Exchange (New) - Overview

Introduction

The Exchange (New) API provides high-throughput foreign exchange trading across global and emerging market currencies. It enables businesses to obtain live guaranteed rate quotes, lock rates using time-limited execution tokens, and execute currency conversions seamlessly.

Converted funds can either be credited to an internal destination wallet or paid out directly to an external beneficiary in a single unified operation.

Key Features

• Guaranteed Rate Quotes: Lock in live market rates with a 30-second cryptographic vfx_token.
• Dual Conversion Modes:
  • convertWithinWallets: Convert funds and credit an internal wallet holding the target currency.
  • convertWalletPayout: Convert funds and deliver them directly to an external beneficiary.
• Custom FX Markup Engine: Configure client-side revenue margins either globally (universal) or per currency pair (currency_pair).
• Full Trade Lifecycle: Request quotes, execute trades, retrieve transaction status, and audit trade history with advanced filtering.
• Webhook Status Updates: Receive real-time FX_STATUS_CHANGE notifications when trade execution and settlements conclude.

Authentication

All Exchange API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer <your_access_token>

An optional x-api-key header can also be supplied for merchant environment verification.

Base URLs

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

FX Conversion Workflow

sequenceDiagram
    autonumber
    participant App as Client Application
    participant Rate as FX Rate Service (/fx/rate)
    participant Trade as FX Trade Service (/fx/payments)
    participant Wall as Wallet / Beneficiary Engine

    App->>Rate: POST /fx/rate (currencyFrom: "USD", currencyTo: "NGN", paymentMode: "immediate")
    Rate-->>App: 200 OK (rate: 1028.44, vfx_token, valid 30s)
    Note over App,Trade: Execute within 30-second rate lock
    App->>Trade: POST /fx/payments (vfx_token, sourceWalletId, sourceAmount, paymentType)
    Trade-->>App: 200 OK (trade ID: 20088, reference: EN-10052024-015, status: "COMPLETED")
    Trade->>Wall: Settle destination wallet or dispatch payout

Trade Settlement Types

Payment Type	Description	Required Identifiers
convertWithinWallets	Converts funds from the source wallet and deposits the converted proceeds into another wallet you own.	sourceWalletId, targetWalletId
convertWalletPayout	Converts funds from the source wallet and dispatches the proceeds directly to a registered recipient.	sourceWalletId, targetAccountId, purposeId

Support

For currency pair availability, liquidity limits, or bespoke FX spreads, contact support@ahrvo.com.