Payouts

Create one-shot or scheduled payouts, recurring schedules, and a per-app address book. Secret API key or dashboard JWT. Amounts on create are human decimal strings.

💡

Standing auth

The payout wallet must already be authorized in the merchant dashboard. ERC-20 payouts need an allowance to Merchant Manager; native EVM payouts spend depositETH.

⚠️

Chain limits

Bulk lines (2–200) are EVM only. Solana is native SOL, one recipient. Sui cannot be scheduled and cannot execute on-chain yet. Create amounts are human decimals; stored amounts are atomic. Bank settlement is a separate dashboard flow, not these endpoints.

Create a payout

POST/payouts

Parameter	Type	Required	Description
`appId`	`string`	Yes	App UUID (SDK sets this)
`chain`	`string`	Yes	Chain id, e.g. 11155111
`tokenAddress`	`string`	Yes	Admin+app catalog token, or native sentinel
`lines`	`{ recipient, amount }[]`	Yes*	1–200 human amounts. *Or recipientWallet + tokenAmount
`scheduledAt`	`string`	No	ISO UTC. Future time → SCHEDULED
`executeNow`	`boolean`	No	Default true when scheduledAt is omitted
`amountUsd`	`string`	No	Record only

List / get / execute / cancel

GET/payouts

GET/payouts/:id

POST/payouts/:id/execute

POST/payouts/:id/cancel

Schedules

POST/payout-schedules

Parameter	Type	Required	Description
`appId`	`string`	Yes	App UUID
`chain`	`string`	Yes	Chain id
`tokenAddress`	`string`	Yes	Catalog token
`lines`	`array`	Yes	Fixed recipients and human amounts
`intervalDays`	`number`	Yes	1–365 UTC days
`startAt`	`string`	No	First run ISO UTC (default now)

GET/payout-schedules

POST/payout-schedules/:id/pause

POST/payout-schedules/:id/resume

POST/payout-schedules/:id/cancel

Address book

POST/apps/:appId/payout-contacts

GET/apps/:appId/payout-contacts

PUT/apps/:appId/payout-contacts/:contactId

DELETE/apps/:appId/payout-contacts/:contactId

POST/apps/:appId/payout-contacts/import

CSV header: label,wallet,amount. Body: csv, family (EVM | SOLANA | SUI), saveToAddressBook.PUT updates label, wallet, or family. Contacts are scoped to the URL appId.

Funding (dashboard)

GET/apps/:id/payout-funding?chainId=

Webhooks

payout.executedeventIntent executed on-chain

payout.failedeventExecute failed; recurring stays ACTIVE

SDKtypescript

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