# Quickstart

> A pack-opening shop on USD.NET testnet in 15 minutes - connect, charge, sell back, webhooks.

You'll build the core of a collectible-card shop: a user connects their USD.NET wallet, buys a booster pack for 4.99 USD₮ and sells a card back for 12.50 USD₮. Everything runs on **testnet**, where USD₮ is free and has no value.

:::steps
### Create your partner record
Open [usd.net/wallet/business](https://usd.net/wallet/business), switch to **Testnet** in Settings → Network, and create a partner record with your site (use `http://localhost:3000` while developing) and, optionally, a webhook URL. Save the `.env` it shows: the server key is shown only once.

### Fund the server wallet
Your server wallet pays 0.01 USD₮ per charge or payout and needs float for payouts. On testnet, take 100 test USD₮ from the faucet: `POST /faucet { "address": "<USDNET_SERVER_ADDRESS>" }`.

### Add Connect to your page
One script tag, one button.

### Charge and pay out from your server
With the one-file SDK.

### Handle webhooks
Verify the signature, then act on the event.
:::

## 1. Your `.env`

```bash title=".env (from usd.net/wallet/business)"
USDNET_NETWORK=testnet
USDNET_PARTNER_ID=pt_4b8d526f30e5
USDNET_SERVER_KEY=0x…            # secret: never commit it, never send it to a browser
USDNET_SERVER_ADDRESS=0x…
USDNET_WEBHOOK_SECRET=whsec_…    # secret
```

## 2. Connect a user (browser)

```html title="index.html"
<script src="https://usd.net/sdk/connect.js"></script>
<button id="connect">Connect with USD.NET</button>
<script>
  USDNet.configure({ network: 'testnet' });
  document.getElementById('connect').onclick = async () => {
    try {
      const { address, mandate } = await USDNet.connect({
        partner: 'pt_4b8d526f30e5',
        // Let our server charge up to 25 USD₮ a pack, 100 a day, for 30 days, and see the balance
        mandate: { perTx: '25', daily: '100', days: 30, read: true },
      });
      await fetch('/api/link-wallet', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ address }) });
    } catch (e) {
      if (e.code !== 'cancelled') alert(e.message);
    }
  };
</script>
```

The popup checks that `location.origin` is one of your registered sites before it shows anything. Call `connect` from a click, or the browser blocks the popup.

> [!WARNING]
> Treat the address the page sends you as a claim. Before you rely on it, check on your server that a mandate exists: `await usd.mandate(address)` returns it, or `null`. Your `mandate.created` webhook carries the same.

## 3. Charge and pay out (server)

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

```js title="server.mjs"
import { USDNet } from './usdnet.mjs';
const usd = new USDNet({ key: process.env.USDNET_SERVER_KEY, network: process.env.USDNET_NETWORK });

// Buy a pack. The id is yours and makes it safe to retry: the same id never charges twice.
export async function buyPack(user, orderId) {
  const tx = await usd.charge({ user, amount: '4.99', id: `pack_${orderId}`, memo: 'Booster pack' });
  if (tx.status !== 'final') throw new Error(tx.error);
  return openPack(user, orderId);         // your game logic
}

// Buy a card back from the user.
export async function sellBack(user, cardId, price) {
  const tx = await usd.payout({ user, amount: price, id: `buyback_${cardId}`, memo: 'Charizard EX' });
  if (tx.status !== 'final') throw new Error(tx.error);
  return tx.hash;
}

// What the user has, and what their mandate still allows today
const u = await usd.user(user);          // { balance, mandate: { leftToday, leftTotal, … }, transactions }
```

Both calls return in well under a second with the transaction already `final` (or `failed` with an `error`). See [Charges and payouts](/business/charges).

## 4. Webhooks

```js title="webhook.mjs (Express)"
import express from 'express';
import { USDNet } from './usdnet.mjs';
const app = express();
app.post('/usdnet/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try { event = await USDNet.verifyWebhook(req.body.toString('utf8'), req.get('usdnet-signature'), process.env.USDNET_WEBHOOK_SECRET); }
  catch { return res.sendStatus(400); }
  if (await alreadyHandled(event.id)) return res.sendStatus(200);  // events can arrive more than once
  switch (event.type) {
    case 'mandate.created': await linkUser(event.data.user, event.data.mandate); break;
    case 'user.credited':   await showTopUp(event.data.user, event.data.amount); break;
    case 'charge.succeeded': await markPaid(event.data.id); break;
    case 'mandate.revoked': await unlinkUser(event.data.user); break;
  }
  res.sendStatus(200);
});
```

Press **Send test event** in usd.net/wallet/business to check your endpoint. See [Webhooks](/business/webhooks).

## 5. Go live

Create a partner record on **mainnet** (a mainnet business wallet, your production sites), fund the server wallet with real USD₮, change `USDNET_NETWORK=mainnet` and `USDNet.configure({ network: 'mainnet' })`. Testnet and mainnet signatures never work on each other: each names its chain.
