API v1
Pay X accounts from your server.
Your server creates payouts with an API key. nett answers with the exact calls, and your app signs them from its own verified wallet: nett never holds your funds or keys.
Mainnet beta: unaudited contracts, real funds. Start small.
1. App and key
In Developers, create an app and an API key. The key is shown once.
2. Payer wallet
Verify the wallet your app pays from: sign one message with it.
3. Payouts
Post up to 50 payouts. Send the calls nett returns from that wallet, then confirm.
4. Webhooks
Signed events as each payout locks, settles or is refunded.
Rules
Non-custodial. nett never holds your funds or keys. The API returns calldata; your app signs it from its own verified wallet. Check where each call goes before signing it.
Recipients are never guessed. A payout needs the recipient’s numeric X id (xUserId), unless its @handle belongs to a nett user who allows being found. A handle that is another account than xUserId is refused (handle_mismatch).
Server side only. /api/v1 sends no CORS headers and refuses a key sent from a browser (403 browser_not_allowed). A key in a web page or an app bundle is a leaked key: revoke it in Developers.
Mainnet beta. Unaudited contracts, real USDG. Start small.
Auth
Every request carries an API key from Developers.
GET /api/v1/payouts HTTP/1.1 Host: www.usenett.app Authorization: Bearer nett_sk_ab12cd34_…
- Base URL
https://www.usenett.app/api/v1- Keys
- Shown once, when created. Up to 5 active per app, 5 apps per account.
- Revoke
- In Developers. It stops working at once.
- Rate limit
- 60 requests a minute per key, then
429 rate_limitedwithRetry-After.
Quote
What providers charge now, and the two contracts your calls may go to.
curl "https://www.usenett.app/api/v1/quote?amount=10.00" \ -H "Authorization: Bearer $NETT_API_KEY"
{
"amount": "10.00",
"amountMicros": "10000000",
"providers": { "active": 4, "feeBps": { "min": 50, "median": 75, "max": 100 } },
"suggestedMaxFee": "0.10",
"suggestedMaxFeeMicros": "100000",
"deadline": { "min": "+10m", "max": "+30d", "default": "+24h" },
"contract": {
"chainId": 4663,
"escrow": "0x70085048eCa377619e9584605e5C30868a7890E6",
"usdg": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
"decimals": 6
}
}Amounts are dollars as strings, two decimals; …Micros are USDG base units (6 decimals). Fees are in basis points: 75 = 0.75%. Only a provider whose fee fits under a payout’s max fee can take it.
Create payouts
POST /api/v1/payouts with 1 to 50 payouts. Nothing moves until you send their calls.
externalId- Yours, 1 to 64 characters of
A-Z a-z 0-9 _ . : -. The idempotency key. from- A wallet verified for this app. It signs, and pays. One
fromper call. amount- Dollars,
"10.00": at most 2 decimals, at least 1.00. xUserId- The recipient’s numeric X id, as a string. Required unless the handle is a nett user.
handle- Optional, with or without @. The label on the receipt; checked against
xUserIdwhen it is a nett user. maxFee- Optional,
"0.10", at most the amount. The quote’s suggestion by default. The unused part comes back. deadline- Optional: unix seconds, or ISO 8601 with a time zone. 10 minutes to 30 days out; 24 hours by default. Past it, the payout can be refunded.
curl https://www.usenett.app/api/v1/payouts \
-H "Authorization: Bearer $NETT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"payouts":[{
"externalId": "order_1042",
"from": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
"amount": "10.00",
"xUserId": "1790000000000000001",
"handle": "alice"
}]}'// curl -o nett.mjs https://www.usenett.app/sdk/nett.mjs
import { createClient } from './nett.mjs';
const nett = createClient({ apiKey: process.env.NETT_API_KEY });
const quote = await nett.quote('10.00');
const { payouts, approve } = await nett.payouts.create([{
externalId: 'order_1042',
from: '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC',
amount: '10.00',
xUserId: '1790000000000000001',
handle: 'alice',
maxFee: quote.suggestedMaxFee,
}]);// 201 Created (200: the same payouts again, for a replay)
{
"payouts": [{
"externalId": "order_1042",
"status": "awaiting_signature",
"orderId": null,
"ref": "0x90efebecf1c94a7220268dc80f0a7ce34038abdf606902b5fb70c17538e15dfa",
"from": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
"xUserId": "1790000000000000001",
"handle": "alice",
"amount": "10.00",
"amountMicros": "10000000",
"maxFee": "0.10",
"maxFeeMicros": "100000",
"deadline": "2026-10-02T12:00:00.000Z",
"provider": null,
"fee": null,
"feeMicros": null,
"feeRefund": null,
"feeRefundMicros": null,
"receiptUrl": null,
"createdAt": "2026-10-01T12:00:00.000Z",
"calls": [{
"to": "0x70085048eCa377619e9584605e5C30868a7890E6",
"data": "0x36282f62…",
"value": "0",
"description": "nett createOrder for payout order_1042: $10.00 to @alice, max fee $0.10, …"
}],
"timeline": []
}],
"approve": {
"to": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
"data": "0x095ea7b3…",
"amountMicros": "10100000",
"spender": "0x70085048eCa377619e9584605e5C30868a7890E6",
"currentAllowanceMicros": "0",
"needed": true
}
}All or nothing: one invalid payout refuses the call, with its index and field in details. approve sets the allowance for every payout of this wallet still awaiting its signature, this call’s and earlier ones: exactly their amounts plus max fees. needed is false when the current allowance already covers them.
Send the calls
From the from wallet: the approval when approve.needed, then each payout’s calls. Only to USDG and the escrow, from the quote.
import { createPublicClient, createWalletClient, defineChain, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
const robinhood = defineChain({
id: 4663,
name: 'Robinhood Chain',
nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
rpcUrls: { default: { http: ['https://rpc.mainnet.chain.robinhood.com'] } },
});
const account = privateKeyToAccount(process.env.PAYER_PRIVATE_KEY);
const wallet = createWalletClient({ account, chain: robinhood, transport: http() });
const chain = createPublicClient({ chain: robinhood, transport: http() });
// Only USDG and the escrow: refuse anything else
const allowed = [quote.contract.usdg, quote.contract.escrow].map((a) => a.toLowerCase());
async function send(call) {
if (!allowed.includes(call.to.toLowerCase())) throw new Error(`unexpected target ${call.to}`);
const hash = await wallet.sendTransaction({ to: call.to, data: call.data, value: BigInt(call.value ?? 0) });
await saveHash(hash); // your database, before waiting: never send a call twice
await chain.waitForTransactionReceipt({ hash });
return hash;
}
if (approve.needed) await send(approve);
for (const p of payouts.filter((x) => x.status === 'awaiting_signature')) {
for (const call of p.calls) await nett.payouts.confirm(await send(call));
}The escrow does not deduplicate: a call sent twice escrows twice. Keep each hash; after a crash, confirm it instead of sending again. The full example also decodes every argument before signing. The wallet needs a little ETH on Robinhood Chain for gas.
Confirm
Once a transaction is mined, POST /api/v1/payouts/confirm with its hash. nett reads the receipt on Robinhood Chain and links each order it created to its payout, which turns open.
curl https://www.usenett.app/api/v1/payouts/confirm \
-H "Authorization: Bearer $NETT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"txHash":"0x…"}'Idempotent. Only orders from your app’s wallets, with your refs and exactly your payouts’ parameters, are linked; the others come back in ignored with a reason (unknown_ref, params_mismatch, duplicate). A duplicate is a second order for the same payout: cancel it with cancel(orderId) on the escrow. Not mined yet: 404 tx_not_found, retry. Without a confirm, the payout links once nett’s index reads the order.
Statuses
awaiting_signature- Created. Its calls are not on chain yet.
open- Escrowed, waiting for a provider.
locked- A provider holds it and pays the account in X Money.
pending_recipient- Paid; X Money waits for the recipient to accept.
settled- Proven and paid out.
receiptUrlis its public receipt. refunded- Past its deadline and returned to the payer wallet.
cancelled- Cancelled by the payer before a provider locked it.
expired- Never sent before its deadline. Nothing is on chain.
reopened is a timeline event: a lock lapsed and the payout is open again. Read one with GET /api/v1/payouts/:externalId, or a page with GET /api/v1/payouts?status=open&limit=100&cursor=… (follow nextCursor).
Cancel and refund
Both answer with calls to send from the payer wallet, like the ones that created the order.
- Cancel
POST /api/v1/payouts/:externalId/cancel. While it is open: no provider holds it.- Refund
POST /api/v1/payouts/:externalId/refund. Once its deadline passed, if no provider filled it.- Withdraw
- Both credit the amount plus the max fee to the payer wallet in the escrow, like an unused fee after a fill.
withdraw()on the escrow sends it.
Both are simulated first: when the contract would refuse, 409 not_cancellable or not_refundable (with the contract’s reason), or 409 no_order before anything is on chain. The status follows the chain: payout.cancelled or payout.refunded arrives by webhook once the transaction is mined.
Webhooks
One https URL per app, set in Developers. nett POSTs each event to it, signed with the app’s secret.
- Events
payout.createdpayout.lockedpayout.pending_recipientpayout.reopenedpayout.settledpayout.refundedpayout.cancelled: each carries the whole payout as of that event. Andping, from Send test.- Answer
- Any 2xx within 10 s. The body is ignored.
- Retries
- After 1 min, 5 min, 30 min, 2 h, 6 h and 24 h at the earliest (the dispatcher runs on API and site activity, and at least every 30 min), then the delivery is dead. Resend it from Developers (a test ping is one attempt).
- Backlog
- Up to 500 deliveries waiting per app. Past that, a new event is logged dead (
backlog_full), never sent on its own: resend it, or read the payout. - Duplicates
- Retries keep the event
id: handle each id once. Order is not guaranteed; the payout’sstatusis. - Replays
- Reject a signature timestamp more than 5 minutes off.
- URLs
- https on port 443 or 8443, public hosts only, no user or password. Redirects are not followed.
- Pause
- In Developers. While paused, events are skipped, not queued; Send test and Resend still work.
import { verifyWebhook } from './nett.mjs';
// rawBody: the exact bytes received, before any JSON parser
const event = await verifyWebhook({
rawBody,
signatureHeader: req.headers['nett-signature'],
secret: process.env.NETT_WEBHOOK_SECRET,
}); // throws: signature_mismatch, timestamp_out_of_tolerance ...
if (!(await seen(event.id))) {
if (event.type === 'payout.settled') console.log(event.data.payout.receiptUrl);
}import { createHmac, timingSafeEqual } from 'node:crypto';
// header: "t=1790000000,v1=5257a869…" · secret: "whsec_…"
function verify(rawBody, header, secret) {
const t = /(?:^|,)\s*t=(\d+)/.exec(header)?.[1];
const v1 = /(?:^|,)\s*v1=([0-9a-f]{64})/.exec(header)?.[1];
if (!t || !v1) throw new Error('bad header');
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) throw new Error('stale');
const mac = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
if (!timingSafeEqual(mac, Buffer.from(v1, 'hex'))) throw new Error('bad signature');
return JSON.parse(rawBody);
}POST /nett/webhook HTTP/1.1
Content-Type: application/json
Nett-Event: payout.settled
Nett-Delivery: dlv_8f2k3j4h5g6d
Nett-Signature: t=1790000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
User-Agent: nett-webhooks/1 (+https://www.usenett.app)
{
"id": "evt_9c1f3b7a2d4e6f80",
"type": "payout.settled",
"createdAt": "2026-10-01T12:31:07.000Z",
"data": {
"payout": {
"externalId": "order_1042",
"status": "settled",
"orderId": "128",
"amount": "10.00",
"fee": "0.07",
"feeRefund": "0.03",
"provider": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
"receiptUrl": "https://www.usenett.app/r.html?id=NT-128",
"timeline": [ … ]
}
}
}The signature is HMAC-SHA256 over ${t}.${rawBody}, in hex, keyed with the whole whsec_… string. Rotate it in Developers: the old one stops at once. A ping carries data: {appId}. A full receiver: webhook-server.mjs.
Idempotency
externalId is yours: your order id, say. Retry a create as often as you need.
- Same parameters
- The same payout comes back, with its calls while it awaits signature.
- Other parameters
409 externalId_conflict. Nothing changes.- On chain
- Each order carries
ref = keccak256("nett:v1:" + appId + ":" + externalId), so nett links it back to your payout. - Your side
- The API is idempotent; the chain is not. Store each transaction hash and confirm it rather than resend.
Limits and errors
- Payouts per call
- 1 to 50
- Amount
- From $1.00 to $10,000.00 new providers take up to $100
- Deadline
- 10 minutes to 30 days
- Requests
- 60 a minute per key
- Payouts per app
- 5,000 in all then
409 too_many_payouts: use another app - Handle lookups
- 100 new
@handlesa minute per app passxUserIdand none is needed - Keys · apps · wallets
- 5 active per app · 5 per account · 10 per app
- Lists
- Up to 100 per page, 50 by default, newest first
Errors
JSON with a stable code, a message for people and sometimes details. The HTTP status means what it says.
{
"error": "externalId_conflict",
"message": "this externalId already exists with other parameters",
"details": { "index": 0, "externalId": "order_1042" }
}400- A malformed request:
invalid_request,invalid_amount,invalid_status,invalid_limit,invalid_cursor,invalid_tx_hash. 401missing_api_key,invalid_api_key,revoked_api_key.403browser_not_allowed: a key sent from a browser.404payout_not_found;tx_not_foundwhile a transaction is not mined.409externalId_conflict,too_many_payouts;no_order,not_cancellable,not_refundable;conflict: retry.422- A payout that cannot be paid, with
details.indexanddetails.field:wallet_not_verified,mixed_from,recipient_required,unknown_handle,handle_mismatch,amount_too_low,amount_above_max,max_fee_above_amount,deadline_out_of_range…;tx_reverted. 429rate_limited: waitRetry-Afterseconds.503apps_not_configured: API keys, payouts and webhooks are not open on this deployment yet (GET /api/configsaysfeatures.apps: false; apps and wallets still work in Developers).chain_unavailable: retry.
The SDK throws them as NettError with code, status, message, details and retryAfter.
OpenAPI and SDK
- OpenAPI 3.1
- /openapi.json
- SDK
- /sdk/nett.mjs one file, no dependencies, Node 18+, Deno, Bun
- Examples
- send-with-viem.mjs · webhook-server.mjs
