# 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](/business/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:

```text title="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](/build/api#confidential-reads).

### Your server wallet

:::endpoint GET /address/:server

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

### A user's account

:::endpoint 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

:::endpoint GET /mandate/:owner/:spender

Signed by either side. `404` if there is none.

### A user's deposit address

:::endpoint GET /bridge/address/:chain/:user

Signed by your server wallet, with a `read: true` mandate. See [Top-ups](/business/top-ups).

### A transaction

:::endpoint GET /tx/:hash

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

## Charges

:::endpoint POST /charge

```json title="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:

```text title="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](/business/charges).

## Payouts

:::endpoint POST /payout

```json title="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](/business/payouts).

## Mandates

:::endpoint POST /mandate

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

```json title="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…" }
```

```text title="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.

:::endpoint POST /revoke

```json title="Request body"
{ "owner": "0x7c1e…40ab", "spender": "0x5b2f…91c0", "nonce": 4, "sig": "0x…" }
```

```text title="Revoke message"
USD Network revoke
Chain: usdnet-1
Owner: 0x7c1e…40ab
Spender: 0x5b2f…91c0
Nonce: 4
```

## Partners

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

:::endpoint GET /partners?owner=:businessWallet

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

:::endpoint POST /partners

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

```json title="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…" }
```

```text title="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.

| `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`.
