Reference

Business API reference

Every business endpoint - mandates, charges, payouts, partner records, reads - with the exact messages to sign.

Base URLs:

NetworkBase URL
Mainnethttps://usd.net/api/v1
Testnethttps://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:

Read message
USD Network read
Chain: usdnet-1
Address: 0x5b2f…91c0
Until: 1762269000000

until at most 15 minutes ahead; reuse the pass until it nearly runs out. See Confidential reads.

Your server wallet

GET/address/:server

Signed by the server wallet. Its balance, nonce and transactions.

A user's account

GET/address/:user

Signed by your server wallet, with a read: true mandate from that user:

JSON
{ "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

GET/mandate/:owner/:spender

Signed by either side. 404 if there is none.

A user's deposit address

GET/bridge/address/:chain/:user

Signed by your server wallet, with a read: true mandate. See Top-ups.

A transaction

GET/tx/:hash

Signed by a party: the full transaction. Otherwise only the public part (that it happened, when, which block).

Charges

POST/charge
Request body
{ "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:

Charge message
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 pack

Leave the Memo: line out when there's no memo. Returns the transaction with idempotent. See Charges.

Payouts

POST/payout
Request body
{ "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

POST/mandate

Signed by the user (their wallet does this in Connect).

Request body
{ "owner": "0x7c1e…40ab", "spender": "0x5b2f…91c0", "perTx": "25", "daily": "100", "total": "500", "until": 1767225600000, "read": true, "partner": "pt_4b8d526f30e5", "nonce": 3, "sig": "0x…" }
Mandate message
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: 3

Total: 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.

POST/revoke
Request body
{ "owner": "0x7c1e…40ab", "spender": "0x5b2f…91c0", "nonce": 4, "sig": "0x…" }
Revoke message
USD Network revoke
Chain: usdnet-1
Owner: 0x7c1e…40ab
Spender: 0x5b2f…91c0
Nonce: 4

Partners

GET/partners/:id

Public: { id, name, url, origins, wallets, payTo, network, chain, disabled }. GET /partners?wallet=0x… finds the record a server wallet belongs to.

GET/partners?owner=:businessWallet

Signed by the business wallet: its records, with owner, webhook, created, updated.

POST/partners

Signed by the business wallet. One envelope for every action:

Request body
{ "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…" }
Partner message
USD Network partner
Chain: usdnet-1
Owner: 0x1d4e…77aa
Action: create
Data: <hex SHA-256 of the canonical JSON of data>
Until: 1762268700000

Canonical JSON: keys sorted, no spaces, undefined left out. until at most 10 minutes ahead; each signed request works once.

actiondataReturns
createname, url?, origins, wallets (1–5), webhook?{ partner, webhookSecret } (201)
updateid and any of name, url, origins, wallets, payTo, webhook (null removes), disabled{ partner }
rotateid{ partner, webhookSecret }; the old secret stops at once
testid{ delivery } after sending a ping
deliveriesid{ 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 /payout1,200 per IP
POST /tx, /mandate, /revoke120 per IP
POST /partners30 per IP
Signed reads120 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.