# 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)

```js
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.

```js
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.

```json title="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.

```js
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.

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

To show deposit addresses inside your own UI instead, see [Top-ups](/business/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.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.
