From 7436717c7a69299542049f97e8d0d861f91557cb Mon Sep 17 00:00:00 2001 From: skyzer Date: Wed, 9 Sep 2026 16:55:15 +0300 Subject: [PATCH] Give wallet funding its own page, and say which chains it accepts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Funding was documented only under third-party payouts, which understated it: the same partner wallet is the ForwardRequest sender for on-ramp bridge-out as well as off-ramp escrow funding. It now has its own page that both flows can point at. The old wording also said a transfer on another chain "cannot fund an order and is not recoverable". That is true of the XAI wallet address and false of the per-chain deposit addresses we monitor and bridge from, so it read as a denial of a service we actually offer. It is now scoped to the address it applies to, alongside the deposit-address path. Document the accepted tokens per chain. They are not uniform — Solana is USDC-only, Tron and TON are USDT-only — and a mismatched send is unrecoverable, so the list ships next to the addresses rather than being left for a partner to infer. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01WGpoBHdy1H255cVJdS9oTi --- api-reference/README.md | 1 + api-reference/funding-your-wallet.md | 69 ++++++++++++++++++++++++++++ api-reference/third-party-payouts.md | 20 ++++---- changelog.md | 9 ++++ 4 files changed, 87 insertions(+), 12 deletions(-) create mode 100644 api-reference/funding-your-wallet.md diff --git a/api-reference/README.md b/api-reference/README.md index 35c941d..ba44880 100644 --- a/api-reference/README.md +++ b/api-reference/README.md @@ -10,6 +10,7 @@ Reference groups: - [User Management](https://unigox.gitbook.io/unigox-api/api-documentation/api-reference/user-management) - [On-Ramp](https://unigox.gitbook.io/unigox-api/api-documentation/api-reference/on-ramp) - [Off-Ramp](https://unigox.gitbook.io/unigox-api/api-documentation/api-reference/off-ramp) +- [Funding your wallet](./funding-your-wallet.md) - [Third-party payouts](./third-party-payouts.md) - [Orders](https://unigox.gitbook.io/unigox-api/api-documentation/api-reference/orders) - [Webhooks](https://unigox.gitbook.io/unigox-api/api-documentation/api-reference/webhooks) diff --git a/api-reference/funding-your-wallet.md b/api-reference/funding-your-wallet.md new file mode 100644 index 0000000..5e65709 --- /dev/null +++ b/api-reference/funding-your-wallet.md @@ -0,0 +1,69 @@ +# Funding your wallet + +Your Unigox partner account is itself an account with a wallet, and that wallet +is what moves crypto on both sides of the API. You top it up in advance; orders +draw it down. + +This page applies to **off-ramp, third-party payouts and on-ramp alike** — the +same wallet, the same address, in every flow: + +- **Off-ramp and third-party payouts.** The wallet signs the transfer into each + order's escrow. It appears as `sender_address` on + `GET /orders/{order_id}/transfer-authorization-parameters`. +- **On-ramp.** The purchased crypto is released to the wallet and bridged out to + your customer from there. It appears as `sender_address` on + `GET /orders/{order_id}/bridge-authorization-parameters`, and any partner + markup you charge is withheld into the same wallet. + +You hold the private key to that wallet: every movement out of it is authorized +by an EIP-712 signature you produce. + +The practical consequence: **an empty balance stops every order**, not just the +next one. Keep the wallet funded ahead of demand. You can read the balance at any +time with `GET /wallet/funding-balance`. + +## The wallet lives on XAI + +`GET /deposit-addresses` returns the wallet address as `funding_wallet_address`. +It does not change, and it is the same address returned as `sender_address` by +the authorization endpoints above — if those two ever disagree, stop and contact +us rather than sending to either. + +That address is on the **XAI** chain. Send only USDC or USDT on XAI to it. A +transfer on any other chain to your XAI address is **not recoverable**. + +The token you fund with must be the token your orders are denominated in: a USDC +order cannot be funded by a USDT balance. + +## Funding from another chain + +You do not have to source USDC on XAI yourself. + +We provision a deposit address for your account on each supported chain and +monitor it. A deposit that lands there is bridged to your XAI wallet +automatically and credited 1:1 with no bridge fee — normally within a minute — +and is spendable as soon as it arrives. + +The same `GET /deposit-addresses` call returns them. Each chain has its own +address, and each accepts only the tokens the endpoint lists against it: + +| Deposit chain | Accepted | +| --- | --- | +| Ethereum, Arbitrum, BSC, Polygon, Optimism, HyperEVM, Unichain | USDC, USDT | +| Base, Avalanche | USDC only | +| Solana | USDC only | +| Tron | USDT only | +| TON | USDT only | + +The token you deposit is the token you receive: deposit USDC and your XAI balance +grows in USDC, deposit USDT and it grows in USDT. + +{% hint style="danger" %} +**A deposit address is not your XAI wallet address, and the two are never +interchangeable.** Sending Solana USDC to your XAI address, or XAI USDC to your +Solana deposit address, is unrecoverable in either direction. Sending a token a +chain does not accept — USDT to Solana, USDC to Tron — is equally unrecoverable. + +Always take the address for the exact chain you are sending from, check it +against the accepted-token list, and send a small test amount first. +{% endhint %} diff --git a/api-reference/third-party-payouts.md b/api-reference/third-party-payouts.md index 74e5da2..0d9278c 100644 --- a/api-reference/third-party-payouts.md +++ b/api-reference/third-party-payouts.md @@ -12,20 +12,16 @@ results for every sender. ## Funding: you pre-fund, we debit Payouts are funded from **your own crypto balance**, not from your customer's. +Your customer never sends crypto to you through Unigox — how they pay you, if at +all, is outside this API. -Your Unigox partner account is itself an account with a wallet. You top that -wallet up with crypto in advance, and every payout your customers make draws -down that balance: the wallet signs the transfer into each order's escrow. Your -customer never sends crypto to you through Unigox — how they pay you, if at all, -is outside this API. +Your partner wallet signs the transfer into each order's escrow, so **an empty +balance stops every payout**, not just the next one. The same wallet funds +on-ramp and off-ramp orders too. -The practical consequence: **an empty balance stops every payout**, not just the -next one. Keep the wallet funded ahead of demand. - -The address is the one on your Unigox wallet page — it does not change, and it -is the same address that appears as `sender_address` on any order's transfer -authorization parameters. Send only the token and chain shown there; a transfer -on another chain cannot fund an order and is not recoverable. +See [Funding your wallet](./funding-your-wallet.md) for the address, the chains +and tokens you can fund from, and the deposit addresses we monitor on your +behalf. ## End-to-end flow diff --git a/changelog.md b/changelog.md index 7098e07..deaf3dc 100644 --- a/changelog.md +++ b/changelog.md @@ -2,6 +2,15 @@ Notable changes to the Unigox partner API, newest first. +## 2026-09-09 + +**You can fund your wallet from another chain, and read the deposit addresses we monitor for you.** Getting USDC onto XAI is no longer your problem. We provision a deposit address for your account on each supported chain and watch it: a deposit is bridged to your XAI wallet automatically, credited 1:1 with no bridge fee, normally within a minute. `GET /api/v1/partner/deposit-addresses` returns the set, with the tokens each chain accepts. + +- Funding was previously described only under third-party payouts, which understated it. The same wallet funds on-ramp and off-ramp orders as well, so it now has its own page: [Funding your wallet](./api-reference/funding-your-wallet.md). +- **The accepted tokens differ per chain, and a mismatch is unrecoverable.** Solana takes USDC only; Tron and TON take USDT only; Base and Avalanche take USDC only; the remaining EVM chains take both. Read the list off the endpoint rather than assuming a chain behaves like its neighbours. +- **A deposit address is not your XAI wallet address.** They are never interchangeable, and a send to the wrong one is unrecoverable in either direction. The previous wording — "a transfer on another chain cannot fund an order and is not recoverable" — remains true of your *XAI wallet address* specifically, and is now stated that way. +- Nothing changes about signing. You still hold the key and still authorize every movement with an EIP-712 signature; this only changes how crypto reaches the wallet. + ## 2026-08-31 **A sender field too long for the payout rail is now refused up front, with the limit in the response.** The rails behind `SENDER_IDENTITY_REQUIRED` cap several sender fields, and they enforce the cap at payout: the whole payment is rejected, after the customer has funded, and the customer sees only that the order was cancelled. A value over the cap is now treated as a field the record could not answer, so `POST /api/v1/partner/offramp/initiate` refuses it while a retry is still free.