Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yativo.com/llms.txt

Use this file to discover all available pages before exploring further.

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.
​
from_currency
string
required
The source wallet currency code (ISO 4217), e.g. "USD", "EUR".
​
to_currency
string
required
The target wallet currency code (ISO 4217), e.g. "BRL", "MXN", "CLP".
​
amount
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
  }'

{
  "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"
  }
}

​
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.
​
from_currency
string
required
The source wallet currency code.
​
to_currency
string
required
The target wallet currency code.
​
amount
number
required
Amount in the source currency to convert.
​
transaction_purpose
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
  }'

{
  "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.