Give wallet funding its own page, and say which chains it accepts

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)

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 %}

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
 

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.