Payouts and rails

POST/v1/payouts

Scope payouts:write (provider key). Pays out from your settlement wallet.

Field	Type	Required	Notes
`walletId`	string	yes	your settlement wallet
`amountMinor`	string	yes	cents
`rail`	`"bank_transfer"` \| `"ach"` \| `"usdc_base"`	yes
`destination`	string	no	leave it out to use your registered destination. Recommended
`treasuryProviderId`	string	no	only if two payout providers serve the same rail

It's idempotent per payout. On a real rail it returns status: "submitted": your wallet has been debited and the money is in transit. It becomes confirmed when the rail confirms, or returned (re-credited with a new entry) if the payment comes back.

Refusals: DESTINATION_COOLING_DOWN, SANCTIONED_ADDRESS, TREASURY_UNAVAILABLE, COVERAGE_SHORTFALL, INSUFFICIENT_FUNDS. See Earnings and payouts.

GET/v1/rail/providers

Scope rail:read. What this deployment can do. Ask before offering a funding or payout option.

JSON

{
  "sandbox": false,
  "providers": [{
    "id": "circle", "name": "Circle", "adapterType": "custodian", "status": "active",
    "roles": ["funding", "payout"], "currencies": ["USDC"], "rails": ["usdc_base"],
    "topUps": false, "depositAddresses": true, "faucet": false
  }]
}

roles says what a provider is allowed to do. topUps, depositAddresses and faucet say what you can ask it for. sandbox: true means development shortcuts such as POST /v1/wallets/:id/fund work.

GET/v1/rail/transactions

Scope rail:read. Every deposit and payout on wallets you own, with its state (pending, held, submitted, confirmed, returned …) and both amounts: the amount on the rail, and the amount credited in USD.