Currency Swap

A swap converts balance from one of your wallets to another, for example from your USD wallet to your USDC wallet. No beneficiary is involved, and the swap completes immediately. You can only swap between the currency pairs Yativo has enabled for your account. Each pair has its own rate, fees and amount limits.

How it works

GET  /wallet/swap/pairs  → see which pairs you can swap, with rates and fees
POST /wallet/swap/quote  → price a swap without moving money
POST /wallet/swap        → debit the source wallet and credit the destination wallet

The fee is charged in the source currency and deducted before conversion:

fee       = fixed_fee + amount × percent_fee / 100
fee       = max(fee, min_fee)   // when min_fee is set
fee       = min(fee, max_fee)   // when max_fee is set
to_amount = (amount − fee) × rate

to_amount is rounded down to the destination currency’s decimal places. You need a wallet in the source currency. If you don’t have a wallet in the destination currency yet, Yativo creates it on your first swap into it.

Team members need the Wallets → view permission to list pairs, quote and view swaps, and Wallets → manage to run a swap.

List swap pairs

GET https://api.yativo.com/api/v1/wallet/swap/pairs

Returns every pair you can swap, with its current rate and fees.

curl -X GET 'https://api.yativo.com/api/v1/wallet/swap/pairs' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": [
    {
      "from_currency": "USD",
      "to_currency": "USDC",
      "rate": 1,
      "fixed_fee": 0,
      "percent_fee": 0.5,
      "min_fee": 1,
      "max_fee": null,
      "min_amount": 10,
      "max_amount": 50000
    }
  ]
}

Field	Description
`rate`	Units of `to_currency` per unit of `from_currency`. Applied after the fee is deducted
`fixed_fee`	Flat fee in `from_currency`
`percent_fee`	Percentage of the amount, charged in `from_currency`
`min_fee`, `max_fee`	Lower and upper bounds on the fee. `null` means no bound
`min_amount`, `max_amount`	Smallest and largest `amount` you can swap, in `from_currency`. `null` means no limit

Quote a swap

POST https://api.yativo.com/api/v1/wallet/swap/quote

Prices a swap without moving money. Use it to show the fee and the amount you’ll receive before you confirm.

string

required

Currency of the wallet to debit, for example "USD".

string

required

Currency of the wallet to credit, for example "USDC". Must differ from from_currency.

number

required

Amount to swap, in from_currency, including the fee. Must be greater than 0.

curl -X POST 'https://api.yativo.com/api/v1/wallet/swap/quote' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: swap-quote-001' \
  -d '{
    "from_currency": "USD",
    "to_currency": "USDC",
    "amount": 1000
  }'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "from_currency": "USD",
    "to_currency": "USDC",
    "from_amount": 1000,
    "fee": 5,
    "net_amount": 995,
    "rate": 1,
    "to_amount": 995,
    "available_balance": 2500
  }
}

{
  "status": "failed",
  "status_code": 422,
  "message": "Request failed.",
  "data": {
    "error": "Swapping USD to EUR is not available."
  }
}

Field	Description
`from_amount`	Amount debited from the source wallet
`fee`	Fee in `from_currency`, included in `from_amount`
`net_amount`	`from_amount` minus `fee`. This is the amount converted
`rate`	Rate applied to `net_amount`
`to_amount`	Amount credited to the destination wallet
`available_balance`	Your current balance in the source wallet

A quote doesn’t reserve the rate or your balance. The swap uses the pair’s rate and fees at the moment you run it.

Run a swap

POST https://api.yativo.com/api/v1/wallet/swap

Debits the source wallet and credits the destination wallet in one step. If the credit fails, the debit is reversed. Takes the same body as Quote a swap, plus:

string

Alternative to the Idempotency-Key header, up to 100 characters.

Send a unique Idempotency-Key header. If you retry with the same key, you get the original swap back and no second swap runs.

curl -X POST 'https://api.yativo.com/api/v1/wallet/swap' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: swap-usd-usdc-001' \
  -d '{
    "from_currency": "USD",
    "to_currency": "USDC",
    "amount": 1000
  }'

const response = await fetch('https://api.yativo.com/api/v1/wallet/swap', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.YATIVO_API_KEY,
    'X-Api-Secret': process.env.YATIVO_API_SECRET,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    from_currency: 'USD',
    to_currency: 'USDC',
    amount: 1000,
  }),
});
const { data: swap } = await response.json();

import os, uuid, requests

response = requests.post(
    'https://api.yativo.com/api/v1/wallet/swap',
    headers={
        'X-Api-Key': os.environ['YATIVO_API_KEY'],
        'X-Api-Secret': os.environ['YATIVO_API_SECRET'],
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={'from_currency': 'USD', 'to_currency': 'USDC', 'amount': 1000},
)
swap = response.json()['data']

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "reference": "9b1f0c52-3a8e-4f4e-b2a1-6f0e5d7c8a91",
    "from_currency": "USD",
    "to_currency": "USDC",
    "from_amount": 1000,
    "fee": 5,
    "rate": 1,
    "to_amount": 995,
    "status": "completed",
    "created_at": "2026-10-20T10:15:00+00:00"
  }
}

{
  "status": "failed",
  "status_code": 422,
  "message": "Request failed.",
  "data": {
    "error": "Insufficient balance or invalid debit wallet."
  }
}

Keep the reference. Use it to look the swap up later. Each swap also appears in your transaction history as two entries of type swap: the debit from the source wallet and the credit to the destination wallet.

List swaps

GET https://api.yativo.com/api/v1/wallet/swap

Returns your swaps, newest first, 10 per page. Use page and per_page to page through them.

curl -X GET 'https://api.yativo.com/api/v1/wallet/swap?page=1&per_page=20' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "current_page": 1,
    "data": [
      {
        "reference": "9b1f0c52-3a8e-4f4e-b2a1-6f0e5d7c8a91",
        "from_currency": "USD",
        "to_currency": "USDC",
        "from_amount": 1000,
        "fee": 5,
        "rate": 1,
        "to_amount": 995,
        "status": "completed",
        "created_at": "2026-10-20T10:15:00+00:00"
      }
    ],
    "per_page": 20,
    "last_page": 1,
    "total": 1
  }
}

Get a swap

GET https://api.yativo.com/api/v1/wallet/swap/{reference}

string

required

The reference returned when you ran the swap.

curl -X GET 'https://api.yativo.com/api/v1/wallet/swap/9b1f0c52-3a8e-4f4e-b2a1-6f0e5d7c8a91' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

Returns the same object as Run a swap, or 404 with Swap not found if the reference isn’t one of yours.

USDC wallet

Your USDC wallet funds corporate cards. You can swap into it from USD only, and you can’t swap out of it. A swap from USDC, or into USDC from any currency other than USD, fails with Invalid wallet selected.

Errors

Swap errors return 422 with a message in data.error, except a missing swap, which returns 404.

Message	Cause
`Swapping {FROM} to {TO} is not available.`	The pair isn’t enabled for your account. Check `GET /wallet/swap/pairs`
`Minimum swap amount is {min} {FROM}.`	`amount` is below the pair’s `min_amount`
`Maximum swap amount is {max} {FROM}.`	`amount` is above the pair’s `max_amount`
`You don't have a {FROM} wallet.`	You have no wallet in the source currency
`Amount is too small to cover the swap fee.`	The fee is equal to or larger than `amount`
`Amount is too small to swap.`	`to_amount` would round down to 0
`Insufficient balance or invalid debit wallet.`	The source wallet’s balance is lower than `amount`
`Invalid wallet selected.`	The swap would debit your USDC wallet, or credit it from a currency other than USD

A validation error, such as a missing field or to_currency equal to from_currency, returns the failing fields in data:

{
  "status": "failed",
  "status_code": 422,
  "message": "Request failed.",
  "data": {
    "to_currency": ["The to currency field and from currency must be different."]
  }
}

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

Regional Guides

How it works

List swap pairs

Quote a swap

Run a swap

List swaps

Get a swap

USDC wallet

Errors

​How it works

​List swap pairs

​Quote a swap

​Run a swap

​List swaps

​Get a swap

​USDC wallet

​Errors

How it works

List swap pairs

Quote a swap

Run a swap

List swaps

Get a swap

USDC wallet

Errors