Business API reference
Every business endpoint - mandates, charges, payouts, partner records, reads - with the exact messages to sign.
Base URLs:
| Network | Base URL |
|---|---|
| Mainnet | https://usd.net/api/v1 |
| Testnet | https://usd.net/explorer/testnet/api/v1 |
Everything is JSON. Amounts are decimal strings in USD₮ with up to 6 decimals. Addresses are lower-case 0x… EVM addresses. Every write is signed with EIP-191 personal_sign by the account it moves money for; there are no API keys. The SDK does all of this for you.
Reads
Reads of an account are signed with a short read pass, x-usd-read: <address>.<until ms>.<signature> over:
USD Network read
Chain: usdnet-1
Address: 0x5b2f…91c0
Until: 1762269000000until at most 15 minutes ahead; reuse the pass until it nearly runs out. See Confidential reads.
Your server wallet
/address/:serverSigned by the server wallet. Its balance, nonce and transactions.
A user's account
/address/:userSigned by your server wallet, with a read: true mandate from that user:
{ "address": "0x7c1e…40ab", "confidential": true, "grant": true, "frozen": false, "balance": "95.01",
"mandate": { "spender": "0x5b2f…91c0", "perTx": "25", "daily": "100", "total": "500", "until": 1767225600000, "read": true,
"spent": "4.99", "dayUsed": "4.99", "leftToday": "95.01", "leftTotal": "495.01", "charges": 1, "active": true },
"transactions": [ /* only those between this user and you */ ] }Without a read grant the answer has no balance ({ address, confidential, frozen }).
A mandate
/mandate/:owner/:spenderSigned by either side. 404 if there is none.
A user's deposit address
/bridge/address/:chain/:userSigned by your server wallet, with a read: true mandate. See Top-ups.
A transaction
/tx/:hashSigned by a party: the full transaction. Otherwise only the public part (that it happened, when, which block).
Charges
/charge{ "from": "0x7c1e…40ab", "to": "0x5b2f…91c0", "amount": "4.99", "fee": "0.01", "id": "order_1042", "memo": "Booster pack", "sig": "0x…" }from is the user, to your server wallet, sig by the server wallet over:
USD Network charge
Chain: usdnet-1
From: 0x7c1e…40ab
To: 0x5b2f…91c0
Amount: 4.99 USDT
Fee: 0.01 USDT
Id: order_1042
Memo: Booster packLeave the Memo: line out when there's no memo. Returns the transaction with idempotent. See Charges.
Payouts
/payout{ "from": "0x5b2f…91c0", "to": "0x7c1e…40ab", "amount": "12.5", "fee": "0.01", "id": "buyback_88", "memo": "Charizard EX", "sig": "0x…" }Signed by from over the same lines with the first line USD Network payout. See Payouts.
Mandates
/mandateSigned by the user (their wallet does this in Connect).
{ "owner": "0x7c1e…40ab", "spender": "0x5b2f…91c0", "perTx": "25", "daily": "100", "total": "500", "until": 1767225600000, "read": true, "partner": "pt_4b8d526f30e5", "nonce": 3, "sig": "0x…" }USD Network mandate
Chain: usdnet-1
Owner: 0x7c1e…40ab
Spender: 0x5b2f…91c0
Per charge: 25 USDT
Per day: 100 USDT
Total: 500 USDT
Until: 1767225600000
Read balance: yes
Partner: pt_4b8d526f30e5
Nonce: 3Total: no limit when total is "0"; leave the Partner: line out without a partner. nonce is the owner's account nonce, like a transfer. Free.
/revoke{ "owner": "0x7c1e…40ab", "spender": "0x5b2f…91c0", "nonce": 4, "sig": "0x…" }USD Network revoke
Chain: usdnet-1
Owner: 0x7c1e…40ab
Spender: 0x5b2f…91c0
Nonce: 4Partners
/partners/:idPublic: { id, name, url, origins, wallets, payTo, network, chain, disabled }. GET /partners?wallet=0x… finds the record a server wallet belongs to.
/partners?owner=:businessWalletSigned by the business wallet: its records, with owner, webhook, created, updated.
/partnersSigned by the business wallet. One envelope for every action:
{ "owner": "0x1d4e…77aa", "action": "create", "data": { "name": "Poké Packs", "url": "https://packs.example.com", "origins": ["https://packs.example.com"], "wallets": ["0x5b2f…91c0"], "webhook": "https://api.example.com/usdnet/webhook" }, "until": 1762268700000, "sig": "0x…" }USD Network partner
Chain: usdnet-1
Owner: 0x1d4e…77aa
Action: create
Data: <hex SHA-256 of the canonical JSON of data>
Until: 1762268700000Canonical JSON: keys sorted, no spaces, undefined left out. until at most 10 minutes ahead; each signed request works once.
action | data | Returns |
|---|---|---|
create | name, url?, origins, wallets (1–5), webhook? | { partner, webhookSecret } (201) |
update | id and any of name, url, origins, wallets, payTo, webhook (null removes), disabled | { partner } |
rotate | id | { partner, webhookSecret }; the old secret stops at once |
test | id | { delivery } after sending a ping |
deliveries | id | { deliveries }, the last 100 attempts |
A server wallet belongs to one record. A business wallet can own up to 10 records.
Limits
| Per minute | |
|---|---|
POST /charge + POST /payout | 1,200 per IP |
POST /tx, /mandate, /revoke | 120 per IP |
POST /partners | 30 per IP |
| Signed reads | 120 new read passes per IP, 30 per address; a pass is checked once and then reused |
429 answers carry retry-after in seconds.
Errors
{ "error": "plain words" } with the HTTP status: 400 malformed, 401 signature doesn't match, 402 not enough USD₮, 403 frozen, no mandate, over a limit or paused, 404 not found, 409 stale nonce or a used request, 429 slow down, 451 sanctions, 5xx try again with the same id.