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
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:3000while developing) and, optionally, a webhook URL. Save the.envit shows: the server key is shown only once. - 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
Add Connect to your page
One script tag, one button.
- 4
Charge and pay out from your server
With the one-file SDK.
- 5
Handle webhooks
Verify the signature, then act on the event.
1. Your .env
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_… # secret2. Connect a user (browser)
<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)
npm i viem
curl -O https://usd.net/sdk/usdnet.mjsimport { 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
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.