Skip to main content

Atlas Exchange Service - Overview

Introduction​

The Atlas Exchange Service powers real-time Foreign Exchange (FX) operations across over 100 global currency pairs.

Designed for high-frequency conversion and cross-border settlement, the Exchange service allows business clients and platform partners to:

  • Obtain guaranteed live FX quotes with rate-locking tokens (vfx_token).
  • Query bulk exchange rates across multiple pairs in a single request.
  • Execute conversions between internal multi-currency wallets (convertWithinWallets).
  • Convert funds and execute direct external payouts to verified beneficiaries (convertWalletPayout).
  • Configure customized markup spreads at universal, currency-pair, or sub-account levels.
  • Reconcile settlement states, SWIFT MT103 logs, and UETR tracking codes.

Key Capabilities​

  • Guaranteed Rate Locking: The /fx/quote endpoint returns a short-lived vfx_token that locks the exchange rate for subsequent trade execution, preventing slippage.
  • Dual Trade Execution Modes: Convert between same-entity wallets or execute an integrated FX conversion + payout leg directly to a recipient bank account or mobile wallet.
  • Bulk Market Pricing: Fetch mid-market indicative pricing across dozens of currency corridors via /fx/bulk-rate.
  • Custom Spread Governance: Define custom FX markups as a percentage or fixed rate spread for specific currency corridors or partner sub-accounts.
  • End-to-End Tracking: Trades include SWIFT MT103 confirmation fields and unique end-to-end transaction references (UETR).

Authentication​

All Exchange endpoints require Bearer token authentication in the Authorization header:

Authorization: Bearer <your_access_token>

Base URLs​

Production: https://api.ahrvo.network
Staging:    https://gateway.ahrvo.network

Available Endpoints​

MethodEndpointDescription
POST/fx/quoteFetch live exchange rate quote and receive a short-lived vfx_token
POST/fx/bulk-rateFetch indicative exchange rates for multiple currency pairs simultaneously
POST/fx/paymentsExecute an FX trade (wallet-to-wallet conversion or wallet-to-payout)
GET/fx/{reference}Retrieve full trade status, settlement times, and SWIFT tracking details by reference
POST/fx/listQuery paginated historical trades with multi-field filtering
POST/fx/markup/configSet universal or currency-pair FX markup spread
GET/fx/markup/configRetrieve configured FX markup spreads for your organization

FX Trade Execution Lifecycle​

sequenceDiagram
    autonumber
    actor Client as Business Client
    participant Exchange as Atlas Exchange API
    participant Engine as FX Liquidity Engine
    participant Wallet as Multi-Currency Wallet
    participant Target as Beneficiary Account

    Client->>Exchange: POST /fx/quote (from: USD, to: GBP, amount: 10000)
    Exchange->>Engine: Request streaming rate quote
    Engine-->>Exchange: Locked Rate (0.7850) + vfx_token (valid for quote window)
    Exchange-->>Client: 200 OK (rate: 0.7850, vfx_token, expiry)

    alt Wallet-to-Wallet Conversion
        Client->>Exchange: POST /fx/payments (paymentType: convertWithinWallets, vfxToken)
        Exchange->>Wallet: Debit USD / Credit GBP
        Exchange-->>Client: 200 OK (trade reference: EN-XXXXX, state: confirmed)
    else Wallet-to-Beneficiary Payout
        Client->>Exchange: POST /fx/payments (paymentType: convertWalletPayout, targetAccountId, vfxToken)
        Exchange->>Wallet: Debit USD
        Exchange->>Target: Route GBP via clearing rails (FPS / SEPA / SWIFT)
        Exchange-->>Client: 200 OK (trade reference: EN-XXXXX, state: inwardSettlementDone)
    end

Next Steps​