# FX Reference Rates API

> Daily ECB euro foreign exchange reference rates for 30 currencies (incl. EUR), any base via cross rates, conversion, historical dates (2024-09-24 onward) and time series. Updated daily. Source: ECB (European Central Bank euro foreign exchange reference rates). Reference rates are published around 16:00 CET on TARGET business days for information purposes only; not for transaction pricing. Cross rates are derived via EUR. Also: AI infrastructure price reference data (cloud GPU instance list prices on AWS and Azure, LLM API token prices), refreshed daily. Also: country macroeconomic indicators (GDP, growth, inflation, unemployment, debt, current account, reserves, FDI, population and more) for ~217 economies from the World Bank World Development Indicators (CC BY 4.0). Payment is USDC on Base (eip155:8453) via x402 v2, exact scheme. No account, no API key, no signup.

## Paid endpoints (HTTP GET, answer 402 until paid)

- [Latest reference rates in any base](https://fx-reference-rates.regnotes.workers.dev/v1/rates/latest?base=USD&symbols=JPY%2CCNY%2CEUR): $0.001. Today's exchange rates (forex reference rates, most recent ECB publication) for ~30 currencies in any base currency, e.g. USD to JPY, CNY, EUR, GBP, HKD, SGD, KRW, INR. Filter with symbols. Returns as_of date and source attribution. Params: base (optional), symbols (optional).
- [Convert an amount between currencies](https://fx-reference-rates.regnotes.workers.dev/v1/convert?from=USD&to=JPY&amount=100): $0.001. Currency converter: convert an amount between any two of ~30 currencies (e.g. 100 USD to JPY) at the latest ECB reference rate or as of a past date. Returns rate, result and as_of date. Params: from, to, amount, date (optional).
- [Reference rates on a date](https://fx-reference-rates.regnotes.workers.dev/v1/rates/historical?date=2026-06-30&base=EUR&symbols=USD%2CGBP): $0.002. ECB reference rates on a given date in any base; non-publication days fall back to the previous publication day (as_of). Params: date, base (optional), symbols (optional).
- [Daily time series for a currency pair](https://fx-reference-rates.regnotes.workers.dev/v1/rates/timeseries?base=USD&symbol=JPY&start=2026-09-01&end=2026-09-30): $0.003. Daily reference rate series for base/symbol between start and end (max 366 days), with min/max/mean and change. Params: base, symbol, start, end.
- [Full history as one CSV file](https://fx-reference-rates.regnotes.workers.dev/v1/dataset/csv?base=EUR): $0.02. Bulk download: every publication day in coverage as CSV (date + one column per currency) in the requested base (default EUR). One payment, whole dataset. Params: base (optional).
- [Cloud GPU instance prices, cheapest first](https://fx-reference-rates.regnotes.workers.dev/v1/ai/gpu-prices?gpu=H100&pricing=on_demand&limit=5): $0.005. Cloud GPU price comparison: hourly list prices of GPU / AI accelerator instances (H100, H200, A100, L40S, L4, A10G, T4, B200, MI300X, Trainium, Inferentia ...) on AWS and Azure in US, EU and Asia regions, on-demand and Azure Spot, ranked by USD per GPU-hour. Filter by gpu model, cloud, region, pricing. Official provider price APIs, refreshed daily. Params: gpu (optional), cloud (optional), region (optional), pricing (optional), limit (optional).
- [LLM API token prices by model](https://fx-reference-rates.regnotes.workers.dev/v1/ai/llm-prices?model=claude-sonnet-4-5): $0.005. LLM API pricing lookup: USD per 1M input, output and cached-input tokens plus context window for ~3,300 models (OpenAI GPT, Anthropic Claude, Google Gemini, DeepSeek, Llama, Mistral, Qwen, xAI ...) across providers (direct, Azure, Bedrock, Vertex, Together, Fireworks ...). Filter by model and provider; sorted by input price. Params: model, provider (optional), limit (optional).
- [Full AI price dataset (GPU + LLM) as JSON](https://fx-reference-rates.regnotes.workers.dev/v1/ai/dataset): $0.10. Bulk download: every cloud GPU instance price row (AWS + Azure, 10 regions, on-demand and spot, with GPU model/count, $/GPU-hour) and every LLM API token price (~3,300 models) in one JSON with per-source retrieval timestamps. One payment, whole dataset, refreshed daily. Params: none.
- [Country macro snapshot: all indicators, latest + history](https://fx-reference-rates.regnotes.workers.dev/v1/macro/country?country=JPN&years=5): $0.02. Country economic profile: latest value and year plus annual history (2005 onward) for 21 World Bank World Development Indicators: GDP (USD), real GDP growth, GDP per capita, GNI per capita PPP, CPI inflation, unemployment, population, exports/imports % GDP, current account % GDP, central government debt % GDP, tax revenue % GDP, real and lending interest rates, FDI inflows % GDP, total reserves, official exchange rate, remittances % GDP, Gini, life expectancy, internet users. Country by ISO3/ISO2 code or name. CC BY 4.0. Params: country, years (optional).
- [One indicator across countries and years](https://fx-reference-rates.regnotes.workers.dev/v1/macro/indicator?indicator=inflation_cpi_pct&countries=USA%2CJPN%2CDEU&start=2020): $0.01. Macroeconomic time series: one World Development Indicator (e.g. inflation_cpi_pct, gdp_growth_pct, central_govt_debt_pct_gdp) for up to 20 countries over a year range, annual values. See free /macro/indicators for keys. CC BY 4.0. Params: indicator, countries, start (optional), end (optional).
- [Rank countries by an indicator](https://fx-reference-rates.regnotes.workers.dev/v1/macro/rank?indicator=gdp_growth_pct&region=Europe&limit=10): $0.02. Country ranking: sort all economies by one World Development Indicator for a year (default: each country's latest value), highest first or lowest first, optionally filtered by World Bank region or income group. Aggregates (World, regions) excluded unless requested. CC BY 4.0. Params: indicator, year (optional), region (optional), income (optional), order (optional), limit (optional), aggregates (optional).
- [Full macro indicator dataset as JSON](https://fx-reference-rates.regnotes.workers.dev/v1/macro/dataset): $0.20. Bulk download: all 21 World Development Indicators for ~217 economies and aggregates, annual 2005 onward, with country metadata (region, income group), per-indicator source, licence and World Bank last-updated date, in one JSON. One payment, whole dataset, refreshed daily. CC BY 4.0. Params: none.

## How to pay

1. GET the endpoint and receive HTTP 402. The `PAYMENT-REQUIRED` header (base64 JSON) lists `accepts` (scheme exact, network eip155:8453, asset USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).
2. Sign an EIP-3009 transferWithAuthorization for the amount and retry with the `PAYMENT-SIGNATURE` header. Any x402 v2 client works (for example @x402/fetch, agentcash).
3. The facilitator settles on-chain; you pay no gas.

### Alternative: MPP (Machine Payments Protocol)

The same 402 also carries a `WWW-Authenticate: Payment` challenge (method tempo, intent charge, USDC.e on Tempo (chain 4217), currency 0x20C000000000000000000000b9537d11c60E8b50), payable to the same address. Only pull-mode credentials are accepted (you sign, the server broadcasts) and the request is validated before broadcast, so a 4xx response never charges you. Any mppx client works, for example `npx mppx <url>`. The client pays its own Tempo network fee.

## Free endpoints

- [OpenAPI](https://fx-reference-rates.regnotes.workers.dev/openapi.json)
- [Health](https://fx-reference-rates.regnotes.workers.dev/health)
- [x402 manifest](https://fx-reference-rates.regnotes.workers.dev/.well-known/x402)
- [Currency list](https://fx-reference-rates.regnotes.workers.dev/currencies)
- [AI price coverage](https://fx-reference-rates.regnotes.workers.dev/ai/coverage)
- [Macro indicator list](https://fx-reference-rates.regnotes.workers.dev/macro/indicators)
- [MCP endpoint (POST)](https://fx-reference-rates.regnotes.workers.dev/mcp)

## Guidance

Use /v1/convert for a single amount conversion (optionally at a past date), /v1/rates/latest for a rate table in any base (limit with symbols=USD,JPY), /v1/rates/historical for a specific date (falls back to the previous publication day and reports as_of), /v1/rates/timeseries for one pair over up to 366 days. Free currency list at /currencies. For AI costs use /v1/ai/gpu-prices (cheapest GPU instances by model, cloud, region, on-demand or spot, ranked by $/GPU-hour), /v1/ai/llm-prices (USD per 1M input/output tokens by model), /v1/ai/dataset for everything in one JSON; free coverage at /ai/coverage. For country economics use /v1/macro/country (one country, all indicators, latest value + history), /v1/macro/indicator (one indicator across up to 20 countries and years), /v1/macro/rank (rank countries by an indicator, filter region/income), /v1/macro/dataset for everything; free list of indicator keys and country codes at /macro/indicators.

All timestamps are UTC.