ForexAPI Documentation

Self-hosted currency exchange rate API. 30 currencies, official daily rates from the European Central Bank, historical data back to 1999, and instant conversion — deployed on your own VPS.

Base URL: https://forexapi.aiclipcutter.tech

Quick Start (Local Dev)

Run the full stack locally in under 5 minutes.

bash
# 1. Clone the project
git clone https://github.com/yourusername/forex-api.git
cd forex-api

# 2. Install dependencies
npm install

# 3. Start Redis via Docker
docker run -d -p 6379:6379 --name forex-redis redis:7-alpine

# 4. Copy .env
cp .env.example .env

# 5. Start the API (dev mode with auto-reload)
npm run dev
# → Server running on http://localhost:3000

# 6. Create your first API key
npm run create-key admin@example.com business

# 7. Test it
curl "http://localhost:3000/v1/latest?base=USD&symbols=EUR,GBP" \
  -H "X-Api-Key: fxk_your_key_here"

Authentication

Pass your API key via header (recommended) or query parameter. Both are supported for Fixer.io compatibility.

Header (recommended)
curl "https://forexapi.aiclipcutter.tech/v1/latest" \
  -H "X-Api-Key: fxk_your_key_here"

Query param (Fixer.io-compatible)
curl "https://forexapi.aiclipcutter.tech/v1/latest?access_key=fxk_your_key_here"

On RapidAPI, the platform injects X-RapidAPI-Key automatically — you don't need to manage keys for marketplace users.

GET /v1/latest

Returns the latest exchange rates. The ECB publishes once per business day around 16:00 CET; the cache is refreshed hourly so a new publication is picked up within the hour. Available on all plans.

Parameters

Request
GET /v1/latest?base=USD&symbols=EUR,GBP,JPY,INR

Response
{
  "success": true,
  "timestamp": 1725356400000,
  "base": "USD",
  "date": "2026-09-03",
  "rates": {
    "EUR": 0.9212,
    "GBP": 0.7874,
    "JPY": 147.32,
    "INR": 83.91
  }
}

GET /v1/convert

Convert a specific amount between two currencies in a single call.

Parameters

Request
GET /v1/convert?from=USD&to=EUR&amount=100

Response
{
  "success": true,
  "query": { "from": "USD", "to": "EUR", "amount": 100 },
  "info": { "rate": 0.9212, "timestamp": 1725356400000 },
  "date": "2026-09-03",
  "result": 92.12
}

GET /v1/historical/:date

Historical rates for any date back to 1999-01-04. Requires Starter plan or higher.

Request
GET /v1/historical/2024-01-15?base=USD&symbols=EUR,GBP

Response
{
  "success": true,
  "base": "USD",
  "date": "2024-01-15",
  "historical": true,
  "rates": { "EUR": 0.9185, "GBP": 0.7821 }
}

GET /v1/timeseries

Rates for every available day within a date range. Max 365 days per request. Requires Pro plan.

Request
GET /v1/timeseries?start=2024-01-01&end=2024-01-07&base=USD&symbols=EUR

Response
{
  "success": true,
  "base": "USD",
  "start_date": "2024-01-01",
  "end_date": "2024-01-07",
  "rates": {
    "2024-01-02": { "EUR": 0.9201 },
    "2024-01-03": { "EUR": 0.9195 },
    "2024-01-04": { "EUR": 0.9188 }
  }
}

GET /v1/fluctuation

Percentage change and absolute delta between two dates. Requires Pro plan.

Request
GET /v1/fluctuation?start=2024-01-01&end=2024-03-01&base=USD&symbols=EUR,GBP

Response
{
  "success": true,
  "base": "USD",
  "start_date": "2024-01-01",
  "end_date": "2024-03-01",
  "rates": {
    "EUR": { "start_rate": 0.9201, "end_rate": 0.9265, "change": 0.0064, "change_pct": 0.6956 },
    "GBP": { "start_rate": 0.7850, "end_rate": 0.7921, "change": 0.0071, "change_pct": 0.9045 }
  }
}

GET /v1/currencies

Returns all supported currency codes with their full names. No authentication required.

Request
GET /v1/currencies

Response
{
  "success": true,
  "currencies": {
    "USD": "United States Dollar",
    "EUR": "Euro",
    "GBP": "British Pound Sterling",
    "...
  }
}

Step-by-Step VPS Deployment

A complete walkthrough from a fresh Ubuntu VPS to a live, HTTPS-secured API.

ssh root@YOUR_VPS_IP
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

cd forex-api
git init
git add .
git commit -m "feat: initial forex api"
git remote add origin https://github.com/YOURUSER/forex-api.git
git push -u origin main

NODE_ENV=production
PORT=3000
APP_URL=https://forexapi.aiclipcutter.tech
REDIS_URL=redis://redis:6379
DB_PATH=/data/forex.db
ADMIN_API_KEY=fxk_generate_a_random_value
ADMIN_EMAIL=admin@yourdomain.com
DEMO_API_KEY=fxk_demo_public
AUTO_SEED=true

node -e "console.log('fxk_'+require('crypto').randomBytes(16).toString('hex'))"

[db] Admin API key bootstrapped from ADMIN_API_KEY
[cron] Initial rate load complete
[seed] Stored 6900+ days of historical rates

curl https://forexapi.aiclipcutter.tech/health

docker exec forex-api node scripts/create-key.js customer@example.com pro

# Health check
curl https://forexapi.aiclipcutter.tech/health

# Live rates (use your key)
curl "https://forexapi.aiclipcutter.tech/v1/latest?base=USD&symbols=EUR,GBP" \
  -H "X-Api-Key: fxk_your_key"

Coolify Auto-Deploy on Git Push

After initial setup, Coolify can deploy automatically every time you push to main.

Resource → General → enable Auto-deploy on push. Coolify registers a webhook on your GitHub repo. Every push to main triggers a new build and zero-downtime restart.

Seed Historical Data

Historical rates are stored in SQLite, not fetched per request. /v1/historical, /v1/timeseries and /v1/fluctuation all read from that table.

Check how many days are loaded:

curl https://forexapi.aiclipcutter.tech/health

Response
{
  "status": "ok",
  "redis": "connected",
  "historical_days": 6934,
  ...
}

Force a re-seed (safe to re-run — rows are replaced, not duplicated):

docker exec forex-api node scripts/seed-history.js

Locally:

npm run seed

To skip the automatic seed, set AUTO_SEED=false in your environment variables.

Create API Keys

Keys look like fxk_<32 hex chars> and carry a tier that decides both the monthly quota and which endpoints are reachable.

On the server

docker exec forex-api node scripts/create-key.js customer@example.com pro

Output
API Key Created:
-----------------------------------------
Key:   fxk_9f2c41ab7e6d4058bc13a7e250f9d834
Email: customer@example.com
Tier:  pro
-----------------------------------------

Locally

npm run create-key -- customer@example.com pro

Tiers

List and revoke

# List every key
docker exec forex-api node scripts/create-key.js --list

# Revoke one (sets active = 0; the key stops working immediately)
docker exec forex-api node scripts/create-key.js --revoke fxk_9f2c41ab7e6d4058bc13a7e250f9d834

RapidAPI Marketplace Listing Guide

RapidAPI drives significant organic API discovery traffic. Listing here is how you get your first paying users without marketing spend.

Real-time & historical currency exchange rates. 30 ECB currencies.
Up to 5× cheaper than Fixer.io. Free tier included.

https://forexapi.aiclipcutter.tech/openapi.json

Proxy Secret Setup

The proxy secret prevents people from calling your VPS directly, bypassing RapidAPI and their billing.

RAPIDAPI_PROXY_SECRET=paste_the_value_from_rapidapi_here

// Validate RapidAPI proxy secret — blocks direct callers
const proxySecret = req.headers['x-rapidapi-proxy-secret'];
if (process.env.RAPIDAPI_PROXY_SECRET && proxySecret !== process.env.RAPIDAPI_PROXY_SECRET) {
  // Not from RapidAPI — check if they have a direct key instead
  const directKey = req.headers['x-api-key'] || req.query.access_key;
  if (!directKey) {
    return res.status(403).json({
      success: false,
      error: { code: 'DIRECT_ACCESS_DENIED', message: 'Access this API via RapidAPI or a valid API key.' }
    });
  }
}

Pricing Plans on RapidAPI

In RapidAPI → Your API → Pricing → Add Plan for each tier:

Tier Mapping

For RapidAPI users, trust RapidAPI's plan enforcement. For direct customers, your middleware handles it.

Error Codes

Rate Limit Headers

Every authenticated response includes:

Fixer.io Compatibility

ForexAPI is designed as a drop-in Fixer.io alternative. Change the base URL and you're done for most endpoints: