Build for business

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.

  1. 1

    Create your partner record

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

  2. 2

    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>" }.

  3. 3

    Add Connect to your page

    One script tag, one button.

  4. 4

    Charge and pay out from your server

    With the one-file SDK.

  5. 5

    Handle webhooks

    Verify the signature, then act on the event.

1. Your .env

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

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.

3. Charge and pay out (server)

Terminal
npm i viem
curl -O https://usd.net/sdk/usdnet.mjs
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.

4. Webhooks

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.

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.