Skip to content
Mainnet beta. Unaudited contracts, real funds. Start small.Demo data. Every figure here is simulated. Exit demo
Send payout

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.

  • nett_sk_…
  • 5keys per app

2. Payer wallet

Verify the wallet your app pays from: sign one message with it.

  • EIP-191ERC-1271

3. Payouts

Post up to 50 payouts. Send the calls nett returns from that wallet, then confirm.

  • USDG on Robinhood Chain

4. Webhooks

Signed events as each payout locks, settles or is refunded.

  • HMAC-SHA256retries for a day

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.

HTTP
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_limited with Retry-After.

Quote

What providers charge now, and the two contracts your calls may go to.

shell
curl "https://www.usenett.app/api/v1/quote?amount=10.00" \
  -H "Authorization: Bearer $NETT_API_KEY"

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 from per 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 xUserId when 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.
shell
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"
  }]}'

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.

viem · server.mjs
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.

shell
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. receiptUrl is 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.created payout.locked payout.pending_recipient payout.reopened payout.settled payout.refunded payout.cancelled: each carries the whole payout as of that event. And ping, 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’s status is.
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.
receiver.mjs
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);
}

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 @handles a minute per app pass xUserId and 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.

409 Conflict
{
  "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.
401
missing_api_key, invalid_api_key, revoked_api_key.
403
browser_not_allowed: a key sent from a browser.
404
payout_not_found; tx_not_found while a transaction is not mined.
409
externalId_conflict, too_many_payouts; no_order, not_cancellable, not_refundable; conflict: retry.
422
A payout that cannot be paid, with details.index and details.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.
429
rate_limited: wait Retry-After seconds.
503
apps_not_configured: API keys, payouts and webhooks are not open on this deployment yet (GET /api/config says features.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

Open Developers