Exchange Rates API

The Exchange Rates API provides real-time exchange rates between currencies, including fee calculations, transaction limits, and payment rail options. This endpoint is essential for displaying conversion rates to users before they create quotes or transactions.

Get Current Exchange Rate

Retrieve the current exchange rate between two currencies with comprehensive fee calculations, limit information, and payment rail options. This endpoint supports both FIAT and CRYPTO transactions.

Endpoint

GET /api/v1/exchange-rates

Authentication

This endpoint does not require authentication for basic rate queries, but authentication is recommended for accurate user-specific rates and limits.

Query Parameters

Transaction Types

• EXCHANGE - Currency conversion between different currencies
• WITHDRAWAL - Withdraw funds to external destination
• DEPOSIT - Deposit funds from external source
• TRANSFER - Internal transfer between accounts
• SWAP - Currency swap within same account
• DIRECT_EXCHANGE - Direct exchange with external beneficiary

Success Response (200 OK)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "source_currency": "USD",
  "source_amount": "100.00",
  "target_currency": "NGN",
  "target_amount": "149250.00",
  "rate": "1492.50",
  "display_rate": "1492.50",
  "valid_until": "2025-06-01T12:00:00Z",
  "rail": {
    "fee_config_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "WIRE",
    "description": "Wire Transfer",
    "display_name": "Wire Transfer",
    "speed": "Same day",
    "total_payable": "105.00",
    "fees": {
      "processing_fee": "3.00",
      "deposit_fee": "2.00",
      "payout_fee": "0.00",
      "total_fees": "5.00",
      "fee_currency": "USD"
    }
  },
  "min_deposit_amount": "10.00",
  "max_deposit_amount": "10000.00",
  "min_withdrawal_amount": "50.00",
  "max_withdrawal_amount": "5000.00"
}

Response Fields

Error Responses

Example: cURL

# Get exchange rate for USD to NGN
curl -X GET "/api/v1/exchange-rates?quote_type=EXCHANGE&source_currency=USD&target_currency=NGN&amount=100.00" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 
# Get exchange rate with target amount (reverse calculation)
curl -X GET "/api/v1/exchange-rates?quote_type=EXCHANGE&source_currency=USD&target_currency=NGN&amount=150000.00&amount_side=TARGET"
 
# Get exchange rate for withdrawal
curl -X GET "/api/v1/exchange-rates?quote_type=WITHDRAWAL&source_currency=USD&target_currency=NGN&amount=500.00"
 
# Get exchange rate for crypto deposit (USDC to NGN)
curl -X GET "/api/v1/exchange-rates?quote_type=DEPOSIT&source_currency=USDC&target_currency=NGN&amount=100.00"

Example: HTTP Request

GET /api/v1/exchange-rates?quote_type=EXCHANGE&source_currency=USD&target_currency=NGN&amount=100.00 HTTP/1.1
Host: api.sznd.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Use Cases

1. Rate Display - Show users current exchange rates before creating quotes
2. Fee Calculation - Display total fees and payable amounts
3. Limit Validation - Check if transaction amounts are within allowed limits
4. Rail Selection - Compare different payment rails and their fees
5. Reverse Calculation - Calculate required source amount for a target amount

Key Features

• FIAT and CRYPTO Support - Handles both traditional currencies and stablecoins (USDC, USDT)
• USD Bridging - Automatically bridges crypto transactions through USD for accurate conversions
• Smart Currency Mapping - Automatically detects stablecoins and applies appropriate conversions
• Fee Calculations - Provides detailed fee breakdowns for all payment rails
• Transaction Limits - Includes minimum and maximum amounts for deposits and withdrawals
• Rate Validity - Provides expiration timestamps for rate locking

Best Practices

1. Cache Rates - Exchange rates change frequently, but you can cache them for short periods (e.g., 30 seconds)
2. Check Validity - Always check the valid_until timestamp before using a rate
3. Validate Limits - Verify transaction amounts against min_* and max_* limits before proceeding
4. Display Fees Clearly - Show users the total payable amount including all fees
5. Handle Errors - Provide fallback options if rate lookup fails

Transaction Limits

Transaction limits are included in the exchange rate response. These limits help ensure transactions comply with regulatory requirements and business rules.

Limit Fields

The exchange rate response includes the following limit fields:

Next Steps

• Create Quote - Use the exchange rate to create a quote for currency conversion
• Currencies API - Get list of supported currencies
• Transactions API - Track completed transactions