Payouts

Send tokens from the merchant payout wallet to one or more recipients. Standing wallet authorization and ERC-20 approve / depositETH are done once in the dashboard. The SDK only creates, schedules, and lists payouts.

⚠️

Authorize once in the dashboard

Connect the payout wallet, sign the yearly payout authorization, and approve the token (or depositETH for native) before calling the SDK. Chains and tokens must be enabled by NodeRails admin and on your app — same catalog as checkout.

💡

Chain limits

Bulk (more than one recipient) is EVM only, max 200 lines. Solana is native SOL only, one recipient. Sui create is allowed; schedule and on-chain execute are not enabled. Stored tokenAmount and lines[].amount are atomic integer strings. Bank settlement is dashboard-only — not in the SDK.

Create and send now

amount on each line is a human token amount. The server converts it using the admin token decimals.

Send nowtypescript

const payout = await noderails.payouts.create({
  chain: '11155111',
  tokenAddress: '0x...',
  lines: [
    { recipient: '0xAlice', amount: '100.50' },
    { recipient: '0xBob', amount: '80' },
  ],
  executeNow: true,
});

console.log(payout.id, payout.status, payout.txHash);

Schedule once

Send at a UTC timetypescript

const payout = await noderails.payouts.create({
  chain: '11155111',
  tokenAddress: '0x...',
  lines: [{ recipient: '0xAlice', amount: '100.50' }],
  scheduledAt: '2026-09-01T09:00:00.000Z',
});

Recurring

Every N days in UTC. Timezone-named cron is not in this release.

Every 30 daystypescript

const schedule = await noderails.payoutSchedules.create({
  chain: '11155111',
  tokenAddress: '0x...',
  intervalDays: 30,
  startAt: '2026-09-01T09:00:00.000Z',
  lines: [
    { recipient: '0xAlice', amount: '100.50' },
    { recipient: '0xBob', amount: '80' },
  ],
});

await noderails.payoutSchedules.pause(schedule.id);
await noderails.payoutSchedules.resume(schedule.id);
await noderails.payoutSchedules.cancel(schedule.id);

Address book and payroll CSV

Contactstypescript

await noderails.payoutContacts.create({
  label: 'Alice',
  wallet: '0xAlice',
  family: 'EVM',
});

const preview = await noderails.payoutContacts.importCsv({
  family: 'EVM',
  saveToAddressBook: true,
  csv: 'label,wallet,amount\nAlice,0xAlice,100.50\nBob,0xBob,80',
});

await noderails.payoutContacts.update('contact-id', { label: 'Alice payroll' });

List and cancel

Historytypescript

const page = await noderails.payouts.list({ status: 'EXECUTED', page: 1 });
await noderails.payouts.execute('payout-id');
await noderails.payouts.cancel('payout-id');

Webhooks

Subscribe to payout.executed and payout.failed on your webhook endpoint.

Types

PayoutIntent.statusPENDING | SCHEDULED | EXECUTED | FAILED | CANCELLEDIntent lifecycle

PayoutSchedule.statusACTIVE | PAUSED | CANCELLEDRecurring template