Six Currency contracts and their failure semantics

Numeric conversion inputs

convert requires from and to from the documented currency enum. amount is a JSON number, defaults to 1, must be finite and greater than zero, and cannot exceed 1,000,000,000. Numeric strings are rejected. The optional date selects a historical reference day.

fromtoamountdate

Date and target validation

All input dates use real YYYY-MM-DD calendar dates from 1999-01-04 through today in UTC. historical requires date. timeseries and fluctuation require ordered start/end dates; count both endpoints when applying the 31-day limit. symbols is a comma-separated string of 1–10 unique supported uppercase codes with no spaces; its default is USD,GBP,JPY.

startendsymbols

Read the published date, not just the request

historical returns base, date and rates. requested_date can record a weekend or holiday rollback. latest may also return amount and a Unix timestamp. convert returns from, to, amount, rate, result and date. Optional fields are returned only when present.

requested_datetimestampresult

Distinguish a range from its observations

timeseries maps dates to currency-rate maps. Range labels may arrive as start/end or start_date/end_date; either pair is accepted. A non-null stop_reason marks a series that ended early, not a complete one. fluctuation carries endpoint rates, signed change and change_pct; inspect actual endpoint dates before comparison. currencies returns date, base EUR, count and a code-to-name map.

ratesstop_reasonstart_dateend_datechange_pctcount

Errors and attribution

A reply with ok:true carries data that has passed this operation's output schema. A result that fails that check is reported as RESULT_INVALID (502): its outcome is unknown, so the price is held, then released, and never charged. An operation that reports it did not succeed returns REQUEST_NOT_FULFILLED (502) and is not charged. SERVICE_UNAVAILABLE describes a condition on the service side, not your wallet balance. OPERATION_TIMEOUT, RESULT_INVALID and other uncertain outcomes must not trigger an automatic paid retry with a new Idempotency-Key. When attribution accompanies a result, it is returned in meta.sourceAttribution.

okdatasourceAttribution

Latest reference rates

POST /api/v1/currency/latest

Use the documented flat JSON object. Keep the fields at the top level; do not wrap them in body.

{
  "base": "EUR",
  "symbols": "USD,GBP,JPY"
}

{
  "base": "EUR",
  "date": "2024-01-05",
  "rates": {
    "USD": 1.1,
    "GBP": 0.85,
    "JPY": 160
  },
  "amount": 1
}

Convert an amount

POST /api/v1/currency/convert

Use the documented flat JSON object. Keep the fields at the top level; do not wrap them in body.

{
  "from": "USD",
  "to": "EUR",
  "amount": 100
}

{
  "from": "USD",
  "to": "EUR",
  "amount": 100,
  "rate": 0.9,
  "result": 90,
  "date": "2024-01-05"
}

Historical reference day

POST /api/v1/currency/historical

Use the documented flat JSON object. Keep the fields at the top level; do not wrap them in body.

{
  "date": "2024-01-06",
  "base": "EUR",
  "symbols": "USD,GBP"
}

{
  "base": "EUR",
  "date": "2024-01-05",
  "requested_date": "2024-01-06",
  "rates": {
    "USD": 1.1,
    "GBP": 0.85
  }
}

Short time series

POST /api/v1/currency/timeseries

Use the documented flat JSON object. Keep the fields at the top level; do not wrap them in body.

{
  "start": "2024-01-02",
  "end": "2024-01-05",
  "base": "EUR",
  "symbols": "USD"
}

{
  "base": "EUR",
  "start": "2024-01-02",
  "end": "2024-01-05",
  "rates": {
    "2024-01-02": {
      "USD": 1.1
    },
    "2024-01-03": {
      "USD": 1.11
    },
    "2024-01-04": {
      "USD": 1.09
    },
    "2024-01-05": {
      "USD": 1.1
    }
  }
}

Endpoint change

POST /api/v1/currency/fluctuation

Use the documented flat JSON object. Keep the fields at the top level; do not wrap them in body.

{
  "start": "2024-01-02",
  "end": "2024-01-05",
  "base": "EUR",
  "symbols": "USD"
}

{
  "base": "EUR",
  "start": "2024-01-02",
  "end": "2024-01-05",
  "start_date": "2024-01-02",
  "end_date": "2024-01-05",
  "rates": {
    "USD": {
      "start_rate": 1.1,
      "end_rate": 1.11,
      "change": 0.01,
      "change_pct": 0.9090909091
    }
  }
}

Current currency names

POST /api/v1/currency/currencies

Use the documented flat JSON object. Keep the fields at the top level; do not wrap them in body.

{}

{
  "date": "2024-01-05",
  "base": "EUR",
  "count": 3,
  "currencies": {
    "USD": "US dollar",
    "GBP": "Pound sterling",
    "JPY": "Japanese yen"
  }
}