Multi-Rail Orchestration API
Canonical request schemas, accepted enumerations, and currency/atomic unit definitions matching the deployed payout endpoints.
/api/v1/payouts/v2On-chain XRPL Testnet settlement using classic r-address or X-address.
{
"Content-Type": "application/json",
"x-api-key": "ipx_test_...",
"Idempotency-Key": "idem_xrpl_20261011_001"
}{
"to": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
"amount": 85.5,
"currency": "USD",
"chain": "xrpl",
"asset": "RLUSD",
"memo": "Shift payment #4102",
"dryRun": false
}Deployed Request Schema & Accepted Enumerations
| Field / Header | Type | Requirement | Accepted Values & Semantics |
|---|---|---|---|
| Idempotency-Key (Header) | string | Required | Merchant-scoped unique key (composite primary key (merchant_id, key)). Reusing a key with different payload parameters returns HTTP 409 IDEMPOTENCY_KEY_REUSED. |
| to | string | Required | Recipient destination: XRPL/Xahau classic address (r...) or X-address (X...), Base EVM address (0x...), Column counterparty ID (cpty_...) or routing:account, or PayPal email. |
| amount | number | Required (if amountAtomic omitted) | Positive JSON number in major currency units (e.g. 85.5 for $85.50, max 10000000). Do not pass a string. |
| amountAtomic | integer | Optional (alternative to amount) | Positive integer in minor/atomic units: 100 units = $1.00 (cents) when rail is set (ach, rtp, fednow); 1,000,000 units = $1.00 (6-decimal drops/USDC/RLUSD) on xrpl, xahau, and base. |
| chain | enum | Default: "base" | Accepted values: "xrpl" | "xahau" | "base" | "solana". Used when rail is omitted. |
| rail | enum | Optional | On /api/v1/payouts/v2: "ach" | "rtp" | "fednow".On /api/v1/payouts/v1: "ach" | "rtp" | "fednow" | "wire" | "paypal".When rail is provided, it takes precedence over chain. |
| currency | enum | Default: "USD" | Fiat denomination currency: "USD" | "EUR" | "GBP". Token symbols belong in asset, not currency. |
| asset | enum | Optional | Settlement asset/token: "USD" | "USDC" | "RLUSD" | "XRP" | "XAH" | "SOL" | "EUR" | "GBP". Defaults by chain (XRP on XRPL, XAH on Xahau, USDC on Base). |
| memo | string | Optional | Optional payment reference / memo (max 500 characters). Included in the idempotency request hash. |
| dryRun | boolean | Default: false | When true, executes preflight validation and fee estimation without broadcasting a transfer. |
Rail & Currency / Unit Reference Matrix
| Rail / Chain | Selector Field | Supported Assets | amount Unit | amountAtomic Unit |
|---|---|---|---|---|
| XRPL | chain: "xrpl" | "RLUSD" | "XRP" | Decimal USD (e.g. 85.5) | 6-decimal drops (10,000 = 1 cent) |
| Xahau | chain: "xahau" | "XAH" | Decimal USD (e.g. 85.5) | 6-decimal drops (10,000 = 1 cent) |
| Base (EVM) | chain: "base" | "USDC" | Decimal USD (e.g. 85.5) | 6-decimal USDC units (10,000 = 1 cent) |
| Column ACH | rail: "ach" | "USD" | Decimal USD (e.g. 85.5) | Integer USD cents (8550 = $85.50) |
| Column RTP / FedNow | rail: "rtp" | "fednow" | "USD" | Decimal USD (e.g. 85.5) | Integer USD cents (8550 = $85.50) |
| PayPal | rail: "paypal" (v1) | "USD" | Decimal USD (e.g. 85.5) | Integer USD cents (8550 = $85.50) |
Rail-Level Error Handling & Reject Codes
InstaPay IPX returns deterministic error codes when schema validation, idempotency isolation, compliance screening, or finality verification fails.
Missing required Idempotency-Key HTTP header. Every payout request must include a unique Idempotency-Key header.
The supplied Idempotency-Key was already used by this merchant with a different request fingerprint (to, amount, chain, rail, currency, memo).
A concurrent request with the same Idempotency-Key (or gig job lock) is currently executing. Do not submit a duplicate request.
Recipient wallet address failed classic/X-address or EIP-55 / 20-byte hex checksum pre-validation.
Merchant or worker subject wallet has not completed cryptographic ownership verification.
Payout amount exceeds the worker's configured daily_payout_limit_cents or merchant's monthly_volume_limit_cents.
Network timeout or persistence interruption occurred after broadcast. Payout is locked in transit hold (transit:payout:<id>) for automated ReconciliationEngine verification; automatic cross-rail fallback is blocked.