Server SDK
usdnet.mjs - one file, one dependency (viem). Charge, pay out, read users, verify webhooks.
npm i viem
curl -O https://usd.net/sdk/usdnet.mjsThe 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.
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.
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.