Build

Accepting payments

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

  1. 1

    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.

  2. 2

    Watch it

    Poll GET /address/:address with a read pass 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.

  3. 3

    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.

  4. 4

    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.

Example

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);

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.