# Server SDK

> usdnet.mjs - one file, one dependency (viem). Charge, pay out, read users, verify webhooks.

```bash
npm i viem
curl -O https://usd.net/sdk/usdnet.mjs
```

The SDK is one ES module you keep in your codebase, with [viem](https://viem.sh) 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.

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

```js
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](/business/api#charges), 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`.
