Introduction
One public JSON API for reading USD Network, proving what it contains and submitting transfers.
https://usd.net/explorer/testnet/api/v1The API serves the explorer at usd.net/explorer and is open to everyone. There are no API keys and no sign-up. CORS allows every origin, so you can call it straight from a browser.
Accounts are confidential: an account's balance, nonce and activity are returned only to a request signed with that account's own key. Everything else (blocks, checkpoints, proofs, supply, the bridge and the compliance log) is public. See Confidential reads.
Endpoints
| Method | Path | Returns |
|---|---|---|
| GET | /info | Chain ID, sequencer key, fee, units |
| GET | /stats | Height, supply, fees, accounts, transfers |
| GET | /blocks | Recent blocks, newest first |
| GET | /blocks/latest | The newest block |
| GET | /block/:height | One block with its transfers (public view) |
| GET | /txs | Recent transfers, newest first (public view) |
| GET | /tx/:hash | One transfer: in full to its sender or recipient, else the public view |
| GET | /address/:address | Balance, nonce and recent transfers, signed by that address; else only the frozen flag |
| GET | /balances | Latest signed proof of balances |
| GET | /balances/proof/:address | That account's leaf and path, signed by that address |
| GET | /checkpoint | Latest signed checkpoint, as JSON or a signed note |
| GET | /proof/inclusion/:height | Inclusion proof for a block |
| GET | /proof/consistency | Consistency proof between two log sizes |
| GET | /compliance | Freeze and unfreeze events |
| GET | /bridge | Vault balance, bridged supply and signers (proof of bridge) |
| GET | /bridge/events | Bridge movements with attestations |
| POST | /bridge/deposit/quote, /bridge/deposit/send | Deposit from Solana devnet, vault pays the fee |
| GET | /anchors | Hourly checkpoint anchors on Solana |
| GET | /witnesses | Witnesses and their latest cosignatures |
| POST | /witness/cosign | A witness submits a cosignature |
| POST | /tx | Submit a signed transfer |
| POST | /faucet | Mint test USD₮ (testnet only) |
Confidential reads
To read your own account, send the header x-usd-read with a read pass: your address, a time in Unix milliseconds no more than 15 minutes ahead, and an EIP-191 personal_sign signature of this message, joined by dots.
USD Network read
Chain: usdnet-1
Address: 0xyouraddress
Until: 1793731653002import { privateKeyToAccount } from 'viem/accounts';
const account = privateKeyToAccount(process.env.KEY as `0x${string}`);
const address = account.address.toLowerCase();
const until = Date.now() + 10 * 60_000;
const message = ['USD Network read', 'Chain: usdnet-1', `Address: ${address}`, `Until: ${until}`].join('\n');
const sig = await account.signMessage({ message });
const res = await fetch(`https://usd.net/api/v1/address/${address}`, {
headers: { 'x-usd-read': `${address}.${until}.${sig}` },
});
console.log(await res.json()); // { balance, nonce, transactions, … }One pass works for every read of that account until it runs out: /address, /tx of a transfer it sent or received, /bridge/out of its withdrawals, /bridge/address of its deposit addresses and /balances/proof. A pass that is expired, too long or signed by another key returns 401. Without a pass, /address returns only { address, confidential, frozen }, and transactions come in their public view: hash, type, status, time and block, plus the amount and the other chain's transaction for deposits and withdrawals.
The protocol's own accounts (the issuer 0x000…000, network fees 0x000…fee00 and the USD Bridge 0x000…b51d6e00) stay public.
Conventions
- Amounts are decimal strings in USD₮, like
"12.5"./infogives the unit (1000000per USD₮). - Addresses are lowercase
0x…strings in responses. Requests accept any case. - Hashes of transfers have a
0xprefix. Block hashes and log hashes are bare lowercase hex. - Times are Unix milliseconds.
- Errors return a non-2xx status with
{ "error": "message" }. See Errors. - Caching. Sealed blocks are immutable and served with
cache-control: public, max-age=60. Everything else isno-store.