API reference

Introduction

One public JSON API for reading USD Network, proving what it contains and submitting transfers.

Base URL
https://usd.net/explorer/testnet/api/v1

The 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

MethodPathReturns
GET/infoChain ID, sequencer key, fee, units
GET/statsHeight, supply, fees, accounts, transfers
GET/blocksRecent blocks, newest first
GET/blocks/latestThe newest block
GET/block/:heightOne block with its transfers (public view)
GET/txsRecent transfers, newest first (public view)
GET/tx/:hashOne transfer: in full to its sender or recipient, else the public view
GET/address/:addressBalance, nonce and recent transfers, signed by that address; else only the frozen flag
GET/balancesLatest signed proof of balances
GET/balances/proof/:addressThat account's leaf and path, signed by that address
GET/checkpointLatest signed checkpoint, as JSON or a signed note
GET/proof/inclusion/:heightInclusion proof for a block
GET/proof/consistencyConsistency proof between two log sizes
GET/complianceFreeze and unfreeze events
GET/bridgeVault balance, bridged supply and signers (proof of bridge)
GET/bridge/eventsBridge movements with attestations
POST/bridge/deposit/quote, /bridge/deposit/sendDeposit from Solana devnet, vault pays the fee
GET/anchorsHourly checkpoint anchors on Solana
GET/witnessesWitnesses and their latest cosignatures
POST/witness/cosignA witness submits a cosignature
POST/txSubmit a signed transfer
POST/faucetMint 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.

Read message
USD Network read
Chain: usdnet-1
Address: 0xyouraddress
Until: 1793731653002
read-pass.ts
import { 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". /info gives the unit (1000000 per USD₮).
  • Addresses are lowercase 0x… strings in responses. Requests accept any case.
  • Hashes of transfers have a 0x prefix. 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 is no-store.

Pages