# Introduction Source: https://usd.net/docs/get-started/introduction > USD Network is a payments network for digital dollars, operated by USD.NET, with native USD₮, fees in dollars and a ledger anyone can verify. USD Network is where digital dollars move. It is a ledger for **USD₮** that settles transfers in about a second, charges its fees in USD₮ rather than a volatile token, and publishes every block so that anyone can check it. It is run by USD.NET as a regulated financial business, not as an anonymous validator network. That choice is deliberate. A payments network has to answer to its users, work with banks and authorities, and stay up. USD.NET takes on that responsibility, while the design keeps the parts that matter verifiable: your keys stay with you, and the ledger is open data. ## What you can do :::cards - [Hold and send dollars](/wallet/overview) A self-custodial wallet protected by a passkey. Send USD₮ to anyone for a flat 0.01 USD₮. - [Bring dollars in](/bridge/overview) Move USD₮ and USDC from Ethereum, Tron, Solana and BNB Chain through the USD Bridge. - [Swap, invest and trade](/swaps/routing) Multi-route swaps across chains, tokenized stocks from Ondo and Hyperliquid perpetuals, from the same wallet. - [Read and verify the ledger](/open-data/overview) A public explorer and API, with signed checkpoints and Merkle proofs anyone can check. ::: ## How it fits together | Part | What it is | Where | | --- | --- | --- | | USD Network | The ledger for USD₮: accounts, transfers, blocks | [Network overview](/network/overview) | | USD₮ | The only asset and the only fee currency on the network | [Native USD₮](/usdt/overview) | | USD Bridge | Vaults on other chains that back bridged supply one to one | [USD Bridge](/bridge/overview) | | Wallet | Passkey-protected keys for USD Network and seven other chains | [usd.net/wallet](https://usd.net/wallet) | | Explorer | Blocks, transfers, checkpoints, proofs, compliance actions | [usd.net/explorer](https://usd.net/explorer) | ## What is live today USD Network **mainnet** (`usdnet-1`) is live with real funds: the ledger, explorer and API, signed checkpoints anchored to Solana every hour, the USD Bridge on Solana, Ethereum and Tron with a deposit address for every account, and the wallet. See [Mainnet](/get-started/mainnet). The **testnet** (`usdnet-testnet-1`) runs the same software with a faucet and test USD₮ that has no value, for building and trying things. Fiat partner flows and independent witnesses are still to come; pages that describe them say so. > [!TIP] > New here? The [Quickstart](/get-started/quickstart) takes about a minute on testnet: create a wallet, get 100 test USD₮ and send some to anyone. --- # Quickstart Source: https://usd.net/docs/get-started/quickstart > Create a passkey wallet, get test USD₮ from the faucet and send your first transfer on USD Network. This takes about a minute and needs nothing but a browser. Everything below happens on testnet, so the dollars are not real. :::steps ### Open the wallet Go to [usd.net/wallet](https://usd.net/wallet) and choose **Create with Face ID** (or Touch ID, Windows Hello or your device PIN, depending on your device). Your browser creates a passkey for usd.net, and the wallet derives its recovery phrase and keys from that passkey, on your device. Nothing secret is sent anywhere or stored by USD.NET. Prefer a recovery phrase? Choose **Create a recovery phrase**: the 12 words appear in one box with **Copy to clipboard**, and the wallet opens once you've saved them. Or choose **Import a recovery phrase** and paste one you have. Either way the wallet is open for this session; to have this device unlock it with Face ID or Touch ID next time, turn that on in **Settings**. ### Back up your recovery phrase The wallet then shows your 12-word recovery phrase. Write it down. It restores the same addresses in this wallet or any standard wallet, and it is your way back in if you ever lose access to your passkey. You can reveal it again at any time under **Settings**. ### Get test USD₮ On the home screen, choose **Get test USD₮**. The faucet mints 100 USD₮ to your USD Network address. Within a second you will see the balance, and the mint appears on the [explorer](https://usd.net/explorer). The faucet allows one request per address every 24 hours. ### Send a transfer Choose **Send**, pick **USD Network**, paste any `0x…` address and an amount, and confirm. The wallet signs the transfer on your device and submits it. The fee is 0.01 USD₮ and it is shown before you sign. The transfer is final as soon as it is sealed into a block, normally in under a second. Open it on the explorer to see the block, its signature and its place in the log. ::: ## What just happened Your wallet signed a plain-text transfer message with your Ethereum-style key, using the same `personal_sign` method every EVM wallet supports. The network checked the signature, your nonce and your balance, sealed the transfer into a signed block, and appended that block to a public Merkle log. [Key concepts](/get-started/key-concepts) explains each of these pieces. ## Next steps :::cards - [Send a transfer from code](/build/first-transfer) The same flow with a script and any EVM private key. - [Verify your transfer](/open-data/verify) Prove your transfer's block is in the signed log. - [How passkeys protect your keys](/wallet/passkeys) What the passkey does and does not protect. - [Testnet limits](/get-started/testnet) Faucet rules, fees and what resets. ::: --- # Key concepts Source: https://usd.net/docs/get-started/key-concepts > The handful of ideas behind USD Network, from accounts and transfers to blocks, checkpoints and issuer controls. ## Accounts An account is an Ethereum-style address (`0x…`) with a USD₮ balance and a nonce. There is no account creation step: an address exists as soon as it receives USD₮. Because addresses are standard, any EVM key or seed phrase already controls a USD Network account. See [Accounts and addresses](/network/accounts). ## Transfers A transfer moves USD₮ from one account to another. The sender signs a short, human-readable message that states the chain, both addresses, the amount, the fee and the nonce. The network accepts the transfer only if the signature recovers to the sender. See [Signing transfers](/build/signing). ## Gas in USD₮ Every transfer pays a flat fee of 0.01 USD₮. There is no separate network token to buy and no fee market to bid in. See [Gas in USD₮](/network/gas). ## Blocks and finality The USD.NET sequencer orders pending transfers, checks them, and seals them into a block. Each block commits to the previous block's hash and is signed with the network's Ed25519 key. A transfer in a sealed block is final: there are no reorganisations. See [Blocks and finality](/network/finality). ## The log and checkpoints Every block hash is appended to an append-only Merkle tree, the same structure used by Certificate Transparency (RFC 9162). A **checkpoint** is a signed statement of the tree's size and root hash. With checkpoints and proofs, anyone can confirm that a block is in the log and that history was never rewritten. See [Checkpoints](/open-data/checkpoints). ## Bridged and issued supply USD₮ reaches USD Network in two ways. It can be **issued** directly on USD Network, or **bridged** from another chain, where it is locked in a public vault. The bridged part is always backed one to one by vault balances you can check yourself. See [How supply is created](/usdt/supply) and [Proof of bridge](/bridge/proof-of-bridge). ## Issuer controls USD₮ is a regulated asset. Its issuer can freeze an address in response to a lawful request, and USD Network enforces that. Every freeze and unfreeze is a public event on the ledger with a reason attached. See [Freezes and lawful requests](/compliance/freezes). ## Self-custody The USD.NET wallet never sees your keys. It derives them from a recovery phrase on your device and protects that phrase with a passkey (or, in browsers whose passkeys can't, a password). USD.NET cannot move your funds. See [Security model](/wallet/security). --- # Mainnet Source: https://usd.net/docs/get-started/mainnet > usdnet-1, the USD Network that holds real dollars, and how it differs from testnet. Mainnet is `usdnet-1`. It runs the same ledger, signatures, blocks, transparency log and proofs as testnet, with one difference that matters: every USD₮ on it is real, minted only when USDC or USD₮ arrives in a USD Bridge vault on another chain, and burned when it leaves. > [!WARNING] > Mainnet balances are real money. Transfers are final after one block and can't be reversed. ## Network details | Field | Mainnet | Testnet | | --- | --- | --- | | Chain ID | `usdnet-1` | `usdnet-testnet-1` | | Explorer | `https://usd.net/explorer` | `https://usd.net/explorer/testnet` | | API | `https://usd.net/api/v1` | `https://usd.net/explorer/testnet/api/v1` | | How USD₮ arrives | USD Bridge deposits only | Faucet and testnet bridge | | Faucet | None | 100 test USD₮ per address per day | | Transfer fee | 0.01 USD₮ | 0.01 USD₮ | `GET /info` on either API returns `network` (`mainnet` or `testnet`) and `chain`. Sign transfers with the chain ID the server returns: a signature made for testnet is not valid on mainnet, and the other way round. The [usd.net wallet](https://usd.net/wallet) reads both from `/info`, so the same address and keys work on either network; switch in Settings → Network. ## What is open | Chain | Assets | Status | | --- | --- | --- | | Solana | USDC, USD₮ | Live | | Ethereum | USDC, USD₮ | Live | | Tron | USD₮ | Live | | BNB Chain | USDC, USD₮ | Live | | Base | USDC | Live | | Arbitrum | USDC, USD₮0 | Live | Chains opened in that order; all six were live on 4 November 2026. If a vault ever runs out of gas, deposits wait safely at your deposit address and are credited once it is refilled, and withdrawals to that chain are refused before anything moves. ## Ethereum One vault address serves every EVM chain: Ethereum, BNB Chain, Base and Arbitrum. Your USD Network address is your Ethereum address, so a deposit credits whoever sent it: no memo. - **USDC without ETH.** The wallet signs an EIP-3009 authorization and the vault submits it, paying the gas. The gas, priced from Chainlink's ETH/USD feed, is shown before you sign and kept from the amount minted. From 2 USDC. - **USDC or USD₮ from your own wallet.** Send it to the vault and pay the gas yourself; the full amount is credited to the sender. Don't send from an exchange: the exchange's address would be credited, not yours. - **Confirmations.** Credit waits for 6 Ethereum blocks, about 75 seconds. - **Withdrawals.** Memo `out:ethereum:<0x address>:usdc` or `:usdt`, from 2 USD₮. The vault keeps the gas it pays, priced live. ## Tron A Tron address is not a USD Network address, so it is linked once: the Tron key signs a message naming the USD Network address to credit (TronLink's `signMessageV2` format), and every USD₮ that Tron address sends to the vault is minted to it. A transfer from an address that isn't linked yet waits and is credited the moment it is linked. The usd.net wallet does the link for you when you swap USD₮ on Tron into USD Network. - **Energy, covered.** A Tron transfer burns TRX for energy (about 6.5 TRX, or 13 when the receiver has never held USD₮). For deposits of 5 USD₮ or more the wallet signs first, then the vault sends that address exactly the TRX the transfer will burn and keeps its cost, priced live, from the amount minted. The figure is shown before you sign. An address that already holds enough TRX pays its own energy and the full amount arrives. One covered deposit per address every 5 minutes. - **Confirmations.** Credit waits for 20 Tron blocks, about a minute, when the block is solid. - **Withdrawals.** Memo `out:tron:`, from 5 USD₮. The vault burns TRX for the energy and keeps what it cost, priced live; sending to an address that has never held USD₮ costs about twice as much. ## Protections - **Sanctions screening.** Deposit senders and withdrawal destinations are checked against OFAC's list of sanctioned digital currency addresses. A deposit from a listed address is held, not minted; a withdrawal to one is refused with `451`. - **Pause.** The operator can pause the bridge. While paused, deposits aren't quoted and withdrawals wait; balances on USD Network are untouched. - **Proof of bridge.** Vault balances are read live from each chain and compared with the bridged supply at [usd.net/explorer/bridge](https://usd.net/explorer/bridge). ## Custody today The vault keys and the three bridge signer keys are held by USD.NET. There are no per-address deposit limits. Moving the vaults to a multisig and the signers to independent operators is the next step, and is published on the proof of bridge page when it happens. --- # Testnet Source: https://usd.net/docs/get-started/testnet > What runs on usdnet-testnet-1, its limits, and how it differs from mainnet. The testnet is `usdnet-testnet-1`. It runs the same ledger, signatures, blocks, log and proofs as [mainnet](/get-started/mainnet), with test USD₮ that has no value. ## Network details | Field | Value | | --- | --- | | Chain ID | `usdnet-testnet-1` | | API | `https://usd.net/explorer/testnet/api/v1` | | Explorer | [usd.net/explorer/testnet](https://usd.net/explorer/testnet) | | Wallet | [usd.net/wallet](https://usd.net/wallet) | | Native asset | USD₮ (test), 6 decimals | | Transfer fee | 0.01 USD₮ | | Faucet | 100 USD₮ per address every 24 hours | | Log origin | `explorer.usd.net/usdnet-testnet-1` | The sequencer's public key is published by `GET /info` as `sequencerKey`. Use it to verify block signatures and checkpoints. ## Faucet `POST /faucet` with `{ "address": "0x…" }` mints 100 test USD₮. Each address can request once every 24 hours, and each IP address once a minute. The wallet's **Get test USD₮** button calls the same endpoint. ## Testnet and mainnet | Capability | Testnet | Mainnet | | --- | --- | --- | | Signed blocks, deterministic finality | Live | Live | | Transfers signed with any EVM key | Live | Live | | RFC 9162 log, signed checkpoints, proofs | Live | Live | | Public explorer and API | Live | Live | | Passkey wallet across 8 networks | Live | Live | | Compliance actions and public log | Live, operator-run | Live, operator-run | | Where USD₮ comes from | Faucet and testnet bridge | USD Bridge only | | USD Bridge | Live on Solana devnet and Base Sepolia (test USDC) | Live on Solana, Ethereum, Tron; BNB Chain, Base, Arbitrum next | | Deposit addresses | Not available | Live on Solana, Ethereum, Tron | | Banking partner on- and off-ramps | Not available | Planned | | Gasless USDC/USDT sends from the wallet | Live (mainnet chains) | Live | | Independent witnesses cosigning checkpoints | Protocol live, programme open | Live | | Checkpoints anchored to public chains | Hourly on Solana | Hourly on Solana, more chains planned | | App-sponsored fees | Not yet | Planned | > [!WARNING] > Testnet state may be reset when the network is upgraded. A reset starts a new chain ID and a new log, so old checkpoints will not verify against it. Never send real funds to a testnet address expecting them to appear on USD Network. --- # Overview Source: https://usd.net/docs/network/overview > USD Network is a ledger built for one job, moving USD₮, operated by a regulated company and open to inspection by anyone. Most blockchains are general-purpose computers that happen to carry dollars. USD Network does one thing: it records who holds USD₮ and moves it between them. Narrowing the job lets the network make promises a payments system needs and a general-purpose chain cannot. ## Design goals - **Dollars in, dollars out.** USD₮ is the only asset and the only fee currency. Nobody has to buy a second token to send money. - **Final means final.** A transfer is either sealed into a block or it is not. There are no probabilistic confirmations and no reorganisations. - **Accountable operation.** USD.NET runs the network as a regulated business, works with banking partners and authorities, and can be held to account. - **Verifiable by anyone, private by default.** Every block and compliance action is public, and every transfer is sealed into it; accounts and amounts are [confidential](/wallet/confidential). The ledger is a transparency log with signed checkpoints and Merkle proofs, and an hourly signed [proof of balances](/open-data/balances). - **Compatible by default.** Accounts are Ethereum-style addresses and transfers are signed with standard `personal_sign`, so existing EVM wallets and keys work. ## What USD Network is not It is not a decentralised network, and it does not claim to be. There is no token, no staking, no validator election and no smart-contract platform. Where decentralisation matters most to users, the design keeps it: users hold their own keys, and the record is open for anyone to check and keep a copy of. ## Components | Component | Role | | --- | --- | | Sequencer | Orders transfers, validates them and seals signed blocks | | Ledger | Accounts, balances, nonces and the full transfer history | | Transparency log | RFC 9162 Merkle tree of block hashes, with signed checkpoints | | USD Bridge | Vaults on Ethereum, Tron, Solana and BNB Chain that back bridged USD₮ | | Fiat gateway | Licensed banking partners for bank transfers in and out | | Explorer and API | Public read access to all of the above | Read [Architecture](/network/architecture) for how they connect. --- # Architecture Source: https://usd.net/docs/network/architecture > How a transfer travels from a signature to a sealed, logged and published block. ## The path of a transfer :::steps ### Sign The sender's wallet builds the transfer message and signs it with the sender's secp256k1 key using EIP-191 `personal_sign`. See [Signing transfers](/build/signing). ### Submit The wallet sends the transfer to `POST /tx`. The API recovers the signer from the signature, and rejects the transfer unless the signer is the sender, the nonce is the account's next nonce, neither party is frozen and the balance covers amount plus fee. ### Sequence Accepted transfers enter the mempool. The sequencer takes a lock, drains the mempool in arrival order and re-checks every transfer against the latest balances, so two transfers can never spend the same dollars. ### Seal The included transfers become a block. The block records its height, the previous block's hash, the time, the transfer hashes, a root over them, the fees collected and the new log size. Its hash is signed with the sequencer's Ed25519 key. ### Log The block hash is appended as a leaf to the transparency log. The log's new root is part of the block itself, and the latest size and root can be fetched at any time as a signed [checkpoint](/open-data/checkpoints). ### Publish The block, its transfers and the updated accounts are immediately readable on the explorer and API. ::: ## Block structure ```json title="GET /block/1" { "height": 1, "prevHash": "88434e65…d799e784", "time": 1793730989320, "txs": [], "txRoot": "4f53cda1…1202b945", "logSize": 2, "logRoot": "f28c233d…c644e19afa", "proposer": "usd.net", "fees": "0", "hash": "ce3d9150…e4d94a12", "sig": "d513cb88…98d1f52105", "transactions": [] } ``` | Field | Meaning | | --- | --- | | `height` | Block number, starting at 0 for genesis | | `prevHash` | Hash of the previous block, all zeros for genesis | | `txs` | Transfer hashes, in the order they were applied | | `txRoot` | SHA-256 of the canonical JSON array of `txs` | | `logSize` | Size of the transparency log once this block is appended | | `logRoot` | Root of the log at `logSize`, so every block is also a log commitment | | `fees` | USD₮ collected in fees in this block | | `hash` | SHA-256 of the block's canonical JSON, see below | | `sig` | Ed25519 signature over the 32 raw bytes of `hash`, by the sequencer key from `GET /info` | To recompute `hash`, take every field except `hash` and `sig`, set `logRoot` to the empty string (the root is computed after the hash), add `"chain": "usdnet-testnet-1"`, and hash the canonical JSON: keys sorted, no whitespace, absent fields omitted. ## Heartbeat blocks Blocks are sealed whenever transfers arrive. When the network is idle, an empty heartbeat block is sealed once an hour so that the log keeps advancing and stale checkpoints are easy to spot. ## Storage The testnet ledger is stored in a replicated Redis database. A block and every account it changes are written in a single multi-key write, and block production is serialised by a lock, so the ledger cannot fork even under concurrent submissions. --- # Blocks and finality Source: https://usd.net/docs/network/finality > Why a transfer on USD Network is final the moment it is sealed, and how you can tell. ## Deterministic finality USD Network has one block producer, the USD.NET sequencer, and blocks are hash-linked: each block names the hash of the one before it. A sealed block is never replaced, so a transfer in a sealed block is final. You do not need to wait for confirmations. A transfer's `status` tells you where it is: | Status | Meaning | | --- | --- | | `pending` | Accepted and waiting to be sealed. On testnet this lasts well under a second. | | `final` | Sealed into the block shown in `block`, at position `index`. | | `failed` | Rejected at sealing time, with the reason in `error`. Nothing moved and no fee was charged. | ## How you can check it Finality is a promise from the operator. The transparency log makes that promise checkable: - Every block's hash is a leaf in an append-only Merkle log. - A [consistency proof](/open-data/consistency-proofs) between any two checkpoints shows that the later log contains the earlier one unchanged. If a block were ever rewritten, no such proof could exist. - An [inclusion proof](/open-data/inclusion-proofs) shows a given block is in the log at a given checkpoint. Checkpoints are also anchored to Solana every hour, and independent witnesses can cosign them, so a rewrite would also have to fool records and parties USD.NET does not control. ## Ordering Transfers are sealed in the order the sequencer received them. Each account's transfers must use consecutive nonces, so a sender's own transfers are always applied in the order they were signed. --- # Gas in USD₮ Source: https://usd.net/docs/network/gas > Every transfer pays a flat 0.01 USD₮ fee. No network token, no fee market, no surprises. On most chains, sending dollars means first buying a different asset to pay for gas, then guessing how much to offer. On USD Network the fee is paid in the same USD₮ you are sending, and it is the same for everyone. ## The fee | Item | Value | | --- | --- | | Fee asset | USD₮ | | Transfer fee | 0.01 USD₮, flat | | Who pays | The sender, on top of the amount | | When it is charged | Only when the transfer is sealed as `final` | If you send 25 USD₮, your balance goes down by 25.01 USD₮ and the recipient receives exactly 25 USD₮. A transfer that fails is not charged. The fee is part of the signed message (`Fee: 0.01 USDT`), so a wallet can always show it before you sign and nobody can change it afterwards. ## Where fees go Fees are credited to the fee collector account `0x00000000000000000000000000000000000fee00`. Its balance and every credit to it are public on the explorer, and each block records the total fees it collected. ## Sponsored fees Planned for mainnet: apps will be able to pay fees on behalf of their users, so a user can receive and send USD₮ without ever thinking about the fee. --- # Accounts and addresses Source: https://usd.net/docs/network/accounts > USD Network uses Ethereum-style addresses, so every EVM key already has a USD Network account. ## Addresses A USD Network address is a 20-byte Ethereum-style address, written as `0x` followed by 40 hex characters. The API lowercases addresses, and the transfer message always uses the lowercase form. Because the address is derived the same way as on Ethereum, the same private key or recovery phrase controls the same address on USD Network, Ethereum, Base, Arbitrum and BNB Chain. In the USD.NET wallet, that is the key at path `m/44'/60'/0'/0/0`. > [!WARNING] > Sending to an address on USD Network is not the same as sending to it on Ethereum. Make sure the recipient expects USD₮ on USD Network. To move dollars between networks, use the [USD Bridge](/bridge/overview). ## Account state Accounts are [confidential](/wallet/confidential). With a [read pass](/build/api#confidential-reads) signed by the account's key, `GET /address` returns its full state: ```json title="GET /address/0x… (with x-usd-read)" { "address": "0x…", "balance": "87.65", "nonce": 1, "frozen": false, "txs": 2, "firstSeen": 1793730989320, "transactions": [ … ] } ``` | Field | Meaning | | --- | --- | | `balance` | USD₮ balance as a decimal string, up to 6 decimals | | `nonce` | The nonce the next transfer from this account must use | | `frozen` | Whether the issuer has frozen the account | | `txs` | Number of sealed transfers involving the account | | `firstSeen` | Time of the first block that touched the account, in milliseconds | An address that has never received USD₮ returns a zero balance and nonce 0. No registration is needed. Without a read pass the response is only `{ "address", "confidential": true, "frozen" }`. ## System addresses | Address | Role | | --- | --- | | `0x0000000000000000000000000000000000000000` | Issuer. The `from` of mints and compliance actions. | | `0x00000000000000000000000000000000000fee00` | Fee collector. Receives every transfer fee. | --- # Fees and limits Source: https://usd.net/docs/network/limits > The numbers that constrain a transfer on USD Network. | Limit | Value | | --- | --- | | Transfer fee | 0.01 USD₮ | | Amount precision | 6 decimals (1 unit = 0.000001 USD₮) | | Smallest transfer | 0.000001 USD₮ | | Memo length | 140 characters | | Transfers per block | Up to 500 | | Heartbeat interval | One empty block an hour when idle | | Faucet (testnet) | 100 USD₮ per address per 24 hours, one request per IP per minute | | New read passes checked | 120 a minute per IP, 30 a minute per address (a pass is checked once, then reused) | | Balance proofs | 20 a minute per IP, 10 a minute per address | | Transfers submitted | 120 a minute per IP | | Deposit checks (`POST /bridge/check`) | 20 a minute per IP | Over a limit, the API answers `429` with a `retry-after` header in seconds. Public reads (`/stats`, `/blocks`, `/txs`, `/block/:height`, `/bridge`, `/checkpoint`, proofs) are served from the edge cache for a few seconds, so polling them is cheap and needs no limit. ## Amounts Amounts are sent and returned as decimal strings, such as `"12.5"` or `"0.000001"`, never as floating-point numbers. Internally, balances are integers of the smallest unit, so there is no rounding. ## Nonces Each transfer must carry the sender's current nonce, which starts at 0 and increases by one with every sealed transfer. A transfer with any other nonce is rejected with status `409`, and the error tells you the expected nonce. Read the current nonce from `GET /address/:address` with a [read pass](/build/api#confidential-reads). ## Memos A memo is optional free text, up to 140 characters, included in the signed message and stored with the transfer. Like the rest of a transfer it is [confidential](/wallet/confidential), but anyone you share a receipt with sees it, and USD.NET can see it. Do not put personal data in it. --- # USD₮ on USD Network Source: https://usd.net/docs/usdt/overview > USD₮ is the only asset on USD Network. It pays for transfers, it is what balances are measured in, and on mainnet every unit is backed one to one in public vaults. USD Network has exactly one asset: USD₮. There is no second token and no network coin. Every balance, amount and fee is in USD₮. > [!NOTE] > USD₮ on USD Network is minted by the USD Bridge, not issued by Tether. On mainnet every unit is minted against USDC or USD₮ locked in a public vault on Solana, Ethereum or Tron, and burned when it is sent out. Issuance by Tether directly on USD Network is not live. ## Properties | Property | Value | | --- | --- | | Symbol | USD₮ | | Decimals | 6 | | Smallest unit | 0.000001 USD₮ | | Fee asset | Yes, the only one | | Operator controls | Freeze and unfreeze under the published policy | | Mainnet | Bridged only: minted against vault deposits | | Testnet | Test USD₮ from the faucet, no value | ## Where USD₮ comes from - **Mainnet (`usdnet-1`)**: only from the [USD Bridge](/bridge/overview). USDC or USD₮ sent to your deposit address on Solana, Ethereum or Tron moves into the vault, and the same amount (less any gas the vault paid) is minted to you. Sending out burns it and the vault releases USDC or USD₮. The bridged supply and every vault balance are compared live on [proof of bridge](/bridge/proof-of-bridge). - **Testnet (`usdnet-testnet-1`)**: from the faucet, which has no value, or from the testnet bridge on Solana devnet and Base Sepolia. `GET /stats` reports the bridged part as `bridged`. On mainnet `supply` equals `bridged`, since nothing else can mint. ## Why one asset A single asset removes whole classes of problems: there is no price risk on fees, no need to hold a gas token, no token approvals and no confusion between look-alike tokens. A balance on USD Network is a dollar balance. --- # How supply is created Source: https://usd.net/docs/usdt/supply > USD₮ enters USD Network by issuance, by bridge deposit or through a banking partner, and leaves the same ways. ## Ways in | Route | What happens | Ledger event | | --- | --- | --- | | Issuance | The issuer mints USD₮ directly on USD Network | `mint` from the issuer address | | Bridge deposit | USD₮ or USDC is locked in a vault on Ethereum, Tron, Solana or BNB Chain | `bridge_in`, linked to the source transaction | | Bank transfer | A banking partner receives dollars and USD₮ is delivered to your address | `mint` or `bridge_in`, depending on the partner flow | | Faucet (testnet only) | 100 test USD₮ per address per day | `mint` with memo `Testnet faucet` | ## Ways out | Route | What happens | Ledger event | | --- | --- | --- | | Bridge withdrawal | USD₮ is burned on USD Network and released from the vault on the destination chain | `bridge_out`, linked to the release transaction | | Bank transfer | A banking partner pays out dollars to your bank account | `bridge_out` or redemption through the issuer | ## Supply on the explorer `GET /stats` reports the network totals: ```json title="GET /stats" { "txCount": 12, "accounts": 4, "supply": "300", "fees": "0.03", "frozen": 0, "bridged": "0", "height": 41, "feeUsdt": "0.01" } ``` `supply` is all USD₮ on the network. `bridged` is the part that came in through the USD Bridge and must be matched by vault balances. The rest is issued supply. --- # Issuer controls Source: https://usd.net/docs/usdt/issuer-controls > USD₮ is a regulated asset. Its issuer can freeze an address under lawful process, and USD Network enforces it in public. USD₮ on every chain carries issuer controls, and USD Network is no different. What is different is that every use of those controls is recorded on the ledger, with a reason, for anyone to see. ## What a freeze does When an address is frozen: - It cannot send USD₮. Transfers from it are rejected with status `403`. - It cannot receive USD₮. Transfers to it are rejected with status `403`. - Its balance stays where it is. A freeze does not move or destroy funds. - Its account shows `"frozen": true` on the explorer and API. An unfreeze reverses all of this. ## Who can freeze Freezes follow USD.NET's published policy and act on requests from law enforcement and other competent authorities, and on USD.NET's own legal obligations as operator. Freezes are not used for commercial reasons. ## Public record Each freeze or unfreeze is a ledger event from the issuer address, sealed into a block like any transfer. It carries a short reason, such as the category of request. The complete list is on the [compliance log](https://usd.net/explorer/compliance) and at `GET /compliance`. Because these events are in the same signed, append-only log as every transfer, they cannot be applied quietly or removed later. See [Freezes and lawful requests](/compliance/freezes) for the process. --- # USD Bridge Source: https://usd.net/docs/bridge/overview > The USD Bridge moves dollars between USD Network and Solana, Ethereum, Tron, BNB Chain, Base and Arbitrum, one to one, against public vaults. Every account has its own deposit address on each chain. > [!NOTE] > Live on mainnet on **Solana**, **Ethereum**, **Tron**, **BNB Chain**, **Base** and **Arbitrum**. The testnet bridge runs on Solana devnet and Base Sepolia with Circle's test USDC: [try it](#try-it-on-testnet). Users of USD Network hold their own keys, so the only place USD.NET ever holds dollars on anyone's behalf is the bridge. That is why the bridge is built to be checked rather than trusted. ## Deposit addresses Every USD Network address has its own deposit address on each bridged chain: one on Solana, one shared by the EVM chains, one on Tron. Find it in the wallet under **Receive**, or from the API with a [read pass](/build/api#confidential-reads) signed by that USD Network address, so nobody else can link the two: ```endpoint GET /bridge/address/{chain}/{usdnetAddress} ``` USDC or USD₮ sent there, from any wallet or exchange, arrives as USD₮ on USD Network. No memo, no link, nothing to sign. The address doesn't change, so it can be saved at an exchange. | Chain | Coins | Smallest amount | Network fee kept | Credited | | --- | --- | --- | --- | --- | | Solana | USDC, USD₮ | 1 | None, the vault pays it | About a minute | | Ethereum | USDC, USD₮ | 2 | The gas the vault pays, priced from Chainlink | After 6 blocks | | Tron | USD₮ | 5 | The TRX the vault sends for energy, priced live | After 20 blocks | | BNB Chain | USDC, USD₮ | 1 | The BNB gas the vault pays, priced from Chainlink | After 15 blocks | | Base | USDC | 1 | The gas the vault pays | After 10 blocks | | Arbitrum | USDC, USD₮0 | 1 | The gas the vault pays | After 20 blocks | Amounts under the smallest wait until more arrives. ## How a deposit works :::steps ### Arrive Dollars land in your deposit address, or come straight from your own wallet: on Solana with the memo `usdnet:`, on Ethereum from your own address (the sender is credited), on Tron from a Tron address you have linked. ### Screen Every sender is checked against OFAC's list of sanctioned digital currency addresses. A listed sender's deposit is held, never minted. ### Sweep and attest The watcher moves the deposit into the vault and 2 of 3 bridge signers attest to it. Today USD.NET runs all three signer keys and the vault keys; moving them to a multisig and independent signers is the next step. ### Mint The same amount, less any network fee the vault paid, is credited on USD Network as a `bridge_in` that records the source chain and transaction. It is now spendable USD₮. ::: ## From the wallet In [usd.net/wallet](https://usd.net/wallet), open **Swap** and pick **USD₮ on USD Network** on one side and USDC or USD₮ on another chain on the other. Moving in uses the wallet's own address on that chain: on Solana, Tron, and for USDC on Ethereum, Base and Arbitrum the vault pays the network fee and keeps it from the amount, so you need no SOL, TRX or ETH. USD₮ on Ethereum and Arbitrum and both coins on BNB Chain are sent from your address, so it needs a little ETH or BNB for gas. Moving out sends to the same address on that chain. Every step is shown with its transaction as it happens. ## How a withdrawal works Send USD₮ to the bridge address with the memo `out::
[:usdc|:usdt]`; the wallet's **Send** (to someone else) and **Swap** (to your own address) do this for you. The USD₮ goes to the bridge, the vault releases it on the destination chain, the signers attest, and it is burned on USD Network as a `bridge_out`. Both legs appear on the explorer as one paired movement. Withdrawals to Ethereum start at 2 and to Tron at 5; the gas or energy the vault pays is kept from the amount. ## Dollar in, dollar out USD₮ and USDC deposited to the bridge are both credited as USD₮ on USD Network, one to one. Withdrawals can be taken in either asset where the vault holds it. Bridge fees, where they apply, are shown before you confirm. ## What you can verify At any time, the total held in the vaults must be at least the bridged supply on USD Network. That invariant is checked live on [usd.net/explorer/bridge](https://usd.net/explorer/bridge). See [Proof of bridge](/bridge/proof-of-bridge). ## Try it on testnet :::steps ### Get devnet USDC Get free test USDC at [faucet.circle.com](https://faucet.circle.com). Choose Solana Devnet or Base Sepolia, and paste the address the wallet shows under **Receive** for that chain. On Base it is your USD Network address. ### Bring it in In [usd.net/wallet](https://usd.net/wallet), switch to testnet in Settings → Network, open **Swap**, choose **Open the testnet bridge**, pick the chain, enter an amount and choose **Bring in**. The vault pays the fee on either chain, so you need no SOL or ETH. On Solana you sign a USDC transfer to the vault with the memo `usdnet:`. On Base you sign an EIP-3009 authorization, which the vault submits. From any other wallet, send USDC to the vault shown on [usd.net/explorer/bridge](https://usd.net/explorer/bridge). On Solana add that memo; on Base no memo is needed, because the sender's address is credited. ### Watch it arrive The bridge reads the deposit from Solana, and two of the three bridge signers attest to it. The same amount is then minted to your address as a `bridge_in`, which links to the Solana transaction. ### Send it out Choose **Send out** with an address on that chain. Your wallet signs a USD Network transfer to the bridge address `0x00000000000000000000000000000000b51d6e00` with the memo `out:solana-devnet:
` or `out:base-sepolia:<0x address>`. The vault releases the USDC, then the amount is burned on USD Network as a `bridge_out`. ::: On testnet, three signer keys attest to every movement, and USD.NET runs all three; at mainnet they are held by independent operators. Deposits are 1 to 1,000 test USDC. You can send out up to the amount you bridged in, so test USD₮ from the faucet can't drain the vault. --- # Proof of bridge Source: https://usd.net/docs/bridge/proof-of-bridge > Vault balances on the source chains are always at least the bridged supply on USD Network. Here is how to check it yourself. USD Network does not publish a proof of reserves for user funds, because there are no pooled user funds to prove: every user holds their own keys. What USD.NET does hold is what sits in the bridge vaults. Proof of bridge shows that this is fully backed. ## The invariant ```text sum of vault balances (Ethereum, Tron, Solana, BNB Chain) ≥ bridged supply on USD Network ``` Both sides are public: - **Vault balances** are token balances of known contract addresses on public chains. Anyone can read them from any node or block explorer. - **Bridged supply** is the `bridged` figure from `GET /stats`, and it equals the sum of all `bridge_in` events minus all `bridge_out` events on the ledger. ## Checking it yourself :::steps ### Read the vaults Take the vault addresses from [usd.net/explorer/bridge](https://usd.net/explorer/bridge) and read their USD₮ and USDC balances on each chain, using a node, Etherscan, Tronscan, Solscan or BscScan. ### Read the bridged supply Call `GET /stats` and take `bridged`. For a stronger check, recompute it from every `bridge_in` and `bridge_out` event in the ledger. ### Compare The vault total must be at least the bridged supply. A shortfall could only come from a movement on one side without its pair on the other, and that would be visible to anyone comparing the two. ### Tie each movement to its pair Every `bridge_in` names its source transaction, and every `bridge_out` names its release transaction. Each one can be matched against the vault's own history on the other chain. ::: ## Why it is enough Issued USD₮ is backed by the issuer's reserves, like USD₮ on every other chain. Bridged dollars are the only liability specific to USD.NET, and proof of bridge covers all of it, continuously, with data neither side can alter alone. > [!NOTE] > On testnet the check runs live against the Solana devnet and Base Sepolia vaults: [usd.net/explorer/bridge](https://usd.net/explorer/bridge) reads their USDC balances from both chains every time the page loads. `GET /bridge` returns the same figures as JSON (`vaults`, `total`, `bridged`, `backed`). Every `bridge_in` and `bridge_out` carries the bridge signers' attestations, which the explorer verifies. --- # Supported chains Source: https://usd.net/docs/bridge/chains > The chains and assets the USD Bridge connects to USD Network at launch. | Chain | Assets in | Credited on USD Network as | Status | | --- | --- | --- | --- | | Solana | USD₮, USDC | USD₮ | **Live on mainnet** | | Ethereum | USD₮, USDC | USD₮ | **Live on mainnet** | | Tron | USD₮ | USD₮ | **Live on mainnet** | | BNB Chain | USD₮, USDC | USD₮ | Next | | Base | USDC | USD₮ | Next | | Arbitrum | USDC, USD₮0 | USD₮ | Next | | Solana devnet (testnet) | Devnet USDC | Test USD₮ | **Live** | | Base Sepolia (testnet) | Test USDC | Test USD₮ | **Live** | Mainnet chains open in the order above. On Ethereum the sender of a deposit is credited (no memo), USDC can come in without ETH, and withdrawals use `out:ethereum:<0x address>:usdc` or `:usdt`. On Tron a sending address is linked to a USD Network address with a signature first, and withdrawals use `out:tron:`. On Solana, withdrawals choose the coin with the memo `out:solana:
:usdc` or `:usdt`; if the address has never held that coin, 0.25 of the amount pays for opening its token account. These are the chains where most dollar stablecoins live today. More can be added later without changing how USD Network works, because each new chain is just another vault in the proof of bridge. ## Moving other assets To bring in something other than USD₮ or USDC, such as ETH or SOL, the wallet first swaps it to a stablecoin on its own chain through a [multi-route swap](/swaps/routing), then bridges the dollars. You see one quote with a guaranteed minimum. ## Token addresses The wallet uses these canonical stablecoin contracts on each chain: | Chain | USD₮ | USDC | | --- | --- | --- | | Ethereum | `0xdAC17F958D2ee523a2206206994597C13D831ec7` | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | | Tron | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | Not supported | | Solana | `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | | BNB Chain | `0x55d398326f99059fF775485246999027B3197955` | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` | | Base | Not supported | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | | Arbitrum | `0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9` (USD₮0) | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` | > [!WARNING] > Stablecoins on BNB Chain use 18 decimals, not 6. Amounts are converted exactly when they are credited on USD Network. --- # Overview Source: https://usd.net/docs/wallet/overview > The USD.NET wallet at usd.net/wallet is self-custodial, opens with a passkey and holds dollars, crypto, stocks and perps across eight networks. The wallet at [usd.net/wallet](https://usd.net/wallet) runs entirely in your browser. It derives your keys on your device, reads balances directly from each network, and signs everything locally. USD.NET never receives your keys and cannot move your funds. ## Networks One recovery phrase controls an address on each of these: | Network | Address type | Derivation path | Send from wallet | | --- | --- | --- | --- | | USD Network | EVM `0x…` | `m/44'/60'/0'/0/0` | Yes | | Ethereum | EVM `0x…` | `m/44'/60'/0'/0/0` | Yes, USDC without ETH | | Base | EVM `0x…` | `m/44'/60'/0'/0/0` | Yes, USDC without ETH | | Arbitrum | EVM `0x…` | `m/44'/60'/0'/0/0` | Yes, USDC without ETH | | BNB Chain | EVM `0x…` | `m/44'/60'/0'/0/0` | Yes | | Tron | `T…` | `m/44'/195'/0'/0/0` | Receive only for now | | Solana | Base58 | `m/44'/501'/0'/0'` | USDC and USDT, without SOL | | Bitcoin | Native SegWit `bc1q…` | `m/84'/0'/0'/0/0` | Receive only for now | These are the standard paths, so the same phrase shows the same addresses in MetaMask, Phantom, TronLink, Sparrow and other wallets. ## What it does - **Home.** Your total in dollars, with your dollars, crypto, stocks and perps on one page, and a prompt to move stablecoins you hold elsewhere onto USD Network. - **Send and receive.** USD₮ on USD Network for 0.01 USD₮, USDC and USDT on Solana and USDC on Ethereum, Base and Arbitrum without holding any SOL or ETH ([Sends without gas](/wallet/gasless)), native coins and other stablecoins on the EVM networks, SOL on Solana, and TRX and USD₮ on Tron (paid in TRX; the wallet shows the energy cost first). Bitcoin from your native SegWit address, with a fast, normal or slow fee. Receive picks the coin and the network, then shows the right address and QR code, including a personal deposit address on Solana, Ethereum and Tron that credits USD Network. - **Swap.** Multi-route quotes across chains and assets, executed from EVM networks. See [Multi-route swaps](/swaps/routing). - **Stocks.** Tokenized US stocks and ETFs from Ondo. See [Tokenized stocks](/swaps/stocks). - **Perps.** Hyperliquid perpetual futures, signed with your own key. See [Perpetuals](/swaps/perps). - **Gifts.** Send dollars as a link anyone can claim. See [Gift links](/wallet/gifts). - **Contacts.** Names for the addresses you pay, on any network, kept on your device. - **Activity.** Every transfer on USD Network, searchable, with a CSV export. - **Settings.** Reveal your recovery phrase, see every address and path, lock or remove the wallet. ## Where balances come from The wallet reads balances straight from public infrastructure: the USD Network API, public RPC nodes for the EVM networks, TronGrid, a public Solana RPC and mempool.space for Bitcoin. Prices come from DefiLlama. None of these see your keys, and USD.NET does not keep a record of your addresses. --- # Passkeys Source: https://usd.net/docs/wallet/passkeys > Your wallet is derived from a usd.net passkey with the WebAuthn PRF extension. Nothing secret is stored, and the wallet follows your passkey to every device. A passkey is a credential your device keeps in its secure hardware and unlocks with Face ID, Touch ID, Windows Hello or your PIN. The USD.NET wallet uses it as the root of your wallet, not just as a login. ## How the wallet comes from the passkey :::steps ### Create the passkey The wallet asks your device to create a passkey for `usd.net`, with the WebAuthn **PRF** extension enabled. ### Ask the passkey for a secret Every time you unlock, the wallet asks the passkey to evaluate its PRF on a fixed input, `SHA-256("usd.net/wallet/prf/v1")`. The authenticator returns 32 secret bytes. The same passkey and the same input always give the same bytes, and nobody without the passkey can compute them. ### Turn the secret into a phrase The wallet hashes those bytes and uses the first 16 bytes as entropy for a standard 12-word BIP39 recovery phrase. ### Derive the keys Your addresses on all eight networks are derived from that phrase with the standard paths. The phrase and keys live only in the page's memory while the wallet is unlocked. ::: The wallet stores only the passkey's public credential ID in your browser, so it knows which passkey to ask for. It stores no secret at all. ## Every device your passkey reaches Passkeys sync through iCloud Keychain, Google Password Manager, 1Password and other managers. Open [usd.net/wallet](https://usd.net/wallet) on any device where your passkey is available, choose **I already have a USD.NET passkey**, and the same wallet opens. ## Supported browsers The PRF extension is needed. It is available in Safari on iOS 18 and macOS 15 or later, and in Chrome on Android and desktop with Google Password Manager or iCloud Keychain passkeys. Where it is not available, use a recovery phrase instead: create or import one, and the wallet locks it in your browser with AES-256-GCM. If the browser's passkeys can't lock it either, a password does, with a key derived by PBKDF2-SHA256 (310,000 iterations). > [!WARNING] > Passkeys are bound to the website they were made on. A passkey created on usd.net opens the wallet only on usd.net. If you delete the passkey from your password manager, the wallet can only be restored with your recovery phrase, so back it up. --- # Recovery phrase Source: https://usd.net/docs/wallet/recovery-phrase > Your 12-word phrase is the full backup of your wallet. You can view and export it at any time, and use it in any standard wallet. Your passkey opens the wallet day to day. The recovery phrase is the backup underneath it: 12 words from the BIP39 English word list that recreate every key the wallet uses. ## Viewing your phrase Open **Settings** in the wallet and choose to reveal the phrase. The wallet asks for your passkey (or, on a password-locked device, your password) before it shows the words. The phrase is displayed on your screen only and is never sent anywhere. ## Writing it down - Write the words on paper, in order, and keep them somewhere safe and private. - Do not store them in a screenshot, email, chat or cloud note. - Anyone who has the words controls your funds, on every network. USD.NET will never ask for them. ## Restoring To restore in the USD.NET wallet, choose **Import a recovery phrase** at [usd.net/wallet](https://usd.net/wallet) and enter the words. Any valid 12- or 24-word phrase works. The wallet opens for that session and saves nothing on the device. To keep it there, choose **Unlock this device with Face ID / Touch ID** in Settings: the wallet creates a small passkey, a *lock key*, whose secret encrypts the phrase in your browser (AES-256-GCM). The lock key holds no wallet of its own and works only on that device. Where the browser's passkeys can't do this, a password locks it instead. To use the same funds in another wallet, import the phrase there. Standard wallets derive the same addresses because the wallet uses standard paths: `m/44'/60'/0'/0/0` for EVM networks and USD Network, `m/44'/195'/0'/0/0` for Tron, `m/44'/501'/0'/0'` for Solana and `m/84'/0'/0'/0/0` for Bitcoin. > [!NOTE] > USD Network balances live on USD Network. Another wallet can hold the keys, but to see and send USD₮ on USD Network it needs to talk to the USD Network API. --- # Sends without gas Source: https://usd.net/docs/wallet/gasless > Send USDC and USDT from your own Solana address, and USDC on Ethereum, Base and Arbitrum, without holding SOL or ETH. The fee comes out of the stablecoin. A stablecoin on Solana or an EVM chain normally can't move unless its wallet also holds that chain's coin for gas. People who only want dollars end up stuck with dollars they can't send. The USD.NET wallet removes that step: USD.NET pays the gas, and you pay a small fee in the stablecoin you are sending. Your funds stay at your own address the whole time. You sign every send on your device. USD.NET only adds its signature as the payer of the network fee. ## Where it works | Network | Tokens | Gas paid by USD.NET in | How | | --- | --- | --- | --- | | Solana | USDC, USDT | SOL | A separate fee payer on the transaction | | Ethereum | USDC | ETH | EIP-3009 authorizations, relayed | | Base | USDC | ETH | EIP-3009 authorizations, relayed | | Arbitrum | USDC | ETH | EIP-3009 authorizations, relayed | On the EVM chains you can still pay the fee in ETH yourself: under **Pay the network fee in**, choose ETH. ## The fee The fee is what the send costs USD.NET in gas, plus 30%, at least 0.01 and rounded up to the next cent. It is shown before you sign and is part of what you sign, so it can't change afterwards. Typical fees, quoted live on 3 November 2026: | Send | Fee | | --- | --- | | Solana, recipient already holds the token | 0.01 | | Solana, recipient's first time holding the token | 0.19 (includes opening their token account, about 0.0015 SOL) | | Base | 0.01 | | Arbitrum | 0.02 | | Ethereum | 0.03, following Ethereum's gas price at the time | If the send fails, nothing is charged. ## How it works on Solana :::steps ### Quote The wallet asks for a quote. The server checks your balance, whether the recipient already has a token account, and the current blockhash. It returns the exact transaction parameters with its own signature over them. ### Build and check The wallet builds the transaction from those parameters with the same code the server uses. It refuses to continue unless the recipient, the token and the amount are exactly what you entered. ### Sign You sign as the owner of your token account. The transaction has two signers. USD.NET is the fee payer. You sign the two transfers: the amount to the recipient, and the fee to USD.NET. ### Co-sign and send The server rebuilds the transaction from the signed parameters and checks that your signature covers exactly those bytes. It adds its signature as fee payer and simulates the transaction on Solana. It broadcasts only if the simulation succeeds. ::: The fee payer can't move your tokens. Only the owner's signature can, and the owner's signature covers the whole transaction. ## How it works on Ethereum, Base and Arbitrum USDC supports EIP-3009 `transferWithAuthorization`: the owner signs a typed message authorizing a specific transfer, and anyone can submit it. :::steps ### Quote The server quotes the fee and picks two random one-time nonces, valid for 15 minutes. ### Sign two authorizations You sign two EIP-712 messages: one sending the amount to the recipient, one sending the fee to the USD.NET relayer. Each names the exact recipient and amount and can be used once. ### Relay The relayer checks both signatures and simulates the transaction. It then submits both authorizations in one Multicall3 transaction, with neither allowed to fail on its own, and pays the gas. ::: The relayer can only submit what you signed. Changing the amount or the recipient makes USDC reject the signature. ## What you trust - **USD.NET can't** move more than you signed, send it somewhere else or reuse a signature. - **USD.NET can** decline to relay, for example while a relayer is being topped up. Your funds stay where they are, and you can always send them with your own SOL or ETH using the recovery phrase in any standard wallet. ## API The wallet calls these endpoints on usd.net. They are public, but every send needs the owner's signature. | Method | Path | Body | | --- | --- | --- | | POST | `/api/relay/solana/quote` | `{ from, to, mint, amount }` (amount in token units) | | POST | `/api/relay/solana/send` | `{ params, token, sig }` (owner signature, base64) | | POST | `/api/relay/evm/quote` | `{ chain, from, to, amount }` with chain `eth`, `base` or `arb` | | POST | `/api/relay/evm/send` | `{ params, token, sigs }` | | GET | `/api/relay/status` | Relayer addresses and their gas balances | --- # Confidential accounts Source: https://usd.net/docs/wallet/confidential > Your balance, activity and transfers on USD Network are private. Receipts prove a payment, and the hourly proof of balances shows every balance is counted. Every account on USD Network is confidential. Your balance, your activity and who you pay are visible to you, in the wallet, and to nobody else on the network. The public explorer shows that a transfer happened, when, and the block that sealed it. It never shows who sent it, who received it or how much. The ledger is still checkable by anyone: every transaction is sealed into a signed block and the public [log](/open-data/checkpoints), witnesses cosign it and it is anchored on Solana, and every hour the sequencer signs a [proof of balances](/open-data/balances) whose total must equal the supply. ## What is private and what is public | | Who can see it | | --- | --- | | Your balance and nonce | You (signed with your key). USD.NET, as the operator | | Your activity: who you paid, who paid you, amounts, memos | You, the other party. USD.NET, as the operator | | That a transaction exists: its hash, time, block, fee | Everyone | | A deposit or withdrawal: amount and the other chain's transaction | Everyone (it's public on that chain anyway). Never your USD Network address | | Freezes and unfreezes, with the address and reason | Everyone, in the [compliance log](/compliance/freezes) | | Total supply, sum of all balances, bridged supply, vault balances | Everyone | A transaction's public hash covers a random 16-byte salt and, for transfers, the sender's signature. Without them the hash can't be matched to a guessed sender, recipient or amount. ## How your wallet reads your account The network answers an account's own reads only when they are signed with its key. Your wallet signs a short read pass (it lasts at most 15 minutes and the wallet renews it) with the same key that signs your transfers. Only the signature leaves the browser. Developers can do the same: see [Confidential reads](/build/api#confidential-reads). ## Receipts To show someone a payment, open it in **Activity**. Each line opens its receipt in the explorer: a link whose part after `#` carries the transaction's own fields. Browsers never send that part to a server. The explorer hashes the fields in your browser and shows them only if they match the transaction's public hash, and checks the sender's signature. So a receipt can't be edited or forged, and it shows nothing else about either account. > [!WARNING] > Anyone with a receipt link sees that one transaction: both addresses, the amount and the memo. Share it only with the person who should. ## Verify your balance **Settings** → **Your account is Confidential** → **Verify my balance**. The wallet fetches its leaf (balance and salt) in the latest snapshot and the sibling hashes and sums on the way to the root, rebuilds the root and total in your browser, and checks them against the snapshot the sequencer signed. It also shows whether the sum of every balance equals the supply. No other account's address is ever sent to you. ## Who else can see accounts USD.NET runs the sequencer, so, like a bank, it can see every account. It discloses account data only where the law requires it, through [lawful requests](/compliance/freezes). An auditor can be given read access with its own key. Hiding accounts from the operator too would take encrypted balances with zero-knowledge proofs or a sequencer inside a secure enclave; both are on the roadmap, not live. What happens on other chains stays public there: a deposit into a USD Bridge vault and a withdrawal to an outside address can be seen on that chain. What is confidential is everything that happens on USD Network itself. > [!NOTE] > Confidential transfers to other accounts may not be permitted in all jurisdictions. You are responsible for complying with your local laws. See the [Terms of Service](https://usd.net/terms#confidential) and [Privacy Policy](https://usd.net/privacy). ## History Accounts became confidential on 4 November 2026. Transactions sealed before then are served in their public view too, but their details were public until that day, so anyone who copied them then still has them. --- # Gift links Source: https://usd.net/docs/wallet/gifts > Send USD₮ as a link that anyone can claim into a new or existing wallet, and take it back while it is unclaimed. A gift link sends dollars to someone who doesn't have a wallet yet, or whose address you don't know. They open the link, create a wallet or unlock theirs, and claim. Until then you can take the dollars back. ## How it works :::steps 1. **Your wallet makes a new key.** In **Gifts**, enter an amount and an optional note. The wallet creates a fresh key in your browser and sends the amount, plus 0.01 USD₮ for the claim's fee, to that key's address on USD Network. 2. **The key goes in the link.** The link looks like `https://usd.net/wallet#gift=…&c=usdnet-1`. Everything after `#` is a URL fragment: browsers never send it to a server, so USD.NET never sees the key. 3. **Whoever opens it claims.** The recipient's wallet signs a transfer from the gift key to their own address. It is final in about a second. ::: | | | | --- | --- | | Smallest gift | 1 USD₮ | | Fees | 0.02 USD₮ in total: 0.01 to fund the gift, 0.01 for the claim | | Where the link is kept | Only on your device, in **Gifts**, and wherever you share it | | Taking it back | Any time before it is claimed, from **Gifts** → **Take back** | > [!WARNING] > A gift link is a bearer key: anyone who has it can claim the dollars. Send it only to the person it is for, over a channel you trust. If you clear your browser before the gift is claimed, the link you shared is the only copy. On the ledger a gift is two ordinary transfers, confidential like any other: one from you to the gift address with the memo `gift`, and one from the gift address to whoever claimed it with the memo `gift claimed` (or `gift returned` when you take it back). --- # Security model Source: https://usd.net/docs/wallet/security > What the wallet protects, what it trusts, and what USD.NET can and cannot do. ## What USD.NET cannot do - See, store or recover your recovery phrase or keys. - Sign a transfer, swap or order on your behalf. - Move your funds on any network. ## What USD.NET can do - Serve the wallet's code from usd.net. Like every web wallet, you trust that this code is what it claims to be. The code runs in your browser, and its network requests are visible in your browser's developer tools. - Apply issuer freezes to USD₮ on USD Network under lawful process. This affects USD₮ on USD Network only, and every freeze is public. See [Issuer controls](/usdt/issuer-controls). ## Threats and protections | Threat | Protection | | --- | --- | | Someone gets your device | The wallet locks, and unlocking needs your biometrics or PIN through the passkey, or your password | | Someone gets a copy of your browser storage | Passkey wallets store no secret. Recovery-phrase wallets store only ciphertext, under a key from the device's passkey lock (or, where passkeys can't do it, from your password via PBKDF2). | | Phishing site | Passkeys only work on usd.net, so a look-alike site cannot use yours | | You lose every device | Restore from your recovery phrase | | USD.NET goes away | Your phrase works in any standard wallet, and the ledger is public | ## Good practice - Back up your recovery phrase on paper the day you create the wallet. - Check the recipient address and network before you send. Transfers are final. - Keep large amounts on a device you control and lock the wallet when you are done. --- # Multi-route swaps Source: https://usd.net/docs/swaps/routing > The wallet asks several liquidity sources for routes across chains and shows you the best ones, with a guaranteed minimum. ## How a swap is quoted When you choose a source asset, a destination asset and an amount, the wallet requests routes from an aggregator that searches bridges and exchanges across many networks. It returns up to a dozen routes, each with: - the amount you will receive and the minimum you are guaranteed, - the steps it takes, such as a swap on one chain and a bridge to another, - the estimated time and the fees along the way. Routes are ordered by what you receive. The default slippage limit is 0.50%. If the market moves further than that before your swap completes, the swap does not go through. ## Executing a swap From Ethereum, Base, Arbitrum and BNB Chain, the wallet executes the route you pick: it requests a token approval if one is needed, then signs and sends each step with your key. You can follow progress in the wallet until the funds arrive. Swaps from Tron, Solana and Bitcoin are quoted but not yet executed from the wallet. ## Dollar routes Moves between dollar stablecoins are where USD Network is designed to be cheapest. At mainnet, moves into and out of USD Network are filled by the [USD Bridge](/bridge/overview) one to one, and stable-to-stable routes between other chains use the cheapest available liquidity. ## Planned route sources More liquidity sources are being added, including providers that route through THORChain, Chainflip and Maya for native Bitcoin and other non-EVM assets. The wallet will compare all of them and show the best routes in one list. > [!NOTE] > Swaps use third-party liquidity and run on public chains, not on USD Network. Network fees on those chains apply and are shown in each route. --- # Tokenized stocks Source: https://usd.net/docs/swaps/stocks > Buy and hold Ondo's tokenized US stocks and ETFs on Ethereum from the same wallet as your dollars. Ondo Global Markets issues tokens that track US stocks and ETFs. The wallet lists them, shows live prices and your holdings, and lets you buy them with a swap. ## Listed tokens | Token | Tracks | | --- | --- | | AAPLon | Apple | | NVDAon | NVIDIA | | TSLAon | Tesla | | MSFTon | Microsoft | | AMZNon | Amazon | | GOOGLon | Alphabet | | METAon | Meta | | COINon | Coinbase | | SPYon | SPDR S&P 500 ETF | | QQQon | Invesco QQQ ETF | ## Buying and selling Choose a stock and **Buy**. The wallet opens a swap from USDC on Ethereum to the token and shows routes as for any other swap. Selling is the same swap in reverse. Tokens are held at your own Ethereum address. ## Eligibility > [!WARNING] > Ondo's tokenized stocks are not offered to US persons or to residents of other restricted jurisdictions. The wallet asks you to confirm you are not a US person before you buy. Token holders do not have shareholder voting rights. Read Ondo's terms before you trade. --- # Perpetuals Source: https://usd.net/docs/swaps/perps > Trade Hyperliquid perpetual futures from the wallet, with orders signed by your own key. The wallet connects to Hyperliquid, an exchange for perpetual futures. Your Hyperliquid account is your wallet's EVM address, and every order is signed locally with your key. ## Funding your account Hyperliquid accounts are funded with USDC on Arbitrum. In **Perps**, choose an amount and the wallet sends that USDC from your Arbitrum address to the Hyperliquid bridge contract, `0x2df1c51e09aecf9cacb7bc98cb1742757f163df7`. The minimum deposit is 5 USDC. Your Hyperliquid balance updates once the deposit is credited, usually within a minute. ## Markets and orders The wallet shows Hyperliquid's markets sorted by volume, with mark price, hourly funding, 24-hour volume and maximum leverage. Orders are market orders, sent as immediate-or-cancel limit orders 1% through the mark price so that they fill at the best available price or not at all. ## Your positions Your account value, margin used and open positions are read from Hyperliquid and refresh as you trade. > [!WARNING] > Perpetual futures use leverage and you can lose your whole margin quickly. Hyperliquid is an independent venue and is not available in every jurisdiction. Only trade what you can afford to lose. --- # Banking partners Source: https://usd.net/docs/fiat/overview > Licensed partners connect USD Network to bank accounts, so dollars can arrive by bank transfer and leave the same way. > [!NOTE] > Bank transfers in and out launch with mainnet. This page describes how they will work. USD Network is built to sit next to the banking system, not around it. Bank transfers in and out are handled by licensed partners, who are responsible for identity checks and for holding fiat. USD.NET connects them to the ledger. ## Partners USD.NET is working with licensed payment and banking providers, including: | Partner | Website | | --- | --- | | Xerof | [xerof.com](https://xerof.com) | | Jeton | [jeton.com](https://jeton.com) | | The Kingdom Bank | [thekingdombank.com](https://thekingdombank.com) | | SGB | [sgb.com](https://sgb.com) | Which partner serves you depends on where you live and how you want to pay. Availability, limits and fees are set by each partner and shown before you confirm. ## Dollars in :::steps ### Choose a partner In the wallet, choose to add dollars by bank transfer. You are shown the partners available to you. ### Verify with the partner The partner checks your identity as its licence requires. USD.NET does not receive your documents. ### Pay You send a bank transfer or card payment to the partner. ### Receive USD₮ The partner delivers the same value in USD₮, less its stated fee, to your USD Network address. The credit is a ledger event, confidential like any other. ::: ## Dollars out You send USD₮ from your wallet to the partner, and the partner pays the dollars to your verified bank account. ## Identity and privacy Identity checks happen only at the fiat edge and only with the partner you choose. The ledger records addresses and amounts, never names. Using USD Network on its own, holding, sending and bridging, does not require an account with USD.NET. --- # Approach Source: https://usd.net/docs/compliance/overview > USD Network stays connected to the regulated world by screening at its edges, enforcing issuer controls and publishing every action it takes. USD.NET operates USD Network as a regulated financial business. Compliance is designed into three places, and kept out of everything else. ## 1. Screening at the edges Dollars enter and leave USD Network through the USD Bridge and through banking partners. Those edges are where the network meets other systems, so that is where screening happens: - Bridge deposits and withdrawals are screened against sanctions lists before they settle. - Banking partners verify the identity of their customers as their licences require. Transfers between USD Network addresses are not routed through an identity check. An ordinary payment between two people is just a signed transfer. ## 2. Issuer controls USD.NET publishes its freeze policy. Where a competent authority requires it, an address can be frozen so it can neither send nor receive. See [Freezes and lawful requests](/compliance/freezes). ## 3. Everything in public Every compliance action is a ledger event, sealed into a signed block and listed on the [compliance log](https://usd.net/explorer/compliance). Nothing is applied quietly, and nothing can be removed from the record later. That makes the use of these powers auditable by anyone, including the people they are used on. ## What USD.NET does not do - It does not hold user funds, other than in the bridge vaults that back bridged supply. - It does not require an account to hold or send USD₮ on USD Network. - It does not sell or share account data. Accounts are [confidential](/wallet/confidential): account data is disclosed only where the law requires it. --- # Freezes and lawful requests Source: https://usd.net/docs/compliance/freezes > How a freeze is requested, applied and recorded, and how to check whether an address is frozen. ## Process :::steps ### Request A law enforcement agency or other competent authority sends a request to USD.NET, the operator of USD Network. ### Review The request is checked for authority, scope and legal basis. Requests that do not meet the bar are refused. ### Apply The address is frozen with a `freeze` event from the issuer address, sealed into the next block. The event carries a short reason, such as the category of request. ### Publish The event appears on the [compliance log](https://usd.net/explorer/compliance) and the account shows `"frozen": true`. ### Release When the legal basis ends, an `unfreeze` event restores the address. It is recorded the same way. ::: ## Checking an address ```bash title="Terminal" curl https://usd.net/explorer/testnet/api/v1/address/0x… ``` The response includes `"frozen": true` or `false`. The full history is at `GET /compliance`, newest first. ## Effects | Action | Frozen sender | Frozen recipient | | --- | --- | --- | | Submit a transfer | Rejected, `403` | Rejected, `403` | | Balance | Unchanged | Unchanged | | Bridge or fiat withdrawal | Not possible | Not applicable | A freeze never moves funds. On testnet, the operator can apply freezes to demonstrate the flow, and they are recorded the same way. ## Contact Authorities can reach the compliance team at **compliance@usd.net**. --- # Overview Source: https://usd.net/docs/build/overview > Build on USD Network with a public HTTP API, standard EVM keys and no SDK required. USD Network is designed so that you need nothing new to build on it. Accounts are EVM addresses, transfers are signed with `personal_sign`, and the network is one JSON API over HTTPS with open CORS. ## What you can build :::cards - [Send payments](/build/first-transfer) Sign and submit USD₮ transfers from a server, a script or a browser. - [Accept payments](/build/receiving) Give each customer an address and watch for transfers to it. - [Read the ledger](/build/api-ledger) Blocks, transfers and accounts, for dashboards, accounting and analytics. - [Verify the ledger](/open-data/verify) Check checkpoints and proofs as an auditor, witness or exchange. ::: ## The basics | | | | --- | --- | | Base URL | `https://usd.net/explorer/testnet/api/v1` | | Chain ID | `usdnet-testnet-1` | | Authentication | None for reads or transfers. Transfers are authorised by their signature. | | Formats | JSON in and out. Amounts are decimal strings. | | CORS | Open to every origin | | Libraries | Any EVM signing library: viem, ethers, web3.py, go-ethereum | ## Getting test USD₮ ```bash title="Terminal" curl -X POST https://usd.net/explorer/testnet/api/v1/faucet \ -H 'content-type: application/json' \ -d '{"address":"0xYourAddress"}' ``` The faucet mints 100 test USD₮ per address every 24 hours. --- # Send your first transfer Source: https://usd.net/docs/build/first-transfer > A complete script that funds a key from the faucet, signs a USD₮ transfer and submits it, in about 30 lines. This example uses [viem](https://viem.sh) and Node 18 or later. Any EVM library that can sign a message works the same way. ```bash title="Terminal" npm install viem ``` ## The script ```js title="send.mjs" import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'; const API = 'https://usd.net/explorer/testnet/api/v1'; const CHAIN = 'usdnet-testnet-1'; const post = (path, body) => fetch(API + path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }) .then(async (r) => ({ status: r.status, body: await r.json() })); // 1. A key. Use your own with PRIVATE_KEY=0x… or let the script make one. const account = privateKeyToAccount(process.env.PRIVATE_KEY || generatePrivateKey()); const from = account.address.toLowerCase(); const to = '0x38496f6877382de8255668ae407f4c0ea2acc0f7'; // 2. Test dollars. await post('/faucet', { address: from }); // 3. The account's next nonce. Accounts are confidential, so the read is signed with the account's key. const until = Date.now() + 10 * 60_000; const pass = `${from}.${until}.${await account.signMessage({ message: ['USD Network read', `Chain: ${CHAIN}`, `Address: ${from}`, `Until: ${until}`].join('\n') })}`; const { nonce } = await fetch(`${API}/address/${from}`, { headers: { 'x-usd-read': pass } }).then((r) => r.json()); // 4. The transfer message, exactly as the network rebuilds it. const transfer = { from, to, amount: '12.5', fee: '0.01', nonce, memo: 'Hello from the docs' }; const message = [ 'USD Network transfer', `Chain: ${CHAIN}`, `From: ${transfer.from}`, `To: ${transfer.to}`, `Amount: ${transfer.amount} USDT`, `Fee: ${transfer.fee} USDT`, `Nonce: ${transfer.nonce}`, ...(transfer.memo ? [`Memo: ${transfer.memo}`] : []), ].join('\n'); // 5. Sign with EIP-191 personal_sign and submit. const sig = await account.signMessage({ message }); const res = await post('/tx', { ...transfer, sig }); console.log(res.status, res.body); ``` ```bash title="Terminal" node send.mjs ``` ## The response A `201` means the transfer was accepted. Because blocks are sealed as transfers arrive, it is normally already final: ```json title="201 Created" { "type": "transfer", "from": "0x1323a980c3e4736108741dacdad57d08e60bd827", "to": "0x38496f6877382de8255668ae407f4c0ea2acc0f7", "amount": "12.5", "fee": "0.01", "nonce": 0, "memo": "Hello from the docs", "time": 1793731653002, "sig": "0x2c96fda2…1ca36b3b0b1c", "hash": "0x85d82a5cd8488ef23a7bf9c63954243d0b2c2ec86496b5d13245d3d0d49e2d63", "status": "final", "block": 5, "index": 0 } ``` Open `https://usd.net/explorer/tx/` to see it. Sending the same signed transfer again returns `409 Expected nonce 1`, because each nonce can be used once. ## Next - [Signing transfers](/build/signing) explains every line of the message. - [Errors](/build/errors) lists what can go wrong and what to do. - [Verify it yourself](/open-data/verify) proves block 5 is in the signed log. --- # Signing transfers Source: https://usd.net/docs/build/signing > The exact transfer message format, and the rules the network applies before it accepts a signature. A USD Network transfer is authorised by an EIP-191 `personal_sign` signature over a short plain-text message. Wallets show the message as it is, so the person signing can read exactly what they are approving. ## The message ```text title="Message" USD Network transfer Chain: usdnet-testnet-1 From: 0x1323a980c3e4736108741dacdad57d08e60bd827 To: 0x38496f6877382de8255668ae407f4c0ea2acc0f7 Amount: 12.5 USDT Fee: 0.01 USDT Nonce: 0 Memo: Hello from the docs ``` Lines are joined with a single newline (`\n`), with no trailing newline. | Line | Rule | | --- | --- | | `USD Network transfer` | Fixed header | | `Chain:` | The chain ID. A signature for one chain is not valid on another. | | `From:` | Sender address, lowercase | | `To:` | Recipient address, lowercase, different from the sender | | `Amount:` | Decimal amount followed by ` USDT`, up to 6 decimals, written exactly as in the request body | | `Fee:` | Must be `0.01 USDT` | | `Nonce:` | The sender's current nonce | | `Memo:` | Optional. Omit the whole line when there is no memo. Up to 140 characters. | > [!WARNING] > The network rebuilds the message from the fields you submit. If `amount` in the body is `"12.50"` but you signed `Amount: 12.5 USDT`, the signature will not match. Use the same string in both places. ## Submitting ```json title="POST /tx" { "from": "0x1323a980c3e4736108741dacdad57d08e60bd827", "to": "0x38496f6877382de8255668ae407f4c0ea2acc0f7", "amount": "12.5", "fee": "0.01", "nonce": 0, "memo": "Hello from the docs", "sig": "0x2c96fda2…1ca36b3b0b1c" } ``` ## What the network checks 1. Both addresses are valid `0x…` addresses and are different. 2. The amount is a positive decimal with at most 6 decimals, and the fee is `0.01`. 3. The signature recovers to `from`. 4. Neither address is frozen. 5. The nonce equals the sender's current nonce. 6. The balance covers the amount plus the fee. Checks 4 to 6 run again when the transfer is sealed, against the balances at that moment. ## Transfer hash The transfer `hash` is `0x` followed by the SHA-256 of the canonical JSON (keys sorted, no whitespace, absent fields omitted) of the chain ID, type, addresses, amount, fee, nonce, memo, time and signature (plus `source` and `attest` on bridge events). The `time` is set by the network when it accepts the transfer, so the hash is known only once the transfer is submitted. It identifies the transfer on the explorer and in blocks. ## Signing in other languages Any library that implements EIP-191 works. In ethers: `await wallet.signMessage(message)`. In web3.py: `Account.sign_message(encode_defunct(text=message), key)`. From a browser wallet: `ethereum.request({ method: 'personal_sign', params: [message, from] })`. --- # Accepting payments Source: https://usd.net/docs/build/receiving > Give a customer an address, watch for a transfer to it, and treat it as paid once it is final. Because transfers are final as soon as they are sealed, accepting USD₮ on USD Network is simpler than on most chains. There are no confirmation counts to tune. ## Pattern :::steps ### Give out an address Use one address per customer or per invoice, derived from your own key. Any EVM derivation works, for example consecutive indexes under `m/44'/60'/0'/0/i`. ### Watch it Poll `GET /address/:address` with a [read pass](/build/api#confidential-reads) signed by that address's key. Accounts are confidential, so without one you get only the frozen flag. The response includes the balance and the most recent transfers, newest first. ### Match the payment Look for a transfer with `"type": "transfer"`, `"to"` equal to your address, `"status": "final"`, and the expected amount. If you asked the payer to include a reference, match it on `memo`. ### Record the hash Store the transfer `hash` and `block`. The hash is permanent and public; the details stay between you and the payer. To prove the payment to a third party, share its [receipt](/wallet/confidential#receipts). ::: ## Example ```js title="watch.mjs" import { privateKeyToAccount } from 'viem/accounts'; const API = 'https://usd.net/explorer/testnet/api/v1'; const CHAIN = 'usdnet-testnet-1'; const account = privateKeyToAccount(process.env.PRIVATE_KEY); // the receiving address's key const address = account.address.toLowerCase(); const seen = new Set(); let pass = { v: '', until: 0 }; async function readPass() { if (pass.until - Date.now() > 60_000) return pass.v; const until = Date.now() + 10 * 60_000; const sig = await account.signMessage({ message: ['USD Network read', `Chain: ${CHAIN}`, `Address: ${address}`, `Until: ${until}`].join('\n') }); pass = { v: `${address}.${until}.${sig}`, until }; return pass.v; } setInterval(async () => { const { transactions } = await fetch(`${API}/address/${address}`, { headers: { 'x-usd-read': await readPass() } }).then((r) => r.json()); for (const t of transactions) { if (t.to !== address || t.status !== 'final' || seen.has(t.hash)) continue; seen.add(t.hash); console.log(`Received ${t.amount} USD₮ from ${t.from} in block ${t.block}`, t.memo ?? ''); } }, 2000); ``` > [!TIP] > Addresses in the API are lowercase. Lowercase your own addresses before comparing them. ## Sweeping To consolidate many deposit addresses, send from each one to your treasury address. Each sweep costs the normal 0.01 USD₮ fee, paid from the swept balance. --- # Introduction Source: https://usd.net/docs/build/api > 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` ::: --- # Network Source: https://usd.net/docs/build/api-network > Static network parameters and live totals. ## Network info :::endpoint GET /info Parameters that do not change while the network runs. Use `sequencerKey` to verify block signatures and checkpoints. ```json title="200 OK" { "chain": "usdnet-testnet-1", "name": "USD Network", "network": "testnet", "storage": "redis", "sequencerKey": "64d1d3120be538bd56f1392fb5c2b4be570af7bbe5bdc7af184713bbcb787a3c", "fee": "0.01", "faucet": "100", "issuer": "0x0000000000000000000000000000000000000000", "feeCollector": "0x00000000000000000000000000000000000fee00", "decimals": 6, "unit": "1000000", "signing": "EIP-191 personal_sign over the transfer message", "log": "RFC 9162 Merkle tree of block hashes, C2SP signed-note checkpoints" } ``` | Field | Meaning | | --- | --- | | `chain` | Chain ID, used in every transfer message | | `sequencerKey` | Ed25519 public key of the sequencer, hex | | `fee` | Transfer fee in USD₮ | | `faucet` | Faucet amount in USD₮ (testnet) | | `issuer` | Address that mints and applies compliance actions | | `feeCollector` | Address that receives fees | | `unit` | Smallest units per USD₮ | ## Network stats :::endpoint GET /stats Live totals, cached at the edge for 5 seconds. ```json title="200 OK" { "txCount": 2, "accounts": 2, "supply": "100", "fees": "0.01", "frozen": 0, "bridged": "0", "height": 5, "time": 1793731653002, "feeUsdt": "0.01", "witnesses": 0, "updatedAt": "2026-11-03T18:47:33.010Z" } ``` | Field | Meaning | | --- | --- | | `txCount` | Sealed ledger events: transfers, mints and compliance actions | | `accounts` | Addresses that have appeared in a sealed block | | `supply` | Total USD₮ on the network | | `fees` | Total fees collected | | `frozen` | Addresses currently frozen | | `bridged` | USD₮ that came in through the USD Bridge, net of withdrawals | | `height` | Height of the newest block | | `time` | Time of the newest block | | `witnesses` | Independent witnesses cosigning checkpoints (0 on testnet) | --- # Blocks and transfers Source: https://usd.net/docs/build/api-ledger > Read blocks, transfers, confidential accounts, proof of balances and compliance events. ## List blocks :::endpoint GET /blocks | Query | Default | Meaning | | --- | --- | --- | | `limit` | 20 | Number of blocks, up to 100 | | `before` | Newest | Start at this height and count down, inclusive. For the next page, pass the lowest height you have minus 1. | Returns an array of blocks, newest first, without their transfers. `GET /blocks/latest` returns just the newest block. ## Get a block :::endpoint GET /block/:height Returns the block and a `transactions` array with every transaction it contains, in order, in their public view (see below). Transfers between accounts show only their hash, status, time, block and fee. Returns `404` if the block does not exist yet. See [Architecture](/network/architecture#block-structure) for every field. ## List transfers :::endpoint GET /txs | Query | Default | Meaning | | --- | --- | --- | | `limit` | 20 | Number of transfers, up to 100 | Returns the most recent sealed events across the network, newest first, in their public view. ## Get a transfer :::endpoint GET /tx/:hash With a [read pass](/build/api#confidential-reads) from its sender or recipient, the whole transaction: ```json title="200 OK" { "type": "transfer", "from": "0x1323a980c3e4736108741dacdad57d08e60bd827", "to": "0x38496f6877382de8255668ae407f4c0ea2acc0f7", "amount": "12.5", "fee": "0.01", "nonce": 0, "memo": "Hello from the docs", "time": 1793731653002, "sig": "0x2c96fda2…1ca36b3b0b1c", "salt": "9b1e04c27d3f8a6650e2b1c4d7a9f031", "hash": "0x85d82a5cd8488ef23a7bf9c63954243d0b2c2ec86496b5d13245d3d0d49e2d63", "status": "final", "block": 5, "index": 0 } ``` | Field | Meaning | | --- | --- | | `type` | `transfer`, `mint`, `freeze`, `unfreeze`, `bridge_in` or `bridge_out` | | `status` | `pending`, `final` or `failed` | | `block`, `index` | Where the event was sealed | | `error` | Present when `status` is `failed` | | `reason` | Present on compliance actions | | `source` | Present on bridge events: `{ chain, tx }` of the other leg | | `salt` | 16 random bytes inside the hash, so a hash can't be matched to a guess of its contents | Mints and compliance actions come `from` the issuer address and have no signature. Anyone else gets the public view: ```json title="200 OK (public view)" { "hash": "0x85d82a5cd8488ef23a7bf9c63954243d0b2c2ec86496b5d13245d3d0d49e2d63", "type": "transfer", "status": "final", "time": 1793731653002, "block": 5, "index": 0, "fee": "0.01", "confidential": true } ``` Deposits (`bridge_in`) and releases (`bridge_out`) also show `amount`, `source` `{ chain, tx }` and `attested`, the bridge signers' verdict; never the account on USD Network. Freezes and unfreezes are public in full. The hash is `0x` + SHA-256 of the canonical JSON of `{ chain, type, from, to, amount, fee, nonce, memo, time, sig, source, attest, salt }` (sorted keys, no whitespace, absent fields left out). A [receipt](/wallet/confidential#receipts) is exactly those fields, so whoever has it can check it against the public hash. ## Get an account :::endpoint GET /address/:address | Query | Default | Meaning | | --- | --- | --- | | `limit` | 50 | Number of recent transfers to include, up to 200 | With a [read pass](/build/api#confidential-reads) signed by that address, returns `address`, `balance`, `nonce`, `frozen`, `txs`, `firstSeen` and `transactions`, the account's recent events in full, newest first. Unknown addresses return a zero balance rather than `404`. See [Accounts and addresses](/network/accounts). Without one it returns only `{ "address", "confidential": true, "frozen" }`. The protocol's own accounts return their `balance` to anyone. ## Proof of balances :::endpoint GET /balances The latest signed snapshot of every balance and the last 24: `head` `{ chain, id, height, time, root, total, count }`, the sequencer's `sig` over it and its `key`, the `supply` at that height and `matches` (whether the total equals it). See [Proof of balances](/open-data/balances). :::endpoint GET /balances/proof/:address With a read pass from that address: the snapshot plus `leaf` `{ address, balance, salt }`, `path` (sibling `h` hash, `s` sum and `left`, from the leaf up) and `included`. An account with no balance at that height isn't in the tree and gets `included: false`. ## Compliance log :::endpoint GET /compliance Returns up to 100 `freeze` and `unfreeze` events, newest first, each with the affected address in `to` and the reason in `reason`. --- # Checkpoints and proofs Source: https://usd.net/docs/build/api-proofs > The signed state of the log, and the Merkle proofs that tie blocks and history to it. ## Latest checkpoint :::endpoint GET /checkpoint ```json title="200 OK" { "origin": "explorer.usd.net/usdnet-testnet-1", "size": 6, "root": "7e9daba34b3fb03b42873d57240bc5071e5dda86dbfb5b428800fb38a5f04d66", "height": 5, "time": 1793731653002, "note": "explorer.usd.net/usdnet-testnet-1\n6\nfp2ro0s/…TWY=\n\n— usd.net 5oGo4ucX…wIgbfMAg=\n", "body": "explorer.usd.net/usdnet-testnet-1\n6\nfp2ro0s/…TWY=\n", "key": "64d1d3120be538bd56f1392fb5c2b4be570af7bbe5bdc7af184713bbcb787a3c" } ``` Add `?format=note` to get just the signed note as `text/plain`: ```note title="GET /checkpoint?format=note" explorer.usd.net/usdnet-testnet-1 6 fp2ro0s/sDtChz1XJAvFBx5d2obb+1tCiAD7OKXwTWY= — usd.net 5oGo4ucXWBCDUHDri5nLDlC10fen2MXRGAmonfOzHTl4Ti5CbuME//WamVJ7KlY4Ip08CiQCo5xYJHABHGzwIgbfMAg= ``` See [Checkpoints](/open-data/checkpoints) for the format. ## Inclusion proof :::endpoint GET /proof/inclusion/:height Proves that block `height` is leaf number `height` in the log at the current size. ```json title="200 OK" { "height": 5, "size": 6, "leaf": "0a89300059b15898b92b9229c7825c07a5ad03342dc1011be872ac537af381de", "root": "7e9daba34b3fb03b42873d57240bc5071e5dda86dbfb5b428800fb38a5f04d66", "path": ["cc9e6b32…8dc32ddd", "74a6b040…"] } ``` `leaf` is the block hash. `path` is the RFC 9162 audit path, from the leaf upwards. Returns `404` if the height is outside the log. ## Consistency proof :::endpoint GET /proof/consistency?from=:m&to=:n | Query | Default | Meaning | | --- | --- | --- | | `from` | | Earlier log size, at least 1 | | `to` | Current size | Later log size | ```json title="200 OK" { "from": 3, "to": 6, "oldRoot": "…", "newRoot": "7e9daba3…a5f04d66", "path": ["…", "…", "…", "…"] } ``` Proves that the log of size `to` begins with the log of size `from`, unchanged. Returns `400` for an invalid range. Compare `oldRoot` with a root you recorded yourself; trusting the one in the response proves nothing. ## Anchors :::endpoint GET /anchors Returns `key` (the anchor key on Solana), `every` (`1h`), `last` and `anchors`: up to 50 by default (`?limit=` up to 500), newest first, each with `size`, `root`, `height`, `at`, `signature` and `slot`. See [Anchors](/open-data/checkpoints#anchors). ## Witnesses :::endpoint GET /witnesses Every registered witness with its `vkey` and `last` cosignature (`size`, `root`, `ts`, `line`). :::endpoint POST /witness/cosign ```json title="Request body" { "size": 6, "line": "— witness.example.org psKCWAAAAABq6kol…" } ``` Accepts a `cosignature/v1` line from a registered witness for the checkpoint of that size, and returns it with `201`. Rejected with `400` when the witness is unknown, the key ID or size doesn't match, the time is more than a day old, or the signature doesn't verify. --- # Submitting Source: https://usd.net/docs/build/api-write > Submit signed transfers and request test USD₮. ## Submit a transfer :::endpoint POST /tx ```json title="Request body" { "from": "0x1323a980c3e4736108741dacdad57d08e60bd827", "to": "0x38496f6877382de8255668ae407f4c0ea2acc0f7", "amount": "12.5", "fee": "0.01", "nonce": 0, "memo": "Hello from the docs", "sig": "0x2c96fda2…1ca36b3b0b1c" } ``` | Field | Required | Meaning | | --- | --- | --- | | `from` | Yes | Sender address | | `to` | Yes | Recipient address | | `amount` | Yes | Decimal USD₮ string, as signed | | `fee` | No | Defaults to `"0.01"`, the only accepted value | | `nonce` | Yes | Sender's current nonce, an integer | | `memo` | No | Up to 140 characters, as signed | | `sig` | Yes | EIP-191 signature of the [transfer message](/build/signing) | Returns `201` with the transfer, usually already `final`. The network seals a block as soon as a transfer is accepted. If the transfer fails when it is sealed, for example because another transfer spent the balance first, it is returned with `"status": "failed"` and an `error`. ## Request test USD₮ :::endpoint POST /faucet ```json title="Request body" { "address": "0x…" } ``` Mints 100 test USD₮ to the address as a `mint` from the issuer, and returns the mint with `201`. Limited to once per address every 24 hours and once per IP address per minute. Testnet only. ## Bridge deposit (testnet) :::endpoint POST /bridge/deposit/quote ```json title="Request body" { "from": "", "to": "0x… (USD Network)", "amount": "25" } ``` For Solana devnet, this returns the exact transfer to sign, `params`, with the vault as fee payer and the memo `usdnet:`, plus a `token`. The transaction is built with the shared builder in `@usd/solana`. For Base Sepolia, send `{ "chain": "base-sepolia", "from": "0x…", "amount": "25" }`. You get back `params` for an EIP-3009 `TransferWithAuthorization` to the vault (domain `USDC`, version `2`, chain 84532), and the vault submits it and pays the gas. :::endpoint POST /bridge/deposit/send ```json title="Request body" { "params": { … }, "token": "…", "sig": "" } ``` The vault adds its signature as fee payer, simulates the transaction and sends it. The deposit is then credited at once. Withdrawals need no special endpoint: they are a normal [signed transfer](/build/signing) to the bridge address with the memo `out:solana-devnet:
` or `out:base-sepolia:<0x address>`. `GET /bridge/out/` returns the release state: `queued`, `waiting`, `released` (with the Solana `signature`) or `unconfirmed`. `POST /bridge/check` with `{ "signature": "…" }`, or `{ "chain": "base-sepolia", "hash": "0x…" }`, asks the bridge to read a deposit right away. --- # Errors Source: https://usd.net/docs/build/errors > Every error the API returns, what causes it and what to do. Errors are returned as a non-2xx status with a JSON body: ```json title="Error" { "error": "Expected nonce 1" } ``` ## Submitting transfers | Status | Error | Cause and fix | | --- | --- | --- | | 400 | `Addresses must be 0x… EVM addresses` | Check `from` and `to` | | 400 | `Sender and recipient are the same` | Send to a different address | | 400 | `Amount must be a positive USDT amount with up to 6 decimals` | Use a decimal string such as `"12.5"` | | 400 | `Fee must be 0.01 USDT` | Send `"fee": "0.01"` and sign `Fee: 0.01 USDT` | | 400 | `Bad nonce` | Nonce must be a non-negative integer | | 400 | `Memo is limited to 140 characters` | Shorten the memo | | 400 | `Send JSON` | The body was not valid JSON | | 401 | `Signature does not match the sender` | The message you signed differs from what the network rebuilt. See [Signing transfers](/build/signing). | | 402 | `Insufficient USDT for amount and fee` | The balance must cover amount plus 0.01 | | 403 | `This address is frozen under the issuer policy` | The sender is frozen. See [Issuer controls](/usdt/issuer-controls). | | 403 | `The recipient address is frozen` | The recipient cannot receive USD₮ | | 409 | `Expected nonce n` | Read the nonce again from `/address` and re-sign | ## Faucet | Status | Error | Cause | | --- | --- | --- | | 400 | `Use a 0x… address` | The address is not valid | | 403 | `This address is frozen` | Frozen addresses cannot receive | | 429 | `Test USDT can be requested once every 24 hours per address` | Wait, or use another address | | 429 | `Please wait a minute between requests` | Rate limit per IP address | | 429 | `Too many requests. Try again in a minute.` | A [rate limit](/network/limits) was hit; wait `retry-after` seconds | ## Reads | Status | Error | Cause | | --- | --- | --- | | 404 | `Block not found` | The height has not been sealed yet | | 404 | `Transaction not found` | Unknown hash, or the transfer was never accepted | | 404 | `Height outside the log` | Inclusion proof for a block that does not exist | | 400 | `Bad range` | Consistency proof with `from` of 0 or above `to` | | 404 | `Unknown endpoint` | Check the path | | 500 | Any | Server error. Retry with backoff. | ## Failed at sealing A transfer can pass submission checks and still fail when it is sealed, if the state changed in between. It is then stored with `"status": "failed"` and one of these errors, and no fee is charged: | Error | Meaning | | --- | --- | | `Frozen address` | One side was frozen before sealing | | `Nonce n is stale, expected m` | Another transfer from the sender was sealed first | | `Insufficient balance` | Another transfer spent the balance first | --- # Build for business Source: https://usd.net/docs/business/overview > Let your users pay, top up and get paid in USD₮ on USD.NET by API, final in under a second, without ever holding their keys. USD.NET for business is for sites and apps that move dollars with their users: games, marketplaces, collectibles, creator tools, subscriptions. A user opens a self-custodial USD.NET wallet with a passkey in seconds, tops it up from any chain, and your server charges, refunds and pays them out in USD₮ on USD.NET by API. Every movement is final in under a second. You never hold a user's keys or their money. Users sign a **mandate** that lets your server charge them up to limits they choose, and revoke it whenever they like. :::cards - [Quickstart](/business/quickstart) Build a pack-opening shop on testnet in 15 minutes - [USD.NET Connect](/business/connect) connect.js: connect a wallet, approve a mandate, pay - [Charges and payouts](/business/charges) Take payments and send refunds, buy-backs and winnings - [Webhooks](/business/webhooks) Hear about every charge, payout and top-up - [API reference](/business/api) Every business endpoint - [Build with AI](/business/ai) Everything an AI agent needs in one file ::: ## The pieces | Piece | What it is | | --- | --- | | **Business wallet** | A normal USD.NET wallet that you open with a passkey. It owns your partner record and is where you sweep revenue. | | **Server wallet** | A key that lives on your server (`USDNET_SERVER_KEY`). It charges users within their mandates, sends payouts and pays the network fee. Made in your browser when you create the partner record and shown once. | | **Partner record** | Your name, the sites allowed to open Connect, your server wallets and your webhook URL. Public except the webhook. `pt_…` | | **USD.NET Connect** | A popup on usd.net, opened by `connect.js` on your site. The user unlocks their wallet there and approves; your page gets the address and the signed result. | | **Mandate** | A user's signed permission for one server wallet to charge them: per charge, per day, optionally in total, until a date. It can also let you see their balance. | | **Charge** | Your server takes an amount from a user, within their mandate. Idempotent by your `id`. | | **Payout** | Your server pays a user: refunds, buy-backs, winnings, cash-outs. No nonce, so send thousands at once. Idempotent by your `id`. | | **Webhooks** | Signed POSTs to your server when a charge, payout, payment, mandate or top-up happens. | ## How a purchase flows :::steps ### The user taps **Connect with USD.NET** Your page calls `USDNet.connect({ partner, mandate })`. The popup shows your name, your verified site and the limits. They approve with Face ID or Touch ID. ### Your server saves their address The popup returns `{ address, mandate }`. You get a `mandate.created` webhook too. ### They top up From any chain or exchange: their own deposit addresses on Solana, Ethereum, Tron, BNB Chain, Base and Arbitrum credit their USD.NET account. You get `user.credited`. ### They buy Your server calls `charge({ user, amount: '4.99', id: 'order_1042' })`. Final in under a second; the pack opens. ### They sell back Your server calls `payout({ user, amount: '12.50', id: 'buyback_88' })`. The USD₮ is in their wallet before the animation ends. ::: ## Costs | | Who pays | Amount | | --- | --- | --- | | Charge | Your server wallet | 0.01 USD₮ network fee | | Payout | Your server wallet | 0.01 USD₮ network fee | | Mandate, revoke | Nobody | Free | | Partner record, webhooks | Nobody | Free | There is no platform fee, no monthly fee and no approval step to start on testnet. ## What users see Their wallet lists every business they connected in **Settings → Connected apps**, with each mandate's limits, what it has charged and a **Revoke** button. Charges show in their Activity as **Paid · charged by an app**, payouts as **Received · from an app**. Their account stays [confidential](/wallet/confidential): the public sees only that a transaction happened. > [!NOTE] > You are responsible for your own product: the rules where your users live, consumer law, refunds and, where they apply, licences and age checks. USD.NET provides the wallet, the network and the API. --- # Quickstart Source: https://usd.net/docs/business/quickstart > A pack-opening shop on USD.NET testnet in 15 minutes - connect, charge, sell back, webhooks. You'll build the core of a collectible-card shop: a user connects their USD.NET wallet, buys a booster pack for 4.99 USD₮ and sells a card back for 12.50 USD₮. Everything runs on **testnet**, where USD₮ is free and has no value. :::steps ### Create your partner record Open [usd.net/wallet/business](https://usd.net/wallet/business), switch to **Testnet** in Settings → Network, and create a partner record with your site (use `http://localhost:3000` while developing) and, optionally, a webhook URL. Save the `.env` it shows: the server key is shown only once. ### Fund the server wallet Your server wallet pays 0.01 USD₮ per charge or payout and needs float for payouts. On testnet, take 100 test USD₮ from the faucet: `POST /faucet { "address": "" }`. ### Add Connect to your page One script tag, one button. ### Charge and pay out from your server With the one-file SDK. ### Handle webhooks Verify the signature, then act on the event. ::: ## 1. Your `.env` ```bash title=".env (from usd.net/wallet/business)" USDNET_NETWORK=testnet USDNET_PARTNER_ID=pt_4b8d526f30e5 USDNET_SERVER_KEY=0x… # secret: never commit it, never send it to a browser USDNET_SERVER_ADDRESS=0x… USDNET_WEBHOOK_SECRET=whsec_… # secret ``` ## 2. Connect a user (browser) ```html title="index.html" ``` The popup checks that `location.origin` is one of your registered sites before it shows anything. Call `connect` from a click, or the browser blocks the popup. > [!WARNING] > Treat the address the page sends you as a claim. Before you rely on it, check on your server that a mandate exists: `await usd.mandate(address)` returns it, or `null`. Your `mandate.created` webhook carries the same. ## 3. Charge and pay out (server) ```bash npm i viem curl -O https://usd.net/sdk/usdnet.mjs ``` ```js title="server.mjs" import { USDNet } from './usdnet.mjs'; const usd = new USDNet({ key: process.env.USDNET_SERVER_KEY, network: process.env.USDNET_NETWORK }); // Buy a pack. The id is yours and makes it safe to retry: the same id never charges twice. export async function buyPack(user, orderId) { const tx = await usd.charge({ user, amount: '4.99', id: `pack_${orderId}`, memo: 'Booster pack' }); if (tx.status !== 'final') throw new Error(tx.error); return openPack(user, orderId); // your game logic } // Buy a card back from the user. export async function sellBack(user, cardId, price) { const tx = await usd.payout({ user, amount: price, id: `buyback_${cardId}`, memo: 'Charizard EX' }); if (tx.status !== 'final') throw new Error(tx.error); return tx.hash; } // What the user has, and what their mandate still allows today const u = await usd.user(user); // { balance, mandate: { leftToday, leftTotal, … }, transactions } ``` Both calls return in well under a second with the transaction already `final` (or `failed` with an `error`). See [Charges and payouts](/business/charges). ## 4. Webhooks ```js title="webhook.mjs (Express)" import express from 'express'; import { USDNet } from './usdnet.mjs'; const app = express(); app.post('/usdnet/webhook', express.raw({ type: 'application/json' }), async (req, res) => { let event; try { event = await USDNet.verifyWebhook(req.body.toString('utf8'), req.get('usdnet-signature'), process.env.USDNET_WEBHOOK_SECRET); } catch { return res.sendStatus(400); } if (await alreadyHandled(event.id)) return res.sendStatus(200); // events can arrive more than once switch (event.type) { case 'mandate.created': await linkUser(event.data.user, event.data.mandate); break; case 'user.credited': await showTopUp(event.data.user, event.data.amount); break; case 'charge.succeeded': await markPaid(event.data.id); break; case 'mandate.revoked': await unlinkUser(event.data.user); break; } res.sendStatus(200); }); ``` Press **Send test event** in usd.net/wallet/business to check your endpoint. See [Webhooks](/business/webhooks). ## 5. Go live Create a partner record on **mainnet** (a mainnet business wallet, your production sites), fund the server wallet with real USD₮, change `USDNET_NETWORK=mainnet` and `USDNet.configure({ network: 'mainnet' })`. Testnet and mainnet signatures never work on each other: each names its chain. --- # Accounts and partner record Source: https://usd.net/docs/business/accounts > Your business wallet, your server wallets and the partner record that ties them to your sites and webhook. ## Two accounts | | Business wallet | Server wallet | | --- | --- | --- | | Where the key lives | Your USD.NET wallet, behind a passkey (or a recovery phrase you keep offline) | Your server's environment, `USDNET_SERVER_KEY` | | What it does | Owns and changes the partner record. Receives swept revenue. | Charges users within their mandates, sends payouts, pays the 0.01 USD₮ fee | | Who signs | You, by hand, in usd.net/wallet/business | Your code, with the SDK | | What to keep in it | Revenue | Enough for today's payouts and fees | Keep the server wallet lean: sweep revenue to the business wallet on a schedule (`usd.transfer({ to: businessWallet, amount })`) and top it up when payouts need more. If the server key ever leaks, the most anyone can take is what the server wallet holds plus what your users' mandates still allow, and you replace it in minutes (below). ## Create a partner record In [usd.net/wallet/business](https://usd.net/wallet/business), with your business wallet open: 1. Enter your **business name** (shown to users in Connect, 2–48 characters) and **website**. 2. Add any **other sites** that may open Connect: staging, `http://localhost:3000` while developing. Origins only, no paths. Up to 10. 3. Add a **webhook URL** (https, a public host name) if you have one now. 4. **Create partner and server wallet**. Your browser makes a new server key, your business wallet signs the record, and you get a `.env` with `USDNET_PARTNER_ID`, `USDNET_SERVER_KEY`, `USDNET_SERVER_ADDRESS` and `USDNET_WEBHOOK_SECRET`. **The key and the secret are shown only once**; USD.NET never sees the key. Each network (testnet, mainnet) has its own records. Switch in Settings → Network. ## What the record holds ```json title="GET /partners/pt_4b8d526f30e5" { "id": "pt_4b8d526f30e5", "name": "Poké Packs", "url": "https://packs.example.com", "origins": ["https://packs.example.com", "http://localhost:3000"], "wallets": ["0x5b2f…91c0"], "payTo": "0x5b2f…91c0", "network": "testnet", "chain": "usdnet-testnet-1", "disabled": false } ``` | Field | Meaning | | --- | --- | | `origins` | Sites allowed to open Connect for you. Connect refuses any other. | | `wallets` | Your server wallets (up to 5). Users' mandates name one of them. | | `payTo` | Where `USDNet.pay` sends one-off payments, and the default spender in `USDNet.connect`. | | `disabled` | Paused: Connect refuses new requests, charges are refused and webhooks stop. Your server wallet can still send payouts and transfers. | The webhook URL and the owner are visible only to the owner. ## Change it Every change is signed by the business wallet: in usd.net/wallet/business (**Edit**, **Pause**, **Rotate webhook secret**), or by API with [`POST /partners`](/business/api#partners). ## Replace a server key Only a server wallet listed on an active partner record can charge. So if a key leaks, or you just rotate keys: 1. Make a new key on your server (`node -e "console.log(require('viem/accounts').generatePrivateKey())"`) and note its address. 2. Move what the old server wallet holds to your business wallet (`usd.transfer`) or let it drain. 3. `POST /partners` `update` with `wallets: [new]`. From that moment the old key can't charge anyone; its mandates are dead. 4. Ask users to connect again: new mandates name the new wallet. Your `mandate.created` webhook tells you who has. In an emergency, **Pause** the record first: every charge is refused at once until you resume. --- # Build with AI Source: https://usd.net/docs/business/ai > Give an AI coding agent everything it needs to build on USD.NET - llms-full.txt, a ready prompt and the rules that matter. These docs are written to be read by AI agents as well as people. Point yours at them and it can build a working integration. | File | What it is | | --- | --- | | [usd.net/docs/llms.txt](https://usd.net/docs/llms.txt) | Index of every page, with a one-line description | | [usd.net/docs/llms-full.txt](https://usd.net/docs/llms-full.txt) | Every page in full, as one Markdown file | | `usd.net/docs/md/.md` | Any single page as Markdown, e.g. [/docs/md/business/api.md](https://usd.net/docs/md/business/api.md) | | [usd.net/sdk/usdnet.mjs](https://usd.net/sdk/usdnet.mjs) | The server SDK, readable source | | [usd.net/sdk/connect.js](https://usd.net/sdk/connect.js) | The browser SDK, readable source | ## A prompt to start with ```text title="Paste into your agent" Read https://usd.net/docs/llms-full.txt, then the "Build for business" pages. We are integrating USD.NET into our app (). Use the server SDK https://usd.net/sdk/usdnet.mjs (download it into our repo) and connect.js in the browser. Build: a "Connect with USD.NET" button that asks for a mandate (perTx , daily , days 30, read: true), a server route that saves the user's address only after checking usd.mandate(address), charges with ids derived from our order ids, payouts for refunds/sell-backs with ids derived from what they pay for, and a webhook route that verifies usdnet-signature against the raw body and is idempotent on event.id. Use testnet (USDNET_NETWORK=testnet) until I say otherwise. Never log or expose USDNET_SERVER_KEY. ``` ## Rules to put in your agent's instructions ```markdown title="CLAUDE.md / AGENTS.md" ## USD.NET - Server SDK: ./lib/usdnet.mjs (from https://usd.net/sdk/usdnet.mjs). Docs: https://usd.net/docs/llms-full.txt - USDNET_SERVER_KEY is a secret: server only, never in client bundles, logs or error messages. - Every charge and payout gets a deterministic id from our own records (order_, refund_, buyback_); never random, so retries are safe. - A charge or payout is done only when the returned tx has status "final". "failed" carries `error`. - Trust the address a browser sends only after `usd.mandate(address)` (or the mandate.created webhook) confirms it. - Webhooks: verify with USDNet.verifyWebhook on the raw body; dedupe on event.id; answer 2xx fast. - Amounts are strings with up to 6 decimals ("4.99"). Never use floats for money. - 403 from charge = no mandate or a limit reached → ask the user to reconnect. 402 = top up. ``` --- # USD.NET Connect Source: https://usd.net/docs/business/connect > connect.js - connect a user's wallet, ask for a spending mandate, take a one-off payment and open wallet pages from your site. USD.NET Connect is a small popup on usd.net that your page opens with `connect.js`. The user unlocks their wallet there (Face ID, Touch ID, a passkey, or a recovery phrase), sees your verified name and exactly what you ask for, and approves. Your page gets the result by `postMessage`; their keys never leave usd.net. ```html ``` Or copy the file and serve it yourself; it has no dependencies (`https://usd.net/sdk/connect.js`, 5 KB). ## USDNet.configure(options) ```js USDNet.configure({ network: 'testnet' }); // 'mainnet' (default) or 'testnet' ``` ## USDNet.connect(options) Returns the user's address and, if you asked for one, the mandate they signed. ```js const { address, network, chain, mandate } = await USDNet.connect({ partner: 'pt_4b8d526f30e5', mandate: { perTx: '25', daily: '100', total: '500', days: 30, read: true }, }); ``` | Option | Required | Meaning | | --- | --- | --- | | `partner` | Yes | Your partner id | | `mandate.perTx` | With `mandate` | Most a single charge may take, USD₮ | | `mandate.daily` | With `mandate` | Most all charges may take in one UTC day | | `mandate.total` | No | Most it may ever take. Leave out for no lifetime limit. | | `mandate.days` | No | How long it lasts, 1–400 days. Default 30. | | `mandate.read` | No | Also let your server see the balance, and the payments between you. Default `false`. | | `spender` | No | Which of your server wallets the mandate names. Default your `payTo`. | | `network` | No | Overrides `configure` | Without `mandate`, the user only shares their address. Ask for limits that match what a user would spend with you: the popup shows them in plain words, and users are more likely to approve modest ones. Connecting again with new limits replaces the old mandate. ```json title="Resolves with" { "address": "0x7c1e…40ab", "network": "testnet", "chain": "usdnet-testnet-1", "mandate": { "hash": "0x…", "spender": "0x5b2f…91c0", "perTx": "25", "daily": "100", "total": "500", "until": 1767225600000, "read": true, "partner": "pt_4b8d526f30e5" } } ``` ## USDNet.pay(options) A one-off payment, no mandate needed: the user signs a transfer to your `payTo` wallet. ```js const { address, tx } = await USDNet.pay({ partner: 'pt_4b8d526f30e5', amount: '4.99', memo: 'order_1042' }); // tx: { hash, amount, memo, to, status: 'final', time } ``` Put your order id in `memo` (up to 140 characters). You also get a `payment.received` webhook with the memo, which is the one to trust: fulfil the order from the webhook or after checking `GET /tx/:hash` on your server, never from the page alone. ## USDNet.open(page) Opens the user's own wallet in a window: `'receive'`, `'send'`, `'swap'`, `'bridge'`, `'activity'`, `'settings'`, or `'topup'` (Swap, set to USD₮ on USD.NET). Use it for a "Top up" or "Withdraw" button; nothing comes back to your page. ```js document.querySelector('#topup').onclick = () => USDNet.open('topup'); ``` To show deposit addresses inside your own UI instead, see [Top-ups](/business/top-ups). ## Errors `connect` and `pay` reject with an `Error` whose `code` is: | `code` | Meaning | | --- | --- | | `cancelled` | The user closed the popup or pressed Cancel | | `popup_blocked` | Called outside a click, or the browser blocks popups | | `bad_request` | Missing `partner` or a bad page name | | `failed` | USD.NET couldn't complete it; `message` says why | If your site isn't one of your partner record's `origins`, the popup says so and returns nothing at all. ## How it stays safe - The popup reads your partner record from USD.NET and refuses unless `location.origin` of the opening page is registered to you; it answers only that origin. - Users see your name, your site with a **verified** mark, and every permission in plain words before they sign. - What the user signs is a USD Network message naming your server wallet, the limits and the chain; your page receives only the result. --- # Mandates Source: https://usd.net/docs/business/mandates > The permission a user signs that lets your server wallet charge them, within limits, until a date - and optionally see their balance. A mandate is the user's own signed permission, recorded on USD Network, for **one** of your server wallets to charge **their** account. The network enforces its limits on every charge; you can't go over them and neither can anyone holding your server key. ## What a mandate holds | Field | Meaning | | --- | --- | | `spender` | The server wallet allowed to charge | | `perTx` | Most one charge can take | | `daily` | Most all charges can take in one UTC day | | `total` | Most it can ever take; `"0"` means no lifetime limit | | `until` | When it ends (ms since 1970), at most 400 days ahead | | `read` | Whether that server wallet may read the account's balance and the payments between them | | `partner` | Your partner id, so the user's wallet shows your name | Rules: `perTx ≤ daily`, and `daily ≤ total` when there is a total. An account can hold up to 50 mandates, one per spender; a new one for the same spender replaces the old and starts its counters again. ## How users give one With [USD.NET Connect](/business/connect): `USDNet.connect({ partner, mandate: { … } })`. The user sees, for example: > Charge you up to **25 USD₮** at a time, **100 USD₮** a day, **500 USD₮** in total, for 30 days > See your USD₮ balance, and the payments between you and Poké Packs. Nothing else. Wallets and scripts can also sign one directly (`POST /mandate`, the [mandate message](/business/api#signed-messages)). ## Check one ```js const m = await usd.mandate(user); // null if none, or revoked // { spender, perTx: "25", daily: "100", total: "500", until, read: true, // spent: "4.99", dayUsed: "4.99", leftToday: "95.01", leftTotal: "495.01", charges: 1, active: true } ``` `GET /mandate/:owner/:spender`, signed by either side (`x-usd-read`). Your server wallet's read pass works for every mandate that names it, with or without `read`. ## When it ends - The user presses **Revoke** in Settings → Connected apps: a `revoke` transaction, final at once. You get `mandate.revoked`. - `until` passes. - You remove the server wallet from your partner record, or pause the record. After that, charges answer `403` and, if it had `read`, reads of the account return nothing. ## Reading a user's account With `read: true`, your server wallet can read: ```js const u = await usd.user(user); // { address, grant: true, balance: "95.01", frozen: false, mandate: { … }, transactions: [ only those between them and you ] } ``` …and their [deposit addresses](/business/top-ups) on other chains. It never sees anything else in their account: other payments, other businesses, other balances. ## Good practice - Ask for what you need. A pack shop with packs at 4.99 asks for maybe 25 per charge and 100 a day, not 10,000. - Show users what they've allowed and link to `usd.net/wallet/settings` to revoke. - When a charge fails with `403` because a limit is reached, ask the user to connect again with new limits. --- # Charges Source: https://usd.net/docs/business/charges > Take USD₮ from a user who gave you a mandate. Idempotent, final in under a second, no nonce. A charge moves USD₮ from a user's account to your server wallet, within the user's [mandate](/business/mandates). Your server signs it with the server key. The network checks the mandate, the limits and the balance, and seals it into a block before it answers. ```js const tx = await usd.charge({ user: '0x7c1e…40ab', amount: '4.99', id: 'pack_1042', memo: 'Booster pack' }); // { hash, type: 'charge', status: 'final', from: user, to: server, amount: '4.99', fee: '0.01', id: 'pack_1042', block, time, idempotent: false } ``` | Field | Meaning | | --- | --- | | `user` | The account to charge | | `amount` | USD₮, up to 6 decimals, written plainly (`"4.99"`, not `"4.990"`) | | `id` | Your unique id for this payment, 1–64 characters: letters, digits, `_ - : .` | | `memo` | Optional, up to 140 characters. The user sees it in their Activity. | The user pays `amount`. Your server wallet receives `amount` and pays the 0.01 USD₮ fee from it, so you net `amount − 0.01`. ## Idempotency Your `id` makes retries safe. Send the same `id` again (after a timeout, a crash, a double click) and you get back the transaction it already made, with `"idempotent": true` and HTTP `200` instead of `201`. Nothing is charged twice. Ids are remembered for 400 days per server wallet. A charge that **failed** keeps its id too: retrying it returns the same failure. Use a new id for a new attempt, e.g. `pack_1042_2`. ## Results | HTTP | `status` | Meaning | | --- | --- | --- | | `201` | `final` | Done. Deliver the goods. | | `200` | either | A repeat of an id you used; this is the original result | | `201` | `failed` | Accepted, but the block refused it (someone spent the balance a moment earlier); `error` says why | | `402` | | The user doesn't have enough USD₮, or your server wallet can't pay the fee | | `403` | | No active mandate, a limit is reached, the partner is paused, or the wallet isn't on a partner record | | `401` | | The signature doesn't match your server wallet | | `400` | | Malformed (amount, id, memo) | Errors carry `{ "error": "…" }` in plain words, e.g. `Over the mandate's daily limit (20.01 USD₮ left today)`. ## Many at once Charges have no nonce: send as many in parallel as you like, from one or several servers. The limit is 1,200 charges and payouts a minute per IP; ask us if you need more. ## A purchase, end to end ```js app.post('/api/packs/:sku/buy', async (req, res) => { const user = await sessionUser(req); // address saved at connect const order = await db.orders.create({ user: user.id, sku: req.params.sku, price: '4.99' }); try { const tx = await usd.charge({ user: user.address, amount: order.price, id: `order_${order.id}`, memo: 'Booster pack' }); if (tx.status !== 'final') return res.status(402).json({ error: tx.error }); await db.orders.paid(order.id, tx.hash); res.json({ cards: await openPack(order) }); } catch (e) { if (e.status === 403) return res.status(403).json({ error: e.message, reconnect: true }); // limits reached or revoked if (e.status === 402) return res.status(402).json({ error: 'Top up your USD.NET wallet', topup: true }); throw e; } }); ``` --- # Payouts, refunds and buy-backs Source: https://usd.net/docs/business/payouts > Pay users from your server wallet - refunds, card buy-backs, winnings, cash-outs - idempotent and in parallel. A payout sends USD₮ from your server wallet to any USD.NET account. It works like a transfer, with two differences built for servers: **no nonce**, so you can send thousands at once, and an **id**, so the same payout is never sent twice. The user needs no mandate to receive. ```js const tx = await usd.payout({ user: '0x7c1e…40ab', amount: '12.5', id: 'buyback_card_88', memo: 'Charizard EX' }); // { type: 'payout', status: 'final', amount: '12.5', fee: '0.01', id: 'buyback_card_88', … } ``` Your server wallet pays `amount + 0.01`. The user receives `amount`, final in under a second, and sees **Received · from an app** with your memo. ## Refunds There's no separate refund call: a refund is a payout with an id that points at the charge. ```js await usd.payout({ user, amount: order.price, id: `refund_${order.id}`, memo: `Refund for order ${order.id}` }); ``` Using `refund_` as the id means an order can only ever be refunded once, whatever your retry logic does. ## Buying cards back ```js app.post('/api/cards/:id/sell', async (req, res) => { const user = await sessionUser(req); const card = await db.cards.lockForSale(req.params.id, user.id); // removes it from the user's collection const price = await priceOf(card); // e.g. "12.5" const tx = await usd.payout({ user: user.address, amount: price, id: `buyback_${card.id}`, memo: card.name }); if (tx.status !== 'final') { await db.cards.unlock(card.id); return res.status(409).json({ error: tx.error }); } res.json({ paid: price, hash: tx.hash }); }); ``` ## Winnings and cash-outs in bulk ```js const results = await Promise.all(winners.map((w) => usd.payout({ user: w.address, amount: w.prize, id: `prize_${round}_${w.id}` }))); ``` ## Results Same as [charges](/business/charges#results): `201 final`, `200` for a repeat id, `201 failed` with an `error`, `402` when the server wallet can't cover `amount + 0.01`, `403` for a frozen address. ## Transfers For anything that isn't a user payment, use a plain transfer: sweeping to your business wallet, or withdrawing to another chain through the USD Bridge (`memo: "out::
"`). The SDK's `usd.transfer({ to, amount, memo })` handles the nonce and sends them one at a time. --- # Top-ups Source: https://usd.net/docs/business/top-ups > How users add USD₮ to their USD.NET account - deposit addresses on six chains, swaps, transfers - and how you hear about it. A user's USD.NET account can be topped up four ways. All of them land as USD₮ on USD.NET in the user's own account, and, if their mandate has `read: true`, you get a `user.credited` webhook. | Way | What the user does | Arrives | | --- | --- | --- | | **Deposit address** | Sends USDC or USD₮ to their own address on Solana, Ethereum, Tron, BNB Chain, Base or Arbitrum, from any wallet or exchange | About a minute on Solana; after confirmations elsewhere | | **Swap** | In their wallet, swaps any coin on any of those chains (or Bitcoin) into USD₮ on USD.NET | Depends on the route; the wallet shows it | | **Transfer** | Another USD.NET user, or you, sends them USD₮ | Under a second | | **Fiat** | Through a banking partner, where available | See [Banking partners](/fiat/overview) | ## Show deposit addresses in your own UI With a `read: true` mandate your server can fetch the user's deposit address on any open chain: ```js const d = await usd.depositAddress(user, 'solana'); // { chain: 'solana', address: '7xK…', assets: ['USDC', 'USDT'], min: '1', arrives: 'about a minute' } ``` `GET /bridge/address/:chain/:user`. Chains on mainnet: `solana`, `ethereum`, `tron`, `bnb`, `base`, `arbitrum`; on testnet `solana-devnet` and `base-sepolia`. The address belongs to that user only; anything sent to it is credited to their account. Show the minimum: smaller deposits wait until the total reaches it. > [!WARNING] > Never ask users to send to your server wallet's own deposit addresses: that would credit you, not them. Always fetch the address for the user. ## Or open their wallet ```js USDNet.open('topup'); // their wallet's Swap, set to USD₮ on USD.NET USDNet.open('receive'); // their deposit addresses and QR codes ``` ## Hear about it ```json title="user.credited" { "type": "user.credited", "data": { "user": "0x7c1e…40ab", "type": "bridge_in", "amount": "50", "balance": "95.01", "hash": "0x…", "source": { "chain": "solana", "tx": "5Kf…" }, "time": 1762268400000, "block": 18231 } } ``` `balance` is their balance right after the credit. Use it to unlock a "Buy" button the moment money arrives. Payouts you send yourself don't trigger `user.credited` (you get `payout.succeeded`). ## Cashing out Users withdraw with their own wallet (Send → another chain), at any time. You can link them there with `USDNet.open('send')`. --- # Webhooks Source: https://usd.net/docs/business/webhooks > Signed events for every charge, payout, payment, mandate and top-up - payloads, signature checks in Node and Python, retries. Set a webhook URL on your partner record (https, a public host name) and USD.NET POSTs an event to it within a second of each block that concerns you. ## Events | `type` | When | | --- | --- | | `charge.succeeded` / `charge.failed` | A charge from your server wallet was sealed or refused by the block | | `payout.succeeded` / `payout.failed` | A payout from your server wallet | | `payment.received` | A user (or anyone) transferred USD₮ to one of your server wallets, e.g. `USDNet.pay` | | `transfer.sent` | A transfer from one of your server wallets (a sweep, a bridge withdrawal) | | `mandate.created` | A user gave one of your server wallets a mandate (or replaced one) | | `mandate.revoked` | A user revoked it | | `user.credited` | USD₮ arrived in the account of a user whose mandate lets you read it: a deposit, a transfer, a payout from someone else | | `ping` | **Send test event** in usd.net/wallet/business | ## Payload ```json title="POST https://api.example.com/usdnet/webhook" { "id": "evt_6f1c9b2a40de8e7f3a1c55b2", "type": "charge.succeeded", "created": 1762268401234, "network": "mainnet", "chain": "usdnet-1", "partner": "pt_4b8d526f30e5", "data": { "hash": "0x9a…", "type": "charge", "status": "final", "from": "0x7c1e…40ab", "to": "0x5b2f…91c0", "user": "0x7c1e…40ab", "amount": "4.99", "fee": "0.01", "id": "order_1042", "memo": "Booster pack", "block": 18230, "time": 1762268401100 } } ``` `data` holds the transaction (`hash`, `type`, `status`, `from`, `to`, `amount`, `fee`, `memo`, `id`, `block`, `time`, `error`), `user` (the other side), and `mandate` on mandate events. Headers: | Header | Value | | --- | --- | | `usdnet-signature` | `t=,v1=` | | `usdnet-event` | The event type | | `usdnet-delivery` | The event id, the same on every retry | | `user-agent` | `USD.NET-Webhooks/1` | ## Check the signature The signature is an HMAC-SHA256, keyed with your webhook secret (`whsec_…`), of `"."`. Check it against the **raw** body, before parsing, and reject timestamps more than 5 minutes off. ```js title="Node (SDK)" const event = await USDNet.verifyWebhook(rawBody, req.headers['usdnet-signature'], process.env.USDNET_WEBHOOK_SECRET); ``` ```js title="Node (no SDK)" import { createHmac, timingSafeEqual } from 'node:crypto'; function verify(raw, header, secret) { const [, t, v1] = /t=(\d+),v1=([0-9a-f]{64})/.exec(header || '') || []; if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) throw new Error('stale'); const mac = createHmac('sha256', secret).update(`${t}.${raw}`).digest(); if (!timingSafeEqual(mac, Buffer.from(v1, 'hex'))) throw new Error('bad signature'); return JSON.parse(raw); } ``` ```python title="Python" import hmac, hashlib, json, re, time def verify(raw: bytes, header: str, secret: str): m = re.search(r"t=(\d+),v1=([0-9a-f]{64})", header or "") if not m or abs(time.time() - int(m[1])) > 300: raise ValueError("stale") mac = hmac.new(secret.encode(), f"{m[1]}.".encode() + raw, hashlib.sha256).hexdigest() if not hmac.compare_digest(mac, m[2]): raise ValueError("bad signature") return json.loads(raw) ``` ## Answering and retries Answer with any `2xx` within 5 seconds; do the work afterwards. Anything else (or no answer) is retried after 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h and 12 h, nine tries in all. Events can arrive twice and out of order: use `id` to skip ones you've handled, and the transaction's `block` to order them. **Webhook deliveries** in usd.net/wallet/business lists the last 100 attempts with their status and time. Pausing the record stops deliveries. ## Webhooks are a signal The signature proves an event came from USD.NET. For money that matters, you can also read the transaction yourself, `GET /tx/:hash` signed by your server wallet, before shipping goods. --- # Business API reference Source: https://usd.net/docs/business/api > 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:
..` 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: 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`. --- # Server SDK Source: https://usd.net/docs/business/sdk > usdnet.mjs - one file, one dependency (viem). Charge, pay out, read users, verify webhooks. ```bash npm i viem curl -O https://usd.net/sdk/usdnet.mjs ``` The SDK is one ES module you keep in your codebase, with [viem](https://viem.sh) as its only dependency. It runs in Node 18+, Bun, Deno and edge runtimes. It signs every request with your server key locally; the key is never sent anywhere. ```js import { USDNet, USDNetError } from './usdnet.mjs'; const usd = new USDNet({ key: process.env.USDNET_SERVER_KEY, network: 'mainnet' }); usd.address; // your server wallet ``` | Option | Meaning | | --- | --- | | `key` | The server wallet's private key, `0x…` | | `network` | `'mainnet'` (default) or `'testnet'` | | `api` | Override the base URL | | `fetch` | Your own `fetch` | ## Methods | Method | Returns | | --- | --- | | `charge({ user, amount, id, memo? })` | The charge transaction, with `idempotent` | | `payout({ user, amount, id, memo? })` | The payout transaction, with `idempotent` | | `transfer({ to, amount, memo? })` | A plain transfer (sweeps, bridge withdrawals); sent one at a time for the nonce | | `user(user)` | `{ balance, mandate, transactions }`; throws `403` without a `read: true` mandate | | `balance(user?)` | A user's balance, or your server wallet's | | `mandate(user)` | The user's mandate to you, or `null` | | `depositAddress(user, chain)` | `{ chain, address, assets, min, arrives }` | | `me(limit?)` | Your server wallet's account | | `tx(hash)` | A transaction you are a party to | | `partner(id)` | A public partner record | | `info()` | The network: chain id, fee, limits | | `USDNet.verifyWebhook(raw, header, secret)` | The event, or throws | Also exported: `amount(v)` (normalises `"4.990"` to `"4.99"`), `messages` (every message format, if you sign elsewhere), `VERSION`. ## Errors Failed requests throw `USDNetError` with `status` (the HTTP status) and `message` (in plain words). A transaction the block refused does **not** throw: it comes back with `status: 'failed'` and `error`. ```js try { await usd.charge({ user, amount: '4.99', id }); } catch (e) { if (e instanceof USDNetError && e.status === 403) askToReconnect(); else if (e.status === 402) askToTopUp(); else throw e; } ``` ## Other languages Anything that can do EIP-191 `personal_sign` works: build the [message](/business/api#charges), sign it with the server key, POST the JSON. In Python, `eth_account`'s `Account.sign_message(encode_defunct(text=message), key)`; in Go, go-ethereum's `accounts.TextHash` and `crypto.Sign`. --- # Testing and going live Source: https://usd.net/docs/business/testing > Build on testnet with free USD₮, check every flow, then switch to mainnet. ## Testnet Testnet is a separate USD Network (`usdnet-testnet-1`) with free USD₮ that has no value. Everything for business works the same. | | Testnet | | --- | --- | | API | `https://usd.net/explorer/testnet/api/v1` | | Explorer | [usd.net/explorer/testnet](https://usd.net/explorer/testnet) | | Wallet | usd.net/wallet → Settings → Network → Testnet | | Test USD₮ | `POST /faucet { "address": "0x…" }`: 100 USD₮ per address every 24 hours, one request a minute per IP | | Deposits | `solana-devnet` and `base-sepolia` | | SDK | `new USDNet({ key, network: 'testnet' })`, `USDNet.configure({ network: 'testnet' })` | Register `http://localhost:` as an origin to try Connect from your machine. Testnet data can be reset, so don't rely on it for long. ## A checklist before launch - Connect: approve, cancel, close the popup, popup blocked, a second connect replacing the mandate. - Charges: success, retry with the same id, over `perTx`, over `daily`, user with too little USD₮, revoked mandate. - Payouts: success, retry with the same id, many at once, server wallet too low. - Webhooks: signature check on the raw body, duplicates skipped, slow handler still answers `2xx` within 5 s. - The server key only in your server's secret store; the webhook secret too. - Monitoring on the server wallet's balance, so payouts never run dry. - A sweep from the server wallet to the business wallet. ## Going live 1. On mainnet, open your business wallet and create a partner record with your production sites. 2. Put the new `.env` values in production. Mainnet and testnet records, keys and signatures are separate. 3. Fund the server wallet with USD₮ on USD.NET (from your business wallet, or by depositing to its own address). 4. Switch `network` to `'mainnet'` in the SDK and in `USDNet.configure`. --- # Security and compliance Source: https://usd.net/docs/business/security > What each key can do, what to protect, and your responsibilities as a business on USD.NET. ## What can move money | Who | Can | Can't | | --- | --- | --- | | A user | Everything in their own account; revoke your mandate at any time | Touch your wallets | | Your server key | Spend the server wallet; charge users within their mandates | Charge above a mandate's limits, charge a user without one, read users without `read: true`, change the partner record | | Your business wallet | Change the partner record (sites, server wallets, webhook, pause); spend its own balance | Charge users | | Your page with connect.js | Ask the user to approve something | Sign anything itself | | USD.NET | Run the network, seal blocks, deliver webhooks, apply [issuer controls](/usdt/issuer-controls) | Sign for any account | ## Protect - **The server key.** In a secret manager, server only. If it leaks: **Pause** the record (charges stop at once), move the funds, replace the key ([how](/business/accounts#replace-a-server-key)). - **The webhook secret.** Rotate it in usd.net/wallet/business if it leaks; the old one stops at once. - **The business wallet.** A passkey wallet, or a recovery phrase kept offline. It controls the record. ## Don't - Don't ask users for their recovery phrase or try to hold their keys. USD.NET never needs them and neither do you. - Don't trust an address, amount or "paid" flag from a browser. Check on the server: `usd.mandate`, the transaction, the webhook. - Don't use random ids for charges and payouts; use ids from your own records so retries can't double-charge or double-pay. ## Users' privacy Accounts are [confidential](/wallet/confidential). You see a user's address, the payments between you and, with `read: true`, their balance. Nothing else about their account, and the public sees only that transactions happened. Treat what you learn as personal data under your privacy policy. ## Compliance USD.NET screens bridge deposits and withdrawals against sanctions lists and may freeze addresses under its [issuer policy](/compliance/freezes); a frozen account can't be charged or paid. You remain responsible for your product and your users: the law where you operate and where they live, consumer protection and refunds, and any licence, age check or identity check your business needs. If you need to identify your users, do it in your own sign-up; USD.NET doesn't share who a wallet belongs to. --- # Overview Source: https://usd.net/docs/open-data/overview > Everything that happens on USD Network is public, and the ledger is built so you can check it rather than trust it. USD Network is operated by one company, so the obvious question is: why believe what it says? The answer is that you do not have to. The ledger is published as open data, and its structure makes rewriting history detectable by anyone who is watching. ## What is public Accounts are [confidential](/wallet/confidential): who paid whom and how much is visible only to the parties. Everything below is open to everyone. | Data | Where | | --- | --- | | Every block, with its signature | [usd.net/explorer/blocks](https://usd.net/explorer/blocks), `GET /blocks` | | That every transfer happened, when and in which block | [usd.net/explorer/txs](https://usd.net/explorer/txs), `GET /txs` | | Every deposit and release: amount and the other chain's transaction | [usd.net/explorer/bridge](https://usd.net/explorer/bridge), `GET /bridge/events` | | The sum of every balance, signed hourly, against the supply | [usd.net/explorer/balances](https://usd.net/explorer/balances), `GET /balances` | | Every freeze and unfreeze, with a reason | [usd.net/explorer/compliance](https://usd.net/explorer/compliance), `GET /compliance` | | Signed checkpoints of the log | [usd.net/explorer/checkpoints](https://usd.net/explorer/checkpoints), `GET /checkpoint` | | Proofs of inclusion and consistency | `GET /proof/…` | | Bridge vaults and bridged supply | [usd.net/explorer/bridge](https://usd.net/explorer/bridge) | | Solana anchors and witness cosignatures | `GET /anchors`, `GET /witnesses` | ## Three layers of assurance :::steps ### Signed blocks Every block is signed by the sequencer's Ed25519 key and names the hash of the block before it. Anyone holding a copy of the chain can check every link. ### A transparency log Block hashes are leaves in an append-only Merkle tree, the structure used by Certificate Transparency to keep certificate authorities honest. A small signed [checkpoint](/open-data/checkpoints) commits to the whole history. [Consistency proofs](/open-data/consistency-proofs) show that a newer checkpoint extends an older one without changing anything. ### Witnesses and anchors Every hour the latest checkpoint is written into a memo on Solana, a record USD.NET can't edit or delete. Independent organisations can check each new checkpoint for consistency with the last and cosign it; their signatures appear on the checkpoint. To show different histories to different people, USD.NET would have to deceive parties it does not control. See [Checkpoints](/open-data/checkpoints#anchors). ::: ## What this proves and what it does not The log proves that history is consistent: once a block has been seen in a checkpoint, it can never be silently changed or removed. It does not, on its own, prove that the operator applied every rule correctly inside a block. For that there are two more checks. The hourly [proof of balances](/open-data/balances) shows every balance adds up to the supply and lets each account confirm it is counted. And because accounts are [confidential](/wallet/confidential), full replay of every transfer is open to the operator and to auditors given read access, rather than to everyone. :::cards - [Checkpoints](/open-data/checkpoints) The signed note format and how to read it. - [Verify it yourself](/open-data/verify) A complete script that checks a checkpoint and proofs. ::: --- # Checkpoints Source: https://usd.net/docs/open-data/checkpoints > A checkpoint is a signed statement of the log's size and root hash, in the C2SP signed-note format used across the transparency ecosystem. ## What a checkpoint says A checkpoint commits to the entire history of USD Network in three lines: ```note title="GET /checkpoint?format=note" explorer.usd.net/usdnet-testnet-1 6 fp2ro0s/sDtChz1XJAvFBx5d2obb+1tCiAD7OKXwTWY= — usd.net 5oGo4ucXWBCDUHDri5nLDlC10fen2MXRGAmonfOzHTl4Ti5CbuME//WamVJ7KlY4Ip08CiQCo5xYJHABHGzwIgbfMAg= ``` | Line | Meaning | | --- | --- | | 1 | **Origin.** Names the log: the host and the chain ID. | | 2 | **Size.** The number of leaves, which is the number of blocks, genesis included. | | 3 | **Root hash.** The RFC 9162 Merkle root over all block hashes, base64. | | blank | Separates the body from the signatures. | | `— usd.net …` | **Signature.** Key name, then base64 of a 4-byte key ID followed by the 64-byte Ed25519 signature. | The signature covers the body: the first three lines, each followed by a newline. ## The key The sequencer's public key is `sequencerKey` in `GET /info`. In C2SP form, the verifier key is: ```text title="Verifier key" usd.net++ ``` The key ID is the first 4 bytes of `SHA-256("usd.net" ‖ 0x0A ‖ 0x01 ‖ public key)`. Tools that speak the signed-note format, such as Go's `golang.org/x/mod/sumdb/note`, can verify USD Network checkpoints with this key directly. ## How the tree is built - Each block hash, as 32 raw bytes, is a leaf. - Leaves are hashed as `SHA-256(0x00 ‖ leaf)` and interior nodes as `SHA-256(0x01 ‖ left ‖ right)`, as RFC 9162 specifies. - Block `n` is leaf `n`, so the log size is always the height plus one. - Each block's own `logRoot` field is the root at size `height + 1`. Every block is therefore also a commitment to the full history up to itself. ## Using checkpoints Save checkpoints as you see them. Later, ask for a [consistency proof](/open-data/consistency-proofs) from your saved size to the current size. If the proof verifies against your saved root, nothing you saw has changed. If the network ever served you a checkpoint that does not verify, you hold signed evidence of it. ## Anchors Once an hour, if the log has grown, the latest checkpoint is written into a Solana memo: ```text title="Memo" usd.net checkpoint usdnet-testnet-1 ``` The memo is signed by the anchor key, which `GET /anchors` returns along with every anchor written so far: size, root, Solana transaction and slot. To use an anchor, read the memo from any Solana explorer or node. Then request `GET /proof/consistency?from=` and verify it against the memo's root. Solana's history can't be edited by USD.NET, so a checkpoint anchored there pins the log's history up to that size for good. ## Witnesses A witness is an independent party that checks the log for everyone else. It keeps the last checkpoint it saw. On each new checkpoint it verifies a consistency proof from the old size, and only then signs the new checkpoint with its own key. The format is C2SP [tlog-cosignature](https://c2sp.org/tlog-cosignature) (`cosignature/v1`): - The signed message is `cosignature/v1\ntime \n` followed by the checkpoint body. - The witness posts its signature line, `— `, with the checkpoint size to `POST /witness/cosign`. - The key ID is the first 4 bytes of `SHA-256(name ‖ 0x0A ‖ 0x04 ‖ public key)`. Once accepted, the line is added to the checkpoint note for that size, under the sequencer's own line, so one note carries both signatures. `GET /witnesses` lists every registered witness, its verifier key and the last checkpoint it cosigned. To run a witness, write to **witnesses@usd.net** with your verifier key, `name+keyid+base64(0x04 ‖ public key)`. --- # Proof of balances Source: https://usd.net/docs/open-data/balances > An hourly Merkle sum tree over every balance, signed by the sequencer. Its total equals the supply, and every account can check it is counted. Accounts on USD Network are [confidential](/wallet/confidential), so nobody can add up the balances themselves. Instead, every hour the sequencer takes every balance at one block height, builds a Merkle sum tree and signs its root and total. Anyone can check the total against the supply, and every account can check that its own balance is inside. Live at [usd.net/explorer/balances](https://usd.net/explorer/balances) and `GET /balances`. ## The tree :::steps 1. **One leaf per account with a balance.** `leaf = SHA-256(0x00 ‖ "usdnet-balance-v1" ‖ address (20 bytes) ‖ balance (u64, big-endian, in units of 10⁻⁶ USD₮) ‖ salt (32 bytes))`. The salt is `HMAC-SHA256(key, ":
")` with a key only the sequencer holds, so a leaf can't be matched to a guessed address and balance. Each account gets its own salt with its proof. 2. **Sorted by leaf hash.** Neighbours in the tree are unrelated accounts. 3. **Nodes carry sums.** `node = SHA-256(0x01 ‖ left hash ‖ left sum (u64) ‖ right hash ‖ right sum (u64))`, and its sum is `left sum + right sum`. A node left over at the end of a level moves up unchanged. 4. **The root carries the total.** The sequencer signs `SHA-256` of the canonical JSON of `{ chain, count, height, id, kind: "usdnet-balances-v1", root, time, total }` with its Ed25519 key, the same key that signs [checkpoints](/open-data/checkpoints). ::: ## What it proves - **Nothing is missing.** The signed total equals the supply at the same height: every USD₮ that exists is in somebody's leaf. - **You are counted.** Your path rebuilds to the signed root with your exact balance. A sum can't be negative (each is an unsigned 64-bit number), so other balances can't cancel yours out. - **It was this snapshot.** The signature ties root, total and height to the sequencer's key. A path shows the sums of sibling subtrees on the way up. The sibling of your leaf is one other account's balance, never its address. ## Check it yourself In the wallet: **Settings** → **Verify my balance**. Or by hand, with a [read pass](/build/api#confidential-reads): ```ts title="check-balance.ts" import { sha256 } from '@noble/hashes/sha256'; import { ed25519 } from '@noble/curves/ed25519'; import { bytesToHex, concatBytes, hexToBytes, utf8ToBytes } from '@noble/hashes/utils'; const u64 = (v: bigint) => { const b = new Uint8Array(8); for (let i = 7; i >= 0; i--) { b[i] = Number(v & 0xffn); v >>= 8n; } return b; }; const hex = (b: Uint8Array) => bytesToHex(sha256(b)); const p = await (await fetch(`https://usd.net/api/v1/balances/proof/${address}`, { headers: { 'x-usd-read': pass } })).json(); let h = hex(concatBytes(new Uint8Array([0]), utf8ToBytes('usdnet-balance-v1'), hexToBytes(p.leaf.address.slice(2)), u64(BigInt(p.leaf.balance)), hexToBytes(p.leaf.salt))); let s = BigInt(p.leaf.balance); for (const step of p.path) { const ss = BigInt(step.s); h = step.left ? hex(concatBytes(new Uint8Array([1]), hexToBytes(step.h), u64(ss), hexToBytes(h), u64(s))) : hex(concatBytes(new Uint8Array([1]), hexToBytes(h), u64(s), hexToBytes(step.h), u64(ss))); s += ss; } const x = p.head; const msg = JSON.stringify({ chain: x.chain, count: x.count, height: x.height, id: x.id, kind: 'usdnet-balances-v1', root: x.root, time: x.time, total: x.total }); console.log({ included: h === x.root && s.toString() === x.total, signed: ed25519.verify(hexToBytes(p.sig), sha256(utf8ToBytes(msg)), hexToBytes(p.key)), equalsSupply: x.total === p.supply, }); ``` The keys of that JSON are already in sorted order, which is what canonical JSON needs. --- # Inclusion proofs Source: https://usd.net/docs/open-data/inclusion-proofs > Prove that a block, and therefore every transfer in it, is part of the signed log. An inclusion proof shows that a particular leaf is in a tree with a particular root, using only a handful of hashes instead of the whole tree. For a log of a million blocks, the proof is 20 hashes. ## Proving a transfer is in the log :::steps ### Find its block `GET /tx/:hash` gives the transfer's `block`. ### Check the block contains it `GET /block/:height` lists the transfer hashes in `txs`. Recompute `txRoot` and the block `hash` as described in [Architecture](/network/architecture#block-structure) to confirm the block commits to your transfer. ### Get the proof `GET /proof/inclusion/:height` returns the `leaf` (the block hash), the log `size`, the `root` and the audit `path`. ### Verify against a checkpoint Check that `size` and `root` match a signed checkpoint, then run the RFC 9162 verification below. If it passes, the block is in the history that the checkpoint signs. ::: ## Verification ```js title="inclusion.mjs" import { sha256 } from '@noble/hashes/sha2.js'; const hex = (s) => Uint8Array.from(s.match(/../g).map((b) => parseInt(b, 16))); const toHex = (u) => [...u].map((b) => b.toString(16).padStart(2, '0')).join(''); const cat = (...a) => { const o = new Uint8Array(a.reduce((n, x) => n + x.length, 0)); let i = 0; for (const x of a) { o.set(x, i); i += x.length; } return o; }; const leafHash = (d) => sha256(cat(new Uint8Array([0]), d)); const nodeHash = (l, r) => sha256(cat(new Uint8Array([1]), l, r)); // RFC 9162, section 2.1.3.2 export function verifyInclusion(index, size, leaf, path, root) { if (index >= size) return false; let fn = index, sn = size - 1, r = leafHash(hex(leaf)); for (const p of path.map(hex)) { if (sn === 0) return false; if (fn & 1 || fn === sn) { r = nodeHash(p, r); if (!(fn & 1)) while (!(fn & 1) && fn !== 0) { fn >>= 1; sn >>= 1; } } else r = nodeHash(r, p); fn >>= 1; sn >>= 1; } return sn === 0 && toHex(r) === root; } ``` The explorer runs the same check in your browser at [usd.net/explorer/verify](https://usd.net/explorer/verify). --- # Consistency proofs Source: https://usd.net/docs/open-data/consistency-proofs > Prove that today's log contains yesterday's log, unchanged. This is what makes rewriting history detectable. A consistency proof shows that a tree of size `m` is a prefix of a tree of size `n`: every block that was in the old log is still there, in the same place, with the same hash. If any block had been altered, removed or reordered, no valid proof could exist. ## Checking that history was not rewritten :::steps ### Keep a checkpoint At some point, save a checkpoint's size and root. Any block's `height + 1` and `logRoot` also work. ### Ask for a proof `GET /proof/consistency?from=` returns a proof to the current size. ### Verify with your root Run the verification below with **your saved root** as the old root and the current signed checkpoint's root as the new root. Do not use the `oldRoot` from the response: the point is to check against what you saw before. ::: ## Verification ```js title="consistency.mjs" import { sha256 } from '@noble/hashes/sha2.js'; const hex = (s) => Uint8Array.from(s.match(/../g).map((b) => parseInt(b, 16))); const toHex = (u) => [...u].map((b) => b.toString(16).padStart(2, '0')).join(''); const cat = (...a) => { const o = new Uint8Array(a.reduce((n, x) => n + x.length, 0)); let i = 0; for (const x of a) { o.set(x, i); i += x.length; } return o; }; const nodeHash = (l, r) => sha256(cat(new Uint8Array([1]), l, r)); // RFC 9162, section 2.1.4.2 export function verifyConsistency(first, second, firstRoot, secondRoot, path) { if (first === second) return path.length === 0 && firstRoot === secondRoot; if (first === 0 || first > second) return false; let p = path.map(hex); if ((first & (first - 1)) === 0) p = [hex(firstRoot), ...p]; let fn = first - 1, sn = second - 1; while (fn & 1) { fn >>= 1; sn >>= 1; } let fr = p[0], sr = p[0]; for (const c of p.slice(1)) { if (sn === 0) return false; if (fn & 1 || fn === sn) { fr = nodeHash(c, fr); sr = nodeHash(c, sr); if (!(fn & 1)) while (!(fn & 1) && fn !== 0) { fn >>= 1; sn >>= 1; } } else sr = nodeHash(sr, c); fn >>= 1; sn >>= 1; } return sn === 0 && toHex(fr) === firstRoot && toHex(sr) === secondRoot; } ``` ## Who should run this Anyone who depends on USD Network's history: exchanges, auditors, partners and, at mainnet, the independent witnesses that cosign checkpoints. Running it on a schedule against saved checkpoints is cheap and turns "we promise not to rewrite history" into something you check every few minutes. --- # Verify it yourself Source: https://usd.net/docs/open-data/verify > One script that checks the latest signed checkpoint, proves a block is in the log and recomputes the block's hash and signature. This script uses two small, audited libraries and the public API. It trusts nothing it does not check. ```bash title="Terminal" npm install @noble/hashes @noble/curves ``` ```js title="verify.mjs" import { sha256 } from '@noble/hashes/sha2.js'; import { ed25519 } from '@noble/curves/ed25519.js'; const API = 'https://usd.net/explorer/testnet/api/v1'; const enc = new TextEncoder(); const hex = (s) => Uint8Array.from(s.match(/../g).map((b) => parseInt(b, 16))); const toHex = (u) => [...u].map((b) => b.toString(16).padStart(2, '0')).join(''); const b64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0)); const cat = (...a) => { const o = new Uint8Array(a.reduce((n, x) => n + x.length, 0)); let i = 0; for (const x of a) { o.set(x, i); i += x.length; } return o; }; const leafHash = (d) => sha256(cat(new Uint8Array([0]), d)); const nodeHash = (l, r) => sha256(cat(new Uint8Array([1]), l, r)); const canonical = (v) => v === null || typeof v !== 'object' ? JSON.stringify(v) : Array.isArray(v) ? '[' + v.map(canonical).join(',') + ']' : '{' + Object.keys(v).filter((k) => v[k] !== undefined).sort().map((k) => JSON.stringify(k) + ':' + canonical(v[k])).join(',') + '}'; function verifyInclusion(index, size, leaf, path, root) { if (index >= size) return false; let fn = index, sn = size - 1, r = leafHash(hex(leaf)); for (const p of path.map(hex)) { if (sn === 0) return false; if (fn & 1 || fn === sn) { r = nodeHash(p, r); if (!(fn & 1)) while (!(fn & 1) && fn !== 0) { fn >>= 1; sn >>= 1; } } else r = nodeHash(r, p); fn >>= 1; sn >>= 1; } return sn === 0 && toHex(r) === root; } // 1. The network key and the latest signed checkpoint const { sequencerKey, chain } = await fetch(API + '/info').then((r) => r.json()); const note = await fetch(API + '/checkpoint?format=note').then((r) => r.text()); const [body, sigs] = note.split('\n\n'); const [origin, size, rootB64] = body.split('\n'); const sigLine = sigs.split('\n').find((l) => l.startsWith('— usd.net ')); const noteOk = ed25519.verify(b64(sigLine.split(' ')[2]).slice(4), enc.encode(body + '\n'), hex(sequencerKey)); const root = toHex(b64(rootB64)); console.log(`${origin} size ${size}: signature ${noteOk ? 'valid' : 'INVALID'}`); // 2. A block: its hash, its signature and its place in the log const height = Number(process.argv[2] ?? 0); const { hash, sig, transactions, ...block } = await fetch(`${API}/block/${height}`).then((r) => r.json()); const hashOk = toHex(sha256(enc.encode(canonical({ ...block, logRoot: '', chain })))) === hash; const sigOk = ed25519.verify(hex(sig), hex(hash), hex(sequencerKey)); const proof = await fetch(`${API}/proof/inclusion/${height}`).then((r) => r.json()); const inLog = proof.leaf === hash && proof.size === Number(size) && proof.root === root && verifyInclusion(height, proof.size, proof.leaf, proof.path, root); console.log(`block ${height}: hash ${hashOk}, signature ${sigOk}, in signed log ${inLog}`); ``` ```bash title="Terminal" node verify.mjs 5 # explorer.usd.net/usdnet-testnet-1 size 6: signature valid # block 5: hash true, signature true, in signed log true ``` > [!TIP] > If a new block is sealed between fetching the checkpoint and fetching the proof, the sizes will differ and the check reports `false`. Run it again, or fetch the proof first and the checkpoint second. ## In the browser [usd.net/explorer/verify](https://usd.net/explorer/verify) runs the same checks in your browser, with no install. --- # FAQ Source: https://usd.net/docs/resources/faq > Short answers to the questions people ask most about USD Network. ## Is USD Network a blockchain? It is a ledger with blockchain properties: hash-linked signed blocks, public data and cryptographic proofs. It is not decentralised. USD.NET operates it as a regulated business, and says so plainly. ## Why not just use Ethereum or Tron? You can, and the wallet supports both. USD Network exists for payments that need what those chains cannot promise: fees in dollars that never change, finality in about a second, an operator that answers to regulators and users, and a ledger built only for dollars. ## Does USD.NET hold my money? No. Your wallet's keys are derived on your device and never sent to USD.NET. The only funds USD.NET holds are in the bridge vaults, and those are publicly checked by [proof of bridge](/bridge/proof-of-bridge). ## Can USD.NET freeze my funds? USD.NET, as operator, can freeze an address under its published policy in response to a lawful request. Every freeze is public, with a reason, on the [compliance log](https://usd.net/explorer/compliance). Freezes never move funds. ## Is there a USD Network token? No. There is no token, no airdrop and no staking. Fees are paid in USD₮. ## What does a transfer cost? 0.01 USD₮, flat, whatever the amount. ## How fast is a transfer? Final as soon as it is sealed, normally in under a second. There are no confirmations to wait for. ## What happens if USD.NET disappears? Your keys are a standard recovery phrase that works in any wallet on every other chain. The full ledger is public and can be copied by anyone, and the signed checkpoints prove what it contained. ## Is the testnet USD₮ real? No. Test USD₮ from the faucet has no value and cannot be bridged or withdrawn. ## Where do I report a security issue? Email **security@usd.net**. Please do not disclose issues publicly before they are fixed. --- # Glossary Source: https://usd.net/docs/resources/glossary > Terms used across these docs. | Term | Meaning | | --- | --- | | **Audit path** | The sibling hashes needed to recompute a Merkle root from one leaf. The `path` in an inclusion proof. | | **Block** | A signed, hash-linked batch of ledger events sealed by the sequencer. | | **Bridged supply** | USD₮ on USD Network that came in through the USD Bridge and is backed by vaults on other chains. | | **Canonical JSON** | JSON with keys sorted, no whitespace and absent fields omitted. Used for every hash. | | **Checkpoint** | A signed note stating the log's origin, size and root hash. | | **Consistency proof** | A proof that a larger log contains a smaller one unchanged. | | **EIP-191** | The Ethereum standard for signing plain-text messages, used by `personal_sign`. | | **Fee collector** | The account `0x…0fee00` that receives transfer fees. | | **Finality** | The point after which a transfer cannot be reversed. On USD Network, the moment it is sealed. | | **Heartbeat block** | An empty block sealed when the network is idle, so the log keeps advancing. | | **Inclusion proof** | A proof that a block is a leaf of the log at a given size and root. | | **Issued supply** | USD₮ created directly on USD Network by the issuer. | | **Issuer** | The account `0x000…000` that mints USD₮ and applies compliance actions. | | **Nonce** | A per-account counter that orders transfers and stops replays. | | **Passkey** | A WebAuthn credential kept by your device and unlocked with biometrics or a PIN. | | **PRF** | The WebAuthn pseudo-random function extension. It lets a passkey produce a stable secret, from which the wallet derives its phrase. | | **Proof of bridge** | The public check that bridge vault balances are at least the bridged supply. | | **Recovery phrase** | The 12 words that back up every key in the wallet. | | **RFC 9162** | Certificate Transparency version 2.0, which defines the Merkle tree and proofs USD Network uses. | | **Sequencer** | The USD.NET service that orders, validates and seals transfers. | | **Signed note** | The C2SP text format for signed statements, used for checkpoints. | | **USD Bridge** | The vaults and signers that move USD₮ and USDC between USD Network and other chains. | | **USD₮** | The only asset on USD Network. On mainnet it is minted by the USD Bridge one to one against USDC and USD₮ held in public vaults. | | **Witness** | An independent party that checks and cosigns checkpoints. The programme is open. | | **Anchor** | A checkpoint written into a Solana memo once an hour, so it can't be changed later. | --- # Changelog Source: https://usd.net/docs/resources/changelog > What has shipped on USD Network, newest first. ## November 2026 ### USD.NET for business - A business API (4 November). Users connect with **USD.NET Connect** (`connect.js`, a popup on usd.net) and sign a **mandate**: your server wallet may charge them up to limits they choose, and optionally see their balance. New transaction types `mandate`, `revoke`, `charge` and `payout`: charges and payouts have no nonce and are idempotent by your `id`, so a server can send thousands at once, each final in under a second. **Partner records** (`POST /partners`) name your sites, server wallets and webhook; **webhooks** are signed (`usdnet-signature`) and retried for 12 hours. A one-file server SDK (`usd.net/sdk/usdnet.mjs`), **Business** in the wallet, and **Settings → Connected apps** with Revoke. See [Build for business](/business/overview). ### Markets - Perps list real-world markets first (4 November): stocks, indices, commodities and currencies from trade.xyz on Hyperliquid (S&P 500, US Tech 100, gold, oil, NVIDIA, Apple…), plus established crypto. Only liquid markets are shown (at least $2M a day, crypto $20M, with open interest); meme coins, leveraged ETFs and pre-IPO synthetics are left out. Choose the leverage per order; trade.xyz markets use the same USDC balance. - Stocks & ETFs grew from 10 to 161 Ondo tokenized stocks and ETFs, including commodity and bond ETFs. Each was checked to buy with 1,000 USDC and sell back with under 1.5% lost each way. ### Wallet sign-in - Two kinds of wallet: a passkey wallet, or a recovery phrase you create or import (4 November). Creating shows the 12 words in one box with Copy; importing has Paste. A phrase opens the wallet for the session; **Settings → Unlock this device with Face ID / Touch ID** keeps it on the device behind a small device passkey (a lock key), or a password where passkeys can't. Wallets already locked with a password keep working. **Use a password instead** is gone. ### Confidential accounts - Every account is confidential (4 November). The public sees that a transaction happened, when and in which block; never who or how much. An account's balance and activity are returned only to a request signed with its own key (`x-usd-read`). See [Confidential accounts](/wallet/confidential) and [Confidential reads](/build/api#confidential-reads). - New transactions carry a random `salt` in their hash. Older hashes are unchanged. - Receipts: each line in Activity opens a link that proves one transaction to whoever you share it with. - [Proof of balances](/open-data/balances): every hour a signed Merkle sum tree over every balance, whose total equals the supply. `GET /balances`, `GET /balances/proof/:address`, and **Verify my balance** in the wallet. ### One domain - Everything is on usd.net: the wallet at `/wallet`, the explorer at `/explorer` (testnet at `/explorer/testnet`), these docs at `/docs`, the network story at `/about`. The mainnet API is `https://usd.net/api/v1`, testnet's `https://usd.net/explorer/testnet/api/v1`. mainnet.usd.net, testnet.usd.net, explorer.usd.net, docs.usd.net and about.usd.net redirect permanently to the new addresses, and their `/api/v1` keeps answering. Log origins such as `explorer.usd.net/usdnet-1` are names inside signed checkpoints and do not change. - Wallet: Swap moves dollars in and out of USD Network on every open chain; gift links; sends on Tron, Solana and Bitcoin; ⌘K search; the wallet stays unlocked across pages for a time you choose. ### Mainnet - BNB Chain, Base and Arbitrum live on the USD Bridge (4 November), completing the six chains. - USD Bridge on Tron: USD₮ (TRC-20). A Tron address is linked to a USD Network address with a signature (TronLink signMessageV2 format); deposits are credited after 20 blocks, and from 5 USD₮ the vault covers the sender's energy, keeping its cost; withdrawals keep the energy the vault burns, priced live. - USD Bridge on Ethereum: USDC and USD₮. USDC comes in without ETH (EIP-3009, the vault pays the gas and keeps it, priced from Chainlink); any transfer from the sender's own wallet is credited after 6 blocks; withdrawals keep the gas the vault pays. One vault address for every EVM chain. - Mainnet `usdnet-1` at mainnet.usd.net: a new ledger whose USD₮ is minted only by USD Bridge deposits. No faucet. See [Mainnet](/get-started/mainnet). - USD Bridge on Solana mainnet with USDC and USD₮, OFAC sanctions screening of senders and destinations, and an operator pause. Ethereum, Tron, BNB Chain, Base and Arbitrum follow in that order. - The wallet reads the network from `/info` and signs for that chain; Settings → Network switches between mainnet and testnet. - Testnet moves to testnet.usd.net (explorer.usd.net keeps serving it until mainnet takes that name). ### Docs - docs.usd.net launches, with guides, the API reference and verification walkthroughs. Every code sample is tested against the live testnet. - `llms.txt`, `llms-full.txt` and a Markdown view of every page, for tools and AI assistants. ### Wallet - Sends without gas: USDC and USDT on Solana without SOL, USDC on Ethereum, Base and Arbitrum without ETH. The fee is paid in the stablecoin. See [Sends without gas](/wallet/gasless). - [usd.net/wallet](https://usd.net/wallet) opens: a self-custodial wallet derived from a passkey, with recovery phrase export. - Addresses and balances on USD Network, Ethereum, Base, Arbitrum, BNB Chain, Tron, Solana and Bitcoin. - USD Network transfers, EVM sends, multi-route swaps, Ondo tokenized stocks and Hyperliquid perpetuals. ### Network - Testnet `usdnet-testnet-1` goes live with signed, hash-linked blocks and deterministic finality. - Transfers signed with EIP-191 `personal_sign`, flat 0.01 USD₮ fee, 140-character memos. - RFC 9162 transparency log over block hashes, C2SP signed-note checkpoints, inclusion and consistency proofs. - Faucet: 100 test USD₮ per address per day. - Compliance actions recorded on a public log. ### USD Bridge - Base Sepolia added as a second testnet bridge chain: gasless deposits with EIP-3009, and any USDC sent to the vault is credited to its sender. - Testnet bridge live on Solana devnet with Circle's devnet USDC: deposits minted as `bridge_in` and withdrawals burned as `bridge_out`. Every movement is attested by 2 of 3 bridge signers. Live proof of bridge at mainnet.usd.net/bridge, and Bridge in the wallet. ### Explorer - Hourly checkpoint anchors on Solana and the witness cosignature protocol (C2SP cosignature/v1): mainnet.usd.net/checkpoints, `GET /anchors`, `GET /witnesses`, `POST /witness/cosign`. - Preview deployments run their own chain (`usdnet-testnet-1-preview`) and keys, so they never touch the public testnet. - [usd.net/explorer](https://usd.net/explorer) with live blocks and transfers, accounts, checkpoints, an in-browser verifier, the compliance log and the proof of bridge page. ## Next - USD Bridge vaults on Ethereum, Tron, Solana and BNB Chain. - Independent witnesses and public-chain anchoring for checkpoints. - Banking partner on- and off-ramps. - Sends and swaps from Tron, Solana and Bitcoin in the wallet.