Reference

Server SDK

usdnet.mjs - one file, one dependency (viem). Charge, pay out, read users, verify webhooks.

Terminal
npm i viem
curl -O https://usd.net/sdk/usdnet.mjs

The SDK is one ES module you keep in your codebase, with viem 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.

JavaScript
import { USDNet, USDNetError } from './usdnet.mjs';
const usd = new USDNet({ key: process.env.USDNET_SERVER_KEY, network: 'mainnet' });
usd.address; // your server wallet
OptionMeaning
keyThe server wallet's private key, 0x…
network'mainnet' (default) or 'testnet'
apiOverride the base URL
fetchYour own fetch

Methods

MethodReturns
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.

JavaScript
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, 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.