Appearance

Swap ​

Swap allows you to move funds between your own Maraboo wallets instantly, with no fees. This is useful for managing multi-currency operations, allocating funds, and organizing your finances.

Overview ​

Swap functionality enables you to:

  • Move funds between different currency wallets
  • Exchange currencies at competitive rates

View swap API reference →

Step 1: Check Wallet Balances ​

Verify you have sufficient funds in the source wallet:

javascript
async function checkWalletBalance(walletId, requiredAmount) {
  const response = await fetch(
    `https://sandbox.mara.boo/api-access/wallets/${walletId}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
        'X-Origin': 'third-party-api',
        'X-Timestamp': new Date().toISOString(),
        'Content-Type': 'application/json'
      }
    }
  );

  const wallet = await response.json();
  const balance = wallet.data.balance;

  if (balance < requiredAmount) {
    throw new Error(`Insufficient balance. Required: ${requiredAmount}, Available: ${balance}`);
  }

  return wallet.data;
}

// Check before transfer
await checkWalletBalance('wallet-xof-456', 500000);

View wallets endpoint →

Step 2: Get Exchange Rate Quote ​

For currency swaps, get a quote first:

javascript
const quoteResponse = await fetch('https://sandbox.mara.boo/api-access/calculators/swap', {
  method: 'POST',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api',
    'X-Timestamp': new Date().toISOString(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 500000,
    from_currency: 'xof',
    to_currency: 'cad',
    country: 'bf'
  })
});

const quote = await quoteResponse.json();
console.log('Exchange rate:', quote.data.exchange_rate);
console.log('You will receive:', quote.data.converted_amount, 'CAD');
console.log('Quote ID:', quote.data.quote_id);

View calculator endpoint →

Step 3: Execute Swap ​

Create the swap transaction:

javascript
const transferResponse = await fetch('https://sandbox.mara.boo/api-access/transactions/client/sessions/swap', {
  method: 'POST',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api',
    'X-Timestamp': new Date().toISOString(),
    'X-Idempotency-Key': `swap-${Date.now()}-${quote.data.quote_id}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    description: 'Internal currency swap',
    swap_quote_id: quote.data.quote_id,
    source_wallet: 'wallet-xof-456',
    destination_wallet: 'wallet-cad-789',
    transaction: {
      amount: 500000,
      from_currency: 'xof',
      to_currency: 'cad',
      country: 'bf',
      priority: 'standard'
    },
    session_type: 'swap_transaction',
    metadata: {
      purpose: 'internal_transfer',
      category: 'currency_management'
    },
    swap_type: 'SWAP'
  })
});

const transfer = await transferResponse.json();
console.log('Transfer ID:', transfer.data.transaction_id);
console.log('Session ID:', transfer.data.session_id);
console.log('Status:', transfer.data.status);

View full API reference →

Step 4: Verify Transfer Completion ​

Track the transfer status:

javascript
const sessionId = transfer.data.session_id;

const statusResponse = await fetch(
  `https://sandbox.mara.boo/api-access/transactions/client/sessions/${sessionId}`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
      'X-Origin': 'third-party-api',
      'X-Timestamp': new Date().toISOString(),
      'Content-Type': 'application/json'
    }
  }
);

const status = await statusResponse.json();
console.log('Status:', status.data.status);
console.log('Amount transferred:', status.data.amount);
console.log('Converted amount:', status.data.converted_amount);
console.log('Exchange rate:', status.data.exchange_rate);

View endpoint →

Best Practices ​

Implement Idempotency ​

Prevent duplicate transfers:

javascript
headers: {
  'X-Idempotency-Key': `transfer-${Date.now()}-${sourceWallet}-${destinationWallet}`
}

Learn about idempotency →

Webhook Notifications ​

Receive real-time notifications for internal transfers:

json
{
  "event": "transaction.completed",
  "data": {
    "session_id": "session-123",
    "transaction_id": "txn-456",
    "transaction_type": "swap_transaction",
    "swap_type": "SWAP",
    "status": "completed",
    "source_wallet_id": "wallet-xof-456",
    "destination_wallet_id": "wallet-cad-789",
    "amount": 500000,
    "from_currency": "xof",
    "to_currency": "cad",
    "exchange_rate": 0.0022,
    "converted_amount": 1100,
    "timestamp": "2025-10-12T14:30:00.000Z"
  }
}

Learn about webhooks →

Next Steps ​