Developer Reference
Integrate in Minutes
Use our simple REST API to perform live currency conversions. All requests require a valid x-api-key in the header.
1. Authentication
To authenticate your requests, you must pass your API Key in the x-api-key header of every request.
# Header Example
x-api-key: YOUR_SECRET_KEY_HERE
x-api-key: YOUR_SECRET_KEY_HERE
2. Convert (GET)
ENDPOINT
/api/v1/convert
Perform real-time currency conversion using our latest hourly exchange rates. Results are cached for 1 hour.
Parameters
| Param | Type | Required | Description |
|---|---|---|---|
| from | string | Yes | Base currency code (e.g. USD) |
| to | string | Yes | Target currency code (e.g. EUR) |
| amount | num | No | Default is 1.00 |
cURL
Node.js
Python
PHP
Go
curl -X GET "https://currency-top.top/api/v1/convert?from=USD&to=EUR&amount=100" \
-H "x-api-key: YOUR_KEY" \
-H "Accept: application/json"
-H "x-api-key: YOUR_KEY" \
-H "Accept: application/json"
3. List Currencies (GET)
ENDPOINT/api/v1/currencies
Retrieve a list of all currently supported currency codes and their full names (e.g., "United States Dollar").
// Sample Response
{
"success": true,
"data": [
{ "code": "USD", "name": "United States Dollar", "symbol": "$" },
{ "code": "EUR", "name": "Euro", "symbol": "€" }
]
}
4. Error Codes Index
Every API error returns a 4xx or 5xx status code along with a descriptive error field in JSON.
| Error Code | HTTP Status | Description |
|---|---|---|
| MISSING_API_KEY | 401 | You did not provide the 'x-api-key' header. |
| INVALID_API_KEY | 403 | The key provided is revoked or does not exist. |
| RATE_LIMIT_EXCEEDED | 429 | You have reached your plan limit for this month. |
| UNSUPPORTED_CURRENCY | 400 | One of the requested currency codes is invalid. |