Users and money

USD.NET 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
<script src="https://usd.net/sdk/connect.js"></script>

Or copy the file and serve it yourself; it has no dependencies (https://usd.net/sdk/connect.js, 5 KB).

USDNet.configure(options)

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

JavaScript
const { address, network, chain, mandate } = await USDNet.connect({
  partner: 'pt_4b8d526f30e5',
  mandate: { perTx: '25', daily: '100', total: '500', days: 30, read: true },
});
OptionRequiredMeaning
partnerYesYour partner id
mandate.perTxWith mandateMost a single charge may take, USD₮
mandate.dailyWith mandateMost all charges may take in one UTC day
mandate.totalNoMost it may ever take. Leave out for no lifetime limit.
mandate.daysNoHow long it lasts, 1–400 days. Default 30.
mandate.readNoAlso let your server see the balance, and the payments between you. Default false.
spenderNoWhich of your server wallets the mandate names. Default your payTo.
networkNoOverrides 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.

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.

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

JavaScript
document.querySelector('#topup').onclick = () => USDNet.open('topup');

To show deposit addresses inside your own UI instead, see Top-ups.

Errors

connect and pay reject with an Error whose code is:

codeMeaning
cancelledThe user closed the popup or pressed Cancel
popup_blockedCalled outside a click, or the browser blocks popups
bad_requestMissing partner or a bad page name
failedUSD.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.