Agent wallet routing and failover, explained step by step
Routing is what turns a pile of connected wallets into a single reliable payment rail. Here is exactly what happens between your API request and the money moving.
Last updated: 9 September 2026
Step 1 — the request is locked to your Agent ID
Every request carries an Agent ID. The engine can only touch wallet channels connected under that ID, so one customer's traffic can never be routed through another customer's wallets.
Step 2 — eligibility checks before every attempt
Before a wallet is used, the engine checks available balance, the per-transaction limit, the per-minute count, the daily ceiling and whether the wallet is in cooldown. Any wallet that fails a check is skipped silently.
This is the cheapest possible failure: skipping an ineligible wallet costs nothing, while attempting one costs a failed transaction and often a provider-side penalty.
Step 3 — round-robin rotation for payouts
Payouts rotate across eligible wallets rather than draining one. Rotation spreads volume, keeps every channel inside its daily pattern and reduces the chance that a provider flags unusual activity on a single number.
Step 4 — failover on the same order ID
If an attempt fails at the provider, the engine moves to the next eligible wallet under the same order ID. Your platform sees one order and one final result, not a chain of retries.
Because the order ID stays constant, your webhook handler stays simple: it only has to be idempotent on order ID and verify the signature before processing.
Step 5 — reconciliation
Transactions that stay pending beyond the provider SLA are reconciled automatically. If the provider confirms non-delivery, the amount is released and any fee reversed in the next settlement cycle.