Skip to main content

Getting Started

This guide will help you authenticate with the OpenFXRates API, understand rate limits, and make your first API request.

Prerequisites​

Before you begin, you'll need:

  1. An OpenFXRates account - Sign up at openfxrates.com
  2. An API Key - Generated from your account dashboard
  3. A tool for making HTTP requests - cURL, Postman, or your programming language's HTTP library

Getting Your API Key​

Step 1: Create an Account​

Visit openfxrates.com and create a free account.

Step 2: Access Your Dashboard​

Log in to your account and navigate to the API Keys section in your dashboard.

Step 3: Generate an API Key​

Click "Generate New Key" and give it a name (e.g., "My App").

Step 4: Copy Your Key​

Copy the generated API key and store it securely. You'll use this in all API requests.

caution

Never share your API key publicly or commit it to version control. Treat it like a password!

Authentication​

All OpenFXRates API requests require authentication via the X-API-Key header.

Using Your API Key​

Include your API key in the X-API-Key header:

curl -X GET "https://api.openfxrates.com/latest_rates?base=USD" \
  -H "X-API-Key: your-api-key-here"

Replace your-api-key-here with your actual API key.

Authentication Example​

Request:

curl -X GET "https://api.openfxrates.com/currencies" \
  -H "X-API-Key: sk_test_abc123def456"

Response:

{
  "currencies": [
    {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$"
    },
    {
      "code": "EUR",
      "name": "Euro",
      "symbol": "€"
    }
    // ... more currencies
  ]
}

Base URL​

The OpenFXRates API is available at:

Production: https://api.openfxrates.com
Development: http://dev.openfxrates.com:8001

Rate Limits​

OpenFXRates implements rate limiting to ensure fair usage and API stability.

Standard Rate Limits​

PlanRequests/MinuteRequests/Day
Free101,000
Pro10050,000
EnterpriseCustomCustom

Checking Rate Limits​

Rate limit information is included in response headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1640000000
  • X-RateLimit-Limit - Maximum requests allowed per minute
  • X-RateLimit-Remaining - Requests remaining in current window
  • X-RateLimit-Reset - Unix timestamp when limit resets

Handling Rate Limit Errors​

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": "Too many requests",
  "retry_after": 60
}

Wait for the retry_after seconds before making another request.

Your First Request​

Let's make your first API request to get the latest exchange rates.

Step 1: Prepare Your Request​

curl -X GET "https://api.openfxrates.com/latest_rates?base=USD" \
  -H "X-API-Key: your-api-key-here"

Step 2: Execute​

Run the command in your terminal. You should receive a response like:

{
  "base": "USD",
  "date": "2024-12-25",
  "rates": {
    "EUR": 0.92,
    "GBP": 0.79,
    "JPY": 150.25,
    "AUD": 1.55,
    "CAD": 1.36
  }
}

Step 3: Success!​

Congratulations! You've made your first API request to OpenFXRates.

Common Parameters​

Most API endpoints support these parameters:

Base Currency​

The source currency for the exchange rate. Must be a valid ISO 4217 code:

?base=USD

Target Currencies​

The currencies to convert to. Use comma-separated codes:

?targets=EUR,GBP,JPY

Omit this parameter to get rates for all currencies.

Date (Historical Only)​

For historical rates, specify the date in YYYY-MM-DD format:

?date=2024-01-15

Error Handling​

The API returns standard HTTP status codes:

StatusMeaningExample
200SuccessRequest completed successfully
400Bad RequestInvalid parameters
401UnauthorizedMissing or invalid API key
404Not FoundResource doesn't exist
429Too Many RequestsRate limit exceeded
500Server ErrorInternal server error

Error Response Format​

{
  "error": "Invalid base currency",
  "message": "The currency code 'XYZ' is not supported",
  "code": "INVALID_CURRENCY"
}

Testing with Swagger UI​

You can test all endpoints interactively using the Swagger UI:

Development: http://dev.openfxrates.com:8001/api-docs/

In Swagger UI:

  1. Click Authorize (top right)
  2. Enter your API key in the X-API-Key field
  3. Click Authorize, then Close
  4. Expand any endpoint and click Try it out
  5. Enter parameters and click Execute

Environment Setup​

Using Environment Variables​

Instead of hardcoding API keys, use environment variables:

Linux/macOS:

export OPENFXRATES_API_KEY="your-api-key-here"

Windows (PowerShell):

$env:OPENFXRATES_API_KEY="your-api-key-here"

Then reference it in your requests:

curl -X GET "https://api.openfxrates.com/latest_rates?base=USD" \
  -H "X-API-Key: $OPENFXRATES_API_KEY"

SDK Support​

OpenFXRates SDKs are available for popular languages:

  • PHP - Coming soon
  • JavaScript/Node.js - Coming soon
  • Python - Coming soon

Check the Code Examples section for detailed examples in your language.

Next Steps​

Need Help?​