FX conversions

Convert money between two of your accounts in different currencies, at a rate you see and lock before any money moves. Use it to hold USD from NGN, or to fund a payout in a currency you don't hold yet.

In short:

1. Get a quote: ask for a rate to receive an amount in the target currency. The quote is valid for about 60 seconds.
2. Lock it: confirm the quote with the two accounts. The source account is debited and the target account credited, usually during the call.
3. Confirm: check the lock response's status, or wait for the trade_completed webhook.

How it works

sequenceDiagram
    autonumber
    participant You as Your backend
    participant MG as Multigate
    You->>MG: GET /fx-rates/best-rate (source, target, amount to receive)
    MG-->>You: Quote id, buyRate, sellRate, endTime (about 60 seconds)
    You->>MG: POST /fx-rates/lock-rate (quote id, accounts, amount)
    Note over MG: Check balance, debit source account,<br/>book with the liquidity provider,<br/>credit target account
    MG-)You: trade / trade_completed (can arrive before the response)
    MG-->>You: Conversion: status completed (or processing)
    Note over MG,You: processing: trade_completed follows when the credit settles

Two calls, no separate fee: Multigate's margin is built into the rate.

Before you start

• MG_BASE_URL, MG_API_KEY and MG_CLIENT_ID are set, as in the Quickstart.
• One active account in each currency, both yours, or both the same customer's. You need their accountId values (not account numbers). Put them in variables:

curl -s "$MG_BASE_URL/client-service/api/v1/accounts?pageSize=50" \
  -H "mp-api-key: $MG_API_KEY" \
  | jq '.data[] | {accountId, currencyIso3Code, status}'
export MG_NGN_ACCOUNT_ID="accountId of your NGN account"
export MG_USD_ACCOUNT_ID="accountId of your USD account"

• The source account funded with more than the amount that will be debited. Check it with Get an account balance before you lock.
• The entityId header set to your client ID on every conversion request. Without it, the service uses the business your API key belongs to.
• Permissions: lock rates (can_lock_rates) to quote and lock; view rates (can_view_rates) or lock rates to read conversions.
• For a customer: pass onBehalfOf when you get the quote. See Acting for customers.

Convert

QUOTE=$(curl -s "$MG_BASE_URL/trade-service/api/v1/fx-rates/best-rate?sourceCurrency=NGN&targetCurrency=USD&amount=1000" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "entityId: $MG_CLIENT_ID")
echo "$QUOTE"
export MG_QUOTE_ID=$(echo "$QUOTE" | jq -r .id)

{
  "message": "The FX rate has been successfully fetched.",
  "id": "FX-261010-150000482913",
  "sourceCurrency": "NGN",
  "targetCurrency": "USD",
  "buyRate": 1530.5,
  "sellRate": 0.0006533812479581836,
  "validityPeriod": 60,
  "startTime": "2026-10-10T15:00:00.000Z",
  "endTime": "2026-10-10T15:01:00.000Z",
  "createdAt": "2026-10-10T15:00:00.482Z",
  "updatedAt": "2026-10-10T15:00:00.482Z"
}

curl -s -X POST "$MG_BASE_URL/trade-service/api/v1/fx-rates/lock-rate" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "entityId: $MG_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "id": "$MG_QUOTE_ID",
  "sourceAccountId": "$MG_NGN_ACCOUNT_ID",
  "targetAccountId": "$MG_USD_ACCOUNT_ID",
  "amount": 1000,
  "reference": "acme_conv_$(date +%s)"
}
EOF

{
  "message": "The FX rate has been successfully locked.",
  "id": "FX-261010-150000482913",
  "status": "completed",
  "sourceCurrency": "NGN",
  "sourceAmount": "1530500",
  "targetCurrency": "USD",
  "targetAmount": "1000",
  "rate": "0.0006533812479581836",
  "tradeReference": "acme_conv_1791640820",
  "sourceAccountNumber": "1029384756",
  "targetAccountNumber": "4410023391",
  "valueDate": "2026-10-10T15:00:20.114Z",
  "createdAt": "2026-10-10T15:00:20.114Z",
  "updatedAt": "2026-10-10T15:00:21.902Z"
}

Conversion statuses

stateDiagram-v2
    direction LR
    [*] --> completed: credited straight away
    [*] --> processing: debited, credit waiting for settlement
    [*] --> awaiting_balance: post-funded, short of funds
    [*] --> failed: provider refused at lock time
    awaiting_balance --> processing: account funded and debited
    processing --> completed: settled and credited
    processing --> failed: provider failed (pairs priced through USD)
    completed --> [*]
    failed --> [*]

Handling trade_completed

• Match the event to your conversion by id, which is the quote ID. tradeReference is your reference (or one Multigate generated).
• Store the quote ID before you call lock: the event can arrive before the lock response.
• Read the amounts from your lock response or Get a conversion. For pairs priced through USD, an event sent after a processing conversion settles can carry the amounts of one leg (to or from USD) and a Multigate-generated tradeReference.
• Deduplicate by Idempotency-Key and by quote ID: the same conversion can be notified more than once.

Retrying safely

Lock has no idempotency key, but a quote can be locked only once. That makes the quote ID your retry key.

If a lock call times out, the connection drops, or you get a 5xx:

1. Call Get a conversion with the quote ID. If it's found, that is your conversion: follow its status.
2. If it isn't found, send the same lock request again (same quote ID, same reference):
   • 409 "Rate already locked": the first attempt is recorded or still running. Wait a few seconds and call Get a conversion again.
   • 400 "Rate expired": no conversion was recorded for this quote. Check the source account balance for a debit you can't explain before you get a new quote, and contact support with the quote ID if you find one.
   • 200: converted.
3. Never lock a new quote for the same purpose until you've confirmed the first one didn't go through.

503 "Failed to execute trade, please reach out to support" means Multigate couldn't reserve the quote: nothing was debited, so retry the same request shortly. The same message with 400 means the provider refused and the conversion failed, so always check the HTTP status, not just the message.

Use a new reference for every conversion, including after a failed one: a reused value returns 409 "Duplicate reference". References must be unique across Multigate, so add your own prefix or use a UUID.

Which pairs you can convert

Pairs depend on the liquidity Multigate has configured. Get a quote to check a pair: an unavailable pair returns 404 (or 400) "Rates for this currency pair are currently unavailable."

• Pairs that include USD are quoted directly. Other pairs are priced through USD.
• USD to NGN, USD to GHS and USD to ETB are quoted for information only. Locking them returns 404 "The rate is not currently tradeable". They exist because many treasury systems expect a buy and a sell rate for every pair: the rate is derived from the opposite direction (for example NGN to USD) with a margin, so you can display it, not trade on it.

Errors

Next steps

• Payouts: pay out from the target account.
• Event catalogue: the trade_completed payload.
• Balances and statements: reconcile the debit and the credit.
• Cross-border payouts: convert, then pay a supplier.