Build for business

Accounts and partner record

Your business wallet, your server wallets and the partner record that ties them to your sites and webhook.

Two accounts

Business walletServer wallet
Where the key livesYour USD.NET wallet, behind a passkey (or a recovery phrase you keep offline)Your server's environment, USDNET_SERVER_KEY
What it doesOwns and changes the partner record. Receives swept revenue.Charges users within their mandates, sends payouts, pays the 0.01 USD₮ fee
Who signsYou, by hand, in usd.net/wallet/businessYour code, with the SDK
What to keep in itRevenueEnough 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, 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

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
}
FieldMeaning
originsSites allowed to open Connect for you. Connect refuses any other.
walletsYour server wallets (up to 5). Users' mandates name one of them.
payToWhere USDNet.pay sends one-off payments, and the default spender in USDNet.connect.
disabledPaused: 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.

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.