Wallet Conversions

Move money between your own wallets, debit one currency, credit another at the rate Swappr quotes for that pair.

Conversions work in either direction (e.g. USD → NGN or NGN → USD). A conversion succeeds only when an active rate is available for that exact from_currency → to_currency pair, otherwise it’s rejected and no money moves.

The result is environment-scoped to your API key: a sandbox (sk_test_…) key converts your sandbox wallets; a live (sk_live_…) key converts your live wallets.

Before you convert

Enable the capability on your key. The API key must carry the conversion capability, enable it in the dashboard under API keys (it mirrors the cross-currency-payout capability). A key without it gets 403.
The rate is applied at execution. The value you preview can change before you send; a rate that is being refreshed is rejected (fx_rate_stale) and no money moves.
Idempotency-Key is required. Send a unique value per logical conversion. A retry with the same key returns the same conversion (200); the same key with a genuinely different conversion is a 409 conflict.

POSTCreate conversion

POST/v1/conversions

Debit one wallet and credit another at the rate Swappr quotes for the pair. Provide exactly one amount basis:

from_amount_minor: source basis: the exact amount to debit from your from_currency wallet. The credited amount is derived at the rate.
to_amount_minor: target basis: the exact amount to credit to your to_currency wallet. The debited amount is derived at the rate.

Request body

from_currencystringRequired

The currency to debit (ISO 4217, e.g. USD).

to_currencystringRequired

The currency to credit (ISO 4217, e.g. NGN). Must differ from from_currency.

from_amount_minorstring

Source basis, the exact amount to debit (minor units; string for values > 2⁵³). XOR with to_amount_minor.

to_amount_minorstring

Target basis, the exact amount to credit (minor units). XOR with from_amount_minor.

Response fields

Field	Type	Notes
`object`	string	Always `conversion`.
`id`	string	The conversion id.
`from_currency` / `to_currency`	string	The pair converted.
`from_amount_minor`	string	Debited from your `from_currency` wallet (minor units).
`to_amount_minor`	string	Credited to your `to_currency` wallet (minor units).
`rate`	string	Destination-per-source rate applied, as a decimal string.
`status`	string	`completed`.

Errors

Code	HTTP	Cause
`ambiguous_amount`	400	Both `from_amount_minor` and `to_amount_minor` were sent.
`amount_required`	400	Neither amount was sent.
`invalid_currency_pair`	400	`from_currency` equals `to_currency`.
`unsupported_currency`	400	A currency code is not valid.
`permission_denied`	403	The API key isn’t enabled for conversions.
`idempotency_conflict`	409	The `Idempotency-Key` was already used for a different conversion.
`fx_rate_unavailable`	422	No active rate for this pair.
`fx_rate_stale`	422	The rate is being refreshed, retry shortly. No money moved.
`fx_rate_inverted`	422	The rate isn’t available to convert at right now.
`insufficient_funds`	402	Your `from_currency` wallet balance is too low.
`fx_convert_unavailable`	503	Conversions for the destination currency aren’t available right now (temporary).
`fx_exposure_cap_exceeded`	422	The conversion is above the current limit, try a smaller amount.

Request

# Convert $1,000.00 (100000 minor) USD into NGN (source basis)
curl -X POST 'https://api.swappr.me/api/v1/conversions' \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "USD",
    "to_currency": "NGN",
    "from_amount_minor": "100000"
  }'

import { randomUUID } from 'crypto';
 
async function convert() {
  const res = await fetch('https://api.swappr.me/api/v1/conversions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SWAPPR_API_KEY}`,
      'Idempotency-Key': randomUUID(),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from_currency: 'USD',
      to_currency: 'NGN',
      from_amount_minor: '100000', // debit exactly $1,000.00
    }),
  });
  return res.json();
}

import os, uuid, requests
 
def convert():
    res = requests.post(
        'https://api.swappr.me/api/v1/conversions',
        headers={
            'Authorization': f"Bearer {os.environ['SWAPPR_API_KEY']}",
            'Idempotency-Key': str(uuid.uuid4()),
        },
        json={
            'from_currency': 'USD',
            'to_currency': 'NGN',
            'from_amount_minor': '100000',  # debit exactly $1,000.00
        },
    )
    res.raise_for_status()
    return res.json()

Response

{
  "object": "conversion",
  "id": "cmq...",
  "from_currency": "USD",
  "to_currency": "NGN",
  "from_amount_minor": "100000",
  "to_amount_minor": "130000000",
  "rate": "1300.0",
  "status": "completed"
}

201 Created

POSTPreview conversion

POST/v1/conversions/quote

Read-only, advisory preview. Resolves the active rate for the pair and derives the exact debit/credit at the given basis. No money moves, no row is written, no capability gate, a valid key is the only requirement.

The request takes the same fields as a conversion (from_currency, to_currency, and exactly one of from_amount_minor / to_amount_minor).

Response fields

Field	Type	Notes
`object`	string	Always `conversion_quote`.
`from_amount_minor`	string	What would be debited (minor units).
`to_amount_minor`	string	What would be credited (minor units).
`rate`	string	Destination-per-source rate, as a decimal string.
`as_of`	string \| null	When the active rate was approved (indicative).
`indicative`	boolean	Always `true`, the binding rate applies at execution.

Request

curl -X POST 'https://api.swappr.me/api/v1/conversions/quote' \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "USD",
    "to_currency": "NGN",
    "from_amount_minor": "100000"
  }'

Response

{
  "object": "conversion_quote",
  "from_currency": "USD",
  "to_currency": "NGN",
  "from_amount_minor": "100000",
  "to_amount_minor": "130000000",
  "rate": "1300.0",
  "as_of": "2026-07-12T09:00:00.000Z",
  "indicative": true
}

200 OK

Rates Collections