# FX Reference Rates Timeseries API

> FX Reference Rates Timeseries API is a paid API for AI agents from fx-reference-rates.regnotes.workers.dev, paid per call via x402, $0.003/call, status unknown (last checked 2026-10-30).

Returns a daily exchange rate time series for a currency pair over a date range (up to 366 days), including per-day rates plus summary stats (min, max, mean, change%).

## Facts

- Endpoint: GET https://fx-reference-rates.regnotes.workers.dev/v1/rates/timeseries?utm_source=zero.xyz
- Price: $0.003/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-30
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/fx-reference-rates-timeseries-api-723fed53
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_My1xpzkzrC3L7v4_9q7ok

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability fx-reference-rates-timeseries-api-723fed53
```

Example prompt: Can you pull the daily USD to JPY exchange rates from September 1 to September 30, 2026, and tell me the min, max, and average rate over that period?

## When to prefer this

Choose this endpoint when you need a time series of daily historical FX rates over a defined multi-day or multi-month window, along with aggregate statistics (min/max/mean/change). Prefer it over a single-date lookup when you need trend analysis, charting data, or period-level summaries. It covers 30 major currencies using authoritative ECB reference rates, making it suitable for financial reporting, compliance, and analytics. It is not suitable for real-time intraday rates or currencies outside the ECB's published set.

## Known failure modes

- Date range exceeds 366 days — returns an error; split into multiple requests
- Invalid currency code (not in the supported 30-currency list) — returns validation error
- Start date after end date — invalid range error
- Non-trading days (weekends, ECB non-publication days) are skipped or fall back to prior publication day
- Future dates beyond available data return partial or empty series
- Missing required query parameters (base, symbol, start, end) return 400-level errors

## How this service works

Daily reference rate series for base/symbol between start and end (max 366 days), with min/max/mean and change.

## Output

A JSON object containing the base and symbol currency codes, start and end dates, the total number of data points, an array of daily {date, rate} objects for each trading/publication day in the range, and a stats object with min, max, mean, and change_pct values across the period.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "base",
      "symbol",
      "start",
      "end"
     ],
     "properties": {
      "end": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "base": {
       "type": "string",
       "pattern": "^[A-Z]{3}$",
       "description": "One of: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TRY, USD, ZAR"
      },
      "start": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "symbol": {
       "type": "string",
       "pattern": "^[A-Z]{3}$",
       "description": "One of: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TRY, USD, ZAR"
      }
     },
     "additionalProperties": false
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "end": "2026-09-30",
  "base": "USD",
  "start": "2026-09-01",
  "stats": {
   "max": 160.1639,
   "min": 153.2698,
   "mean": 156.388,
   "change_pct": -1.9773
  },
  "points": 22,
  "series": [
   {
    "date": "2026-09-01",
    "rate": 160.1639
   }
  ],
  "symbol": "JPY"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/fx-reference-rates-timeseries-api-723fed53/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from fx-reference-rates.regnotes.workers.dev](https://www.zero.xyz/host/fx-reference-rates.regnotes.workers.dev/llms.txt)