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

Client API Endpoint: GET /api/v1/client/exchange-rates

Public Endpoint: GET /api/v1/exchange-rates

Use the client endpoint for signed business integrations. The public endpoint is useful for unauthenticated product surfaces that only need rate discovery.

Authentication

This endpoint requires HMAC authentication (Business API Key). Include your API key and signature in the request headers:

x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>

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 NGNcurl -X GET "https://api.sznd.app/api/v1/client/exchange-rates?quote_type=EXCHANGE&source_currency=USD&target_currency=NGN&amount=100.00" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"
# Get exchange rate with target amount (reverse calculation)curl -X GET "https://api.sznd.app/api/v1/client/exchange-rates?quote_type=EXCHANGE&source_currency=USD&target_currency=NGN&amount=150000.00&amount_side=TARGET" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"
# Get exchange rate for withdrawalcurl -X GET "https://api.sznd.app/api/v1/client/exchange-rates?quote_type=WITHDRAWAL&source_currency=USD&target_currency=NGN&amount=500.00" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"
# Get exchange rate for deposit (CAD to CAD)curl -X GET "https://api.sznd.app/api/v1/client/exchange-rates?quote_type=DEPOSIT&source_currency=CAD&target_currency=CAD&amount=100.00" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"
# Get exchange rate for crypto deposit (USDC to NGN)curl -X GET "https://api.sznd.app/api/v1/client/exchange-rates?quote_type=DEPOSIT&source_currency=USDC&target_currency=NGN&amount=100.00" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here"

Example: HTTP Request

GET /api/v1/client/exchange-rates?quote_type=EXCHANGE&source_currency=USD&target_currency=NGN&amount=100.00 HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-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