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.
<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)
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.
const { address, network, chain, mandate } = await USDNet.connect({
partner: 'pt_4b8d526f30e5',
mandate: { perTx: '25', daily: '100', total: '500', days: 30, read: true },
});| Option | Required | Meaning |
|---|---|---|
partner | Yes | Your partner id |
mandate.perTx | With mandate | Most a single charge may take, USD₮ |
mandate.daily | With mandate | Most all charges may take in one UTC day |
mandate.total | No | Most it may ever take. Leave out for no lifetime limit. |
mandate.days | No | How long it lasts, 1–400 days. Default 30. |
mandate.read | No | Also let your server see the balance, and the payments between you. Default false. |
spender | No | Which of your server wallets the mandate names. Default your payTo. |
network | No | Overrides 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.
{
"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.
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.
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:
code | Meaning |
|---|---|
cancelled | The user closed the popup or pressed Cancel |
popup_blocked | Called outside a click, or the browser blocks popups |
bad_request | Missing partner or a bad page name |
failed | USD.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.originof 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.