General
Get Token Rate
GET
Get the rate for a token/amount/fiat combination. This endpoint returns the rate from the first available provider in the priority queue that can handle the specified token, amount, and currency combination.
Parameters
token
(path, required): The token symbol (e.g., “USDC”, “USDT”)amount
(path, required): The token amount to get the rate forfiat
(path, required): The fiat currency code (e.g., “NGN”, “KES”)network
(query, optional): The blockchain network identifier (e.g., “arbitrum-one”, “polygon”, “base”). If not provided, returns the first matching token across all networks.provider_id
(query, optional): Specific provider ID to get their rate instead of the priority queue selection
Example
Response
Success Response (200 OK)
Error Responses
400 Bad Request
- Token not supported:
"Token USDC is not supported"
- Token not supported on network:
"Token USDC is not supported on network arbitrum-one"
- Fiat currency not supported:
"Fiat currency XYZ is not supported"
- Invalid amount:
"Invalid amount"
- Currency conversion not supported:
"USDC can only be converted to USD"
- Provider not found:
"Provider not found"
- Provider configuration error:
"Provider does not support this token/currency combination"
- Amount out of range:
"Amount must be between 10 and 1000 for this provider"
503 Service Unavailable
- No provider available:
"No provider available for USDC to NGN conversion with amount 100"
Rate Resolution Logic
The API uses the following logic to determine the rate:
- Direct Currency Match: If the token’s base currency matches the fiat currency, returns 1:1 rate
- Provider-Specific Rate: If
provider_id
is provided, returns that provider’s rate (if they support the combination) - Priority Queue Selection: Searches through provider buckets in priority order and returns the rate from the first provider that can handle the request
- Service Unavailable: If no provider can handle the request, returns 503 error
Priority Queue System
The current implementation uses a priority queue to determine provider selection:
- Provider Order: Providers are ranked by priority (highest priority first)
- First Available Wins: The first provider that meets all criteria gets selected
- No Rate Comparison: The system doesn’t compare rates to find the “best” one - it uses the first suitable provider
- Queue Randomization: Provider order is randomized periodically to ensure fair distribution
The priority queue system is the current implementation and may change in future versions. Provider selection is based on priority order, not rate comparison.
Important Notes
- Priority-Based Selection: The API returns the rate from the first available provider in the priority queue, not necessarily the lowest or highest rate
- No Market Rate Fallback: The API does not fall back to market rates when no providers are available
- Service Availability: A 503 response indicates that no providers can currently handle your request
- Amount Validation: Providers have minimum and maximum order amounts that must be respected
- Network Filtering: Network filters are applied to both token selection and provider matching
Troubleshooting
Common Issues
- 503 Service Unavailable: Try adjusting the amount or currency combination
- 400 Bad Request - Amount out of range: Check provider limits for your token/currency pair
- 400 Bad Request - Provider not found: Verify the provider ID is correct and active
Best Practices
- Always handle 503 responses gracefully in your application
- Consider implementing retry logic with different amounts
- Cache successful rates to reduce API calls
- Monitor provider availability for your specific use cases
- Understand that rates are based on priority queue order, not rate comparison
Authorizations
Query Parameters
Network identifier for the blockchain (optional, filters tokens by network)
Available options:
base
, bnb-smart-chain
, lisk
, tron
, celo
, arbitrum-one
, polygon
, asset-chain
Provider ID to get the rate for a specific provider. If not provided, returns rate from the public queue.
Response
200
Token rate