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 Postman quickstart