Build
Send your first transfer
A complete script that funds a key from the faucet, signs a USD₮ transfer and submits it, in about 30 lines.
This example uses viem and Node 18 or later. Any EVM library that can sign a message works the same way.
npm install viemThe script
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
const API = 'https://usd.net/explorer/testnet/api/v1';
const CHAIN = 'usdnet-testnet-1';
const post = (path, body) =>
fetch(API + path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
.then(async (r) => ({ status: r.status, body: await r.json() }));
// 1. A key. Use your own with PRIVATE_KEY=0x… or let the script make one.
const account = privateKeyToAccount(process.env.PRIVATE_KEY || generatePrivateKey());
const from = account.address.toLowerCase();
const to = '0x38496f6877382de8255668ae407f4c0ea2acc0f7';
// 2. Test dollars.
await post('/faucet', { address: from });
// 3. The account's next nonce. Accounts are confidential, so the read is signed with the account's key.
const until = Date.now() + 10 * 60_000;
const pass = `${from}.${until}.${await account.signMessage({ message: ['USD Network read', `Chain: ${CHAIN}`, `Address: ${from}`, `Until: ${until}`].join('\n') })}`;
const { nonce } = await fetch(`${API}/address/${from}`, { headers: { 'x-usd-read': pass } }).then((r) => r.json());
// 4. The transfer message, exactly as the network rebuilds it.
const transfer = { from, to, amount: '12.5', fee: '0.01', nonce, memo: 'Hello from the docs' };
const message = [
'USD Network transfer',
`Chain: ${CHAIN}`,
`From: ${transfer.from}`,
`To: ${transfer.to}`,
`Amount: ${transfer.amount} USDT`,
`Fee: ${transfer.fee} USDT`,
`Nonce: ${transfer.nonce}`,
...(transfer.memo ? [`Memo: ${transfer.memo}`] : []),
].join('\n');
// 5. Sign with EIP-191 personal_sign and submit.
const sig = await account.signMessage({ message });
const res = await post('/tx', { ...transfer, sig });
console.log(res.status, res.body);node send.mjsThe response
A 201 means the transfer was accepted. Because blocks are sealed as transfers arrive, it is normally already final:
{
"type": "transfer",
"from": "0x1323a980c3e4736108741dacdad57d08e60bd827",
"to": "0x38496f6877382de8255668ae407f4c0ea2acc0f7",
"amount": "12.5",
"fee": "0.01",
"nonce": 0,
"memo": "Hello from the docs",
"time": 1793731653002,
"sig": "0x2c96fda2…1ca36b3b0b1c",
"hash": "0x85d82a5cd8488ef23a7bf9c63954243d0b2c2ec86496b5d13245d3d0d49e2d63",
"status": "final",
"block": 5,
"index": 0
}Open https://usd.net/explorer/tx/<hash> to see it. Sending the same signed transfer again returns 409 Expected nonce 1, because each nonce can be used once.
Next
- Signing transfers explains every line of the message.
- Errors lists what can go wrong and what to do.
- Verify it yourself proves block 5 is in the signed log.