Swap

Exchange one cryptocurrency for another directly within your IvoryPay business wallet — no external transfers required.

Base path: /v1/crypto-swap Authentication: API Key (Authorization: <secret-key>)

---

Endpoints

Method	Path	Description
POST	/v1/crypto-swap/estimate	Preview a swap rate without executing it
POST	/v1/crypto-swap/initiate	Execute a crypto-to-crypto swap

---

POST /v1/crypto-swap/estimate

Returns the estimated output amount, conversion rate, and fee for a proposed swap. No funds are moved during estimation.

Request

Headers

Authorization: <your-secret-api-key>
Content-Type: application/json

Body

{
  "sourceCurrency": "USDT",
  "targetCurrency": "BTC",
  "amountInSourceCurrency": 100
}

Field	Type	Required	Description
sourceCurrency	string	Yes	Token you want to swap from. See supported tokens.
targetCurrency	string	Yes	Token you want to swap to. Must differ from sourceCurrency.
amountInSourceCurrency	number	Yes	Amount in the source token. Must be a positive number.

Response

{
  "status": true,
  "message": "Swap estimation retrieved successfully",
  "data": {
    "sourceCurrency": "USDT",
    "targetCurrency": "BTC",
    "amountInSourceCurrency": 100,
    "amountInTargetCurrency": 0.00143,
    "feeInSourceCurrency": 0.15,
    "conversionRate": 0.0000143
  }
}

Field	Type	Description
sourceCurrency	string	Token being swapped from
targetCurrency	string	Token being swapped to
amountInSourceCurrency	number	Amount you're swapping
amountInTargetCurrency	number	Estimated amount you will receive
feeInSourceCurrency	number	Platform fee deducted from source amount
conversionRate	number	Exchange rate at time of estimation

Error Responses

Status	Message	Cause
400	The source currency must be different from the target currency	Same token for source and target
400	Your <token> wallet is inactive. Please enable.	Wallet is disabled
400	Insufficient balance	Not enough funds for the swap + fee
401	Unauthorized	Missing or invalid API key

---

POST /v1/crypto-swap/initiate

Executes the swap. Debits amountInSourceCurrency + fee from your source wallet and credits the converted amount to your target wallet.

Request

Headers

Authorization: <your-secret-api-key>
Content-Type: application/json

Body

{
  "sourceCurrency": "USDT",
  "targetCurrency": "BTC",
  "amountInSourceCurrency": 100,
  "reference": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
sourceCurrency	string	Yes	Token to swap from.
targetCurrency	string	Yes	Token to swap to. Must differ from sourceCurrency.
amountInSourceCurrency	number	Yes	Amount to swap in the source token.
reference	string	Yes	Your unique identifier for this swap. Used for idempotency.

Response

{
  "status": true,
  "message": "Swap initiated successfully",
  "data": {
    "id": "uuid",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "sourceCurrency": "USDT",
    "targetCurrency": "BTC",
    "amountInSourceCurrency": 100,
    "amountInTargetCurrency": 0.00143,
    "feeInSourceCurrency": 0.15,
    "status": "PENDING",
    "businessId": "uuid",
    "environment": "LIVE",
    "createdAt": "2026-02-19T10:00:00.000Z"
  }
}

Error Responses

Status	Message	Cause
400	The source currency must be different from the target currency	Same token for source and target
400	Duplicate transaction	A swap with the same reference already exists
400	Insufficient balance	Not enough funds for the swap + fee
400	Unable to retrieve swap conversion	Exchange rate service unavailable
401	Unauthorized	Missing or invalid API key

---

Swap Lifecycle

PENDING → SUCCESS
        ↘ FAILED

Status	Description
PENDING	Swap queued for processing
SUCCESS	Source wallet debited, target wallet credited
FAILED	Swap failed — no funds moved

Swaps are processed asynchronously. Use webhooks to get notified when a swap completes.

---

Supported Tokens

Value	Name
USDT	Tether USD
USDC	USD Coin
BTC	Bitcoin
ETH	Ethereum
SOL	Solana

Both sourceCurrency and targetCurrency must be tokens supported by your account. Use GET /v1/crypto-transfer/supported/network-tokens to see your enabled tokens.

---

Fee Structure

The platform fee is calculated dynamically by the conversion service at the time of the request and returned as feeInSourceCurrency in both the estimate and initiate responses. It is deducted from the source currency amount.

totalDeducted = amountInSourceCurrency + feeInSourceCurrency
amountReceived = amountInTargetCurrency  (already net of fees)

Use /v1/crypto-swap/estimate first to preview the exact amounts before executing.

---

Code Examples

Node.js

const axios = require('axios');

const BASE_URL = 'https://api.ivorypay.io/api/v1';
const API_KEY = process.env.IVORYPAY_SECRET_KEY;

// Step 1: Estimate
const estimate = await axios.post(
  `${BASE_URL}/crypto-swap/estimate`,
  {
    sourceCurrency: 'USDT',
    targetCurrency: 'BTC',
    amountInSourceCurrency: 100,
  },
  {
    headers: { Authorization: API_KEY, 'Content-Type': 'application/json' },
  },
);

console.log(
  'You will receive:',
  estimate.data.data.amountInTargetCurrency,
  'BTC',
);

// Step 2: Initiate
const swap = await axios.post(
  `${BASE_URL}/crypto-swap/initiate`,
  {
    sourceCurrency: 'USDT',
    targetCurrency: 'BTC',
    amountInSourceCurrency: 100,
    reference: crypto.randomUUID(),
  },
  {
    headers: { Authorization: API_KEY, 'Content-Type': 'application/json' },
  },
);

console.log('Swap status:', swap.data.data.status);

cURL

BASE_URL="https://api.ivorypay.io/api/v1"
API_KEY="live_sk_xxxxxxxxxxxx"

# Estimate
curl -X POST $BASE_URL/crypto-swap/estimate \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sourceCurrency":"USDT","targetCurrency":"BTC","amountInSourceCurrency":100}'

# Initiate
curl -X POST $BASE_URL/crypto-swap/initiate \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCurrency": "USDT",
    "targetCurrency": "BTC",
    "amountInSourceCurrency": 100,
    "reference": "550e8400-e29b-41d4-a716-446655440000"
  }'

Python

import requests
import uuid

BASE_URL = 'https://api.ivorypay.io/api/v1'
API_KEY = 'live_sk_xxxxxxxxxxxx'
HEADERS = {'Authorization': API_KEY, 'Content-Type': 'application/json'}

# Estimate
estimate = requests.post(f'{BASE_URL}/crypto-swap/estimate', json={
    'sourceCurrency': 'USDT',
    'targetCurrency': 'BTC',
    'amountInSourceCurrency': 100,
}, headers=HEADERS)

print('You will receive:', estimate.json()['data']['amountInTargetCurrency'], 'BTC')

# Initiate
swap = requests.post(f'{BASE_URL}/crypto-swap/initiate', json={
    'sourceCurrency': 'USDT',
    'targetCurrency': 'BTC',
    'amountInSourceCurrency': 100,
    'reference': str(uuid.uuid4()),
}, headers=HEADERS)

print('Swap status:', swap.json()['data']['status'])