Exchange

The Exchange APIs allow you to convert between currencies. There are two mechanisms depending on whether you want to convert within your own wallets or send directly to an external beneficiary.

Exchange Methods

MethodDescriptionWallet Balance RequiredBeneficiary RequiredPayment Instructions
SwapConvert between currencies within your own walletsYesNoNo
Direct ExchangeConvert and send to an external beneficiary in one stepNoYesYes

Swap vs Direct Exchange

Swap

A Swap converts funds between different currencies within your own wallets. For example, converting USD in your USD wallet to EUR in your EUR wallet.

  • Requires wallet balance in the source currency
  • No external beneficiary — funds stay in your wallets
  • Conversion happens immediately upon quote acceptance
  • Uses quote_type: "SWAP"

Direct Exchange

A Direct Exchange converts funds and sends them directly to an external beneficiary without requiring a wallet balance. You receive payment instructions after accepting the quote, send the funds, and the payout is delivered to the beneficiary.

  • No wallet balance required — you deposit funds after accepting the quote
  • External beneficiary required — funds are sent to the recipient
  • Payment instructions provided after quote acceptance
  • Uses quote_type: "DIRECT_EXCHANGE"

Common Flow

Both methods use the Quotes API:

  1. Create a Quote — POST /api/v1/client/quotes with the appropriate quote_type
  2. Accept the Quote — POST /api/v1/client/quotes/{id}/accept
  3. Process — For Swap, conversion is immediate. For Direct Exchange, follow the payment instructions.
  4. Webhook — Receive a transaction webhook on completion.

Authentication

All exchange endpoints require HMAC authentication:

http
x-api-key: <your-api-key>x-timestamp: <rfc3339-timestamp>x-signature: <hmac-sha256-signature>

For details, see the Authentication documentation.

Prerequisites

  • origin_reference — Unique transaction ID for idempotency (required for all business API requests)
  • on_behalf_of — Required for business API: "self" for the business owner's account, or a customer user ID (see Quotes API)
  • Beneficiary — Required for Direct Exchange only. Create via Beneficiaries API.

Next Steps

  • Swap — Convert between currencies within your wallets
  • Direct Exchange — Convert and send to an external beneficiary
  • Quotes API — Full quote API reference
  • Exchange Rates — Preview rates before creating a quote