Skip to main content
Cross-border transfers move money between currencies — USD to EUR, USDC to EURC, USD to BRL via Pix, etc. They always need a quote first to lock in the FX rate.

1. Request a quote

Quotes live for ~30 seconds. If the user takes longer to confirm, re-quote.

2. Show the quote to the user (if applicable)

If there’s a human in the loop, show them:
  • “You send $1000.00 USD”
  • “They receive €928.40 EUR”
  • “Fee: $2.50 USD”
  • “This rate expires in 30 seconds”
Even agent-driven flows should log the quote — auditability matters.

3. Execute the transfer

The transfer inherits amounts + rate + fee from the quote.
Always use an idempotency_key. If your process crashes after POSTing but before receiving the response, you don’t want a duplicate transfer on retry. Keys are cached 24 hours.

4. Watch it settle

Three options: Webhook (recommended):
SSE (if the originator is an agent):
Poll:
Typical live settlement times:
  • USDC → USDC: ~10 seconds
  • USDC → fiat (ACH): 1-2 business days
  • USD → USDC (on-ramp): 30 seconds to a few minutes
  • USD → EUR bank wire: 1 business day

5. Handle failure

For INSUFFICIENT_BALANCE, funds never left your wallet — retry after topping up. For RAIL_DECLINED, the receiving bank rejected — usually a bad account number or compliance flag. Surface to the user, don’t auto-retry. For SANCTIONS_HIT, the destination hit a sanctions list. Do not retry; escalate to compliance.

Quote expiry

If you wait too long between quote and execute, the transfer returns QUOTE_EXPIRED. Re-quote and try again:
Or just re-quote right before each transfer — quotes are cheap.

Compliance holds

Large cross-border transfers may pause in processing pending compliance review. You’ll see a compliance.review_required webhook. The transfer either:
  • Completes after review (most common)
  • Fails with HIGH_RISK_TRANSACTION (rare — flags for manual resolution)
Don’t build UIs that assume sub-minute settlement for amounts over $10k.

Rails available

Supported per-currency pairs and rails are discoverable: