Currency Swap

Currency swap lets you convert funds between any two currency wallets you hold in your Yativo account — for example, moving USD to BRL, EUR to MXN, or CLP to USD — without sending to an external beneficiary. The flow is two steps: first initiate to preview the rate and terms, then process to execute the conversion and move the balance.

How it works

1. POST /swap/init    → preview rate, receive swap details
2. POST /swap/process → debit from_currency wallet, credit to_currency wallet

Both wallets must exist before swapping. Create missing wallets with POST /wallet/create.

Step 1: Initiate Swap

Preview the exchange rate and resulting converted amount before committing.

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

Requires Idempotency-Key header.

string

required

The source wallet currency code (ISO 4217), e.g. "USD", "EUR".

string

required

The target wallet currency code (ISO 4217), e.g. "BRL", "MXN", "CLP".

number

required

Amount in the source currency to convert.

curl -X POST 'https://api.yativo.com/api/v1/swap/init' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: swap-init-usd-brl-001' \
  -d '{
    "from_currency": "USD",
    "to_currency": "BRL",
    "amount": 500
  }'

const response = await fetch('https://api.yativo.com/api/v1/swap/init', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `swap-init-${Date.now()}`,
  },
  body: JSON.stringify({
    from_currency: 'USD',
    to_currency: 'BRL',
    amount: 500,
  }),
});
const data = await response.json();

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "from_currency": "USD",
    "to_currency": "BRL",
    "from_amount": "500.00",
    "to_amount": "2491.00",
    "exchange_rate": "4.9820",
    "fee": "5.00",
    "fee_currency": "USD"
  }
}

{
  "status": "error",
  "status_code": 400,
  "message": "Insufficient wallet balance"
}

{
  "status": "error",
  "status_code": 422,
  "message": "Invalid currencies supplied"
}

Step 2: Process Swap

Execute the conversion. Funds are debited from the from_currency wallet and credited to the to_currency wallet at the live rate.

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

Requires Idempotency-Key header. Use a new, unique key for the process step — reusing the init key will be rejected.

string

required

The source wallet currency code.

string

required

The target wallet currency code.

number

required

Amount in the source currency to convert.

string

Optional description for this swap, recorded on the transaction record.

curl -X POST 'https://api.yativo.com/api/v1/swap/process' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: swap-process-usd-brl-001' \
  -d '{
    "from_currency": "USD",
    "to_currency": "BRL",
    "amount": 500
  }'

const response = await fetch('https://api.yativo.com/api/v1/swap/process', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `swap-process-${Date.now()}`,
  },
  body: JSON.stringify({
    from_currency: 'USD',
    to_currency: 'BRL',
    amount: 500,
    transaction_purpose: 'Fund BRL wallet for local payouts',
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.yativo.com/api/v1/swap/process',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
        'Idempotency-Key': f'swap-process-{int(time.time())}',
    },
    json={
        'from_currency': 'USD',
        'to_currency': 'BRL',
        'amount': 500,
    }
)

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "from_currency": "USD",
    "to_currency": "BRL",
    "from_amount": "500.00",
    "to_amount": "2491.00",
    "exchange_rate": "4.9820",
    "transaction_type": "currency_swap",
    "gateway_id": "currency_swap",
    "swap_from_currency": "USD",
    "swap_to_currency": "BRL",
    "transaction_purpose": "Fund BRL wallet for local payouts",
    "created_at": "2026-06-01T10:00:00.000000Z"
  }
}

Full example

Node.js — complete swap flow

async function swapCurrency(token, fromCurrency, toCurrency, amount) {
  const BASE = 'https://api.yativo.com/api/v1';
  const headers = {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  };

  // Step 1: Preview the rate
  const initRes = await fetch(`${BASE}/swap/init`, {
    method: 'POST',
    headers: { ...headers, 'Idempotency-Key': `swap-init-${Date.now()}` },
    body: JSON.stringify({ from_currency: fromCurrency, to_currency: toCurrency, amount }),
  });
  const preview = await initRes.json();
  console.log(`Rate: ${preview.data.exchange_rate} — you receive ${preview.data.to_amount} ${toCurrency}`);

  // Step 2: Execute
  const processRes = await fetch(`${BASE}/swap/process`, {
    method: 'POST',
    headers: { ...headers, 'Idempotency-Key': `swap-process-${Date.now()}` },
    body: JSON.stringify({ from_currency: fromCurrency, to_currency: toCurrency, amount }),
  });
  return processRes.json();
}

// Usage
const result = await swapCurrency(token, 'USD', 'BRL', 500);
console.log('Swap complete:', result.data);

Notes

Both wallets must exist before swapping. Create them with POST /wallet/create if needed.
The live rate is fetched at execution time — rates are not locked between /init and /process. Use /init to show the customer a preview, then execute /process promptly.
Swaps are recorded as currency_swap transactions and appear in your transaction history.
Check available wallet balances with GET /wallet/balance before initiating.

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

Regional Guides

How it works

Step 1: Initiate Swap

Step 2: Process Swap

Full example

Notes

​How it works

​Step 1: Initiate Swap

​Step 2: Process Swap

​Full example

​Notes

How it works

Step 1: Initiate Swap

Step 2: Process Swap

Full example

Notes