# Introduction

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

```text title="Base URL"
https://usd.net/explorer/testnet/api/v1
```

The API serves the explorer at [usd.net/explorer](https://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](/wallet/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](#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](/open-data/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.

```text title="Read message"
USD Network read
Chain: usdnet-1
Address: 0xyouraddress
Until: 1793731653002
```

```ts title="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](/build/errors).
- **Caching.** Sealed blocks are immutable and served with `cache-control: public, max-age=60`. Everything else is `no-store`.

## Pages

:::cards
- [Network](/build/api-network) `/info` and `/stats`
- [Blocks and transfers](/build/api-ledger) `/blocks`, `/block`, `/txs`, `/tx`, `/address`, `/balances`, `/compliance`
- [Checkpoints and proofs](/build/api-proofs) `/checkpoint` and `/proof/…`
- [Submitting](/build/api-write) `POST /tx` and `POST /faucet`
:::
