allratestoday-com Open Endpoints API

openapi: 3.2.0
info:
  title: AllRatesToday Exchange Rate & Central Bank Rates Open…
  description: 'Live mid-market exchange rates for 160+ currencies plus official rates from 122 central banks and 4 tax authorities (ECB, the Fed, Bank of Canada, CBSL, Banxico, HMRC, US Treasury and more).


    ## Data

    - **Market rates** (`/api/rate`, `/api/v1/rates`, `/api/historical-rates`): live mid-market rates, refreshed roughly every 60 seconds.

    - **Central-bank rates** (`/api/v1/central-bank/*`, `/api/open/central-bank/*`): the official tables exactly as published by each institution, one table per publication date. History reaches back to 2000 and earlier for major sources (ECB from 1999, Bank of Canada from 1950s-era series where published).

    - **Daily Reference Rate** (`/api/open/reference-rate`, `/api/v1/reference-rate/*`): one immutable mid-market USD table per business day, fixed at 16:00 London (median of a five-minute sampling window). For index calculation, research and reporting; not a registered benchmark. Methodology: https://allratestoday.com/reference-rate/


    ## Authentication

    Most endpoints require an API key sent as `Authorization: Bearer art_live_...`. Get a free key at https://allratestoday.com/register, or self-issue a 100-call trial key with no account via `POST /api/agent/keys` (built for AI agents). Logged-in dashboard users can also authenticate with their session cookie.


    Keyless endpoints: `/api/v1/symbols` and `/api/open/central-bank/{bank}` (attribution required), plus JSON reads of `/api/public/central-bank/{bank}`.


    ## Output formats

    Endpoints that return tabular data accept `?format=json|csv|xml|xlsx` (CSV is UTF-8 with BOM; XLSX is a real Excel workbook; default json).


    ## Plans

    Free plan: latest central-bank tables included. Historical central-bank dates and time series require a paid plan. See https://allratestoday.com/pricing.'
  version: 2.2.0
  contact:
    name: AllRatesToday Support
    url: https://allratestoday.com
    email: support@allratestoday.com
servers:
- url: https://allratestoday.com
  description: Production
tags:
- name: Open Endpoints
  description: Keyless endpoints — no API key needed
paths:
  /api/v1/symbols:
    get:
      tags:
      - Open Endpoints
      operationId: getSymbols
      summary: List supported currencies
      description: All supported currency codes, names, and symbols. No authentication required; CORS-enabled; cached 24 hours; does not count toward your monthly quota.
      parameters:
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Supported currencies
          content:
            application/json:
              schema:
                type: object
                properties:
                  currencies:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: USD
                        name:
                          type: string
                          example: US Dollar
                        symbol:
                          type: string
                          example: $
                  count:
                    type: integer
                    example: 161
        '400':
          $ref: '#/components/responses/BadRequest'
  /api/open/central-banks:
    get:
      tags:
      - Open Endpoints
      operationId: listOpenCentralBanks
      summary: Catalogue of every official source — keyless
      description: Every central bank and tax authority the API serves, with the date of its latest published table, its age in days, a stale flag and its publication cadence. No API key. Use it to discover source codes for the other central-bank endpoints and to check freshness before citing a rate.
      responses:
        '200':
          description: Source catalogue
          content:
            application/json:
              schema:
                type: object
                properties:
                  sources:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: ecb
                        name:
                          type: string
                          example: European Central Bank
                        latest:
                          type: string
                          format: date
                          example: '2026-09-18'
                        age_days:
                          type: integer
                          example: 1
                        stale:
                          type: boolean
                          example: false
                        cadence:
                          type: string
                          example: daily
              example:
                sources:
                - code: ecb
                  name: European Central Bank
                  latest: '2026-09-18'
                  age_days: 1
                  stale: false
                  cadence: daily
                - code: hmrc
                  name: HM Revenue & Customs
                  latest: '2026-09-01'
                  age_days: 18
                  stale: false
                  cadence: monthly
  /api/open/central-bank/{bank}:
    get:
      tags:
      - Open Endpoints
      operationId: getOpenCentralBankLatest
      summary: Latest official table — keyless, attribution required
      description: The latest published table for a central bank or tax authority, with no API key. CORS-enabled and edge-cached (30–60 min), built for embeds and widgets. Free to use with a visible attribution link to allratestoday.com (the response includes the attribution object). Pass `source`+`target` for a single pair (direct or inverse only). JSON only. For historical dates, time series, or cross-computed pairs use the keyed `/api/v1/central-bank/*` endpoints.
      parameters:
      - $ref: '#/components/parameters/BankCode'
      - $ref: '#/components/parameters/PairSource'
      - $ref: '#/components/parameters/PairTarget'
      responses:
        '200':
          description: Latest published table (or single pair) with attribution
          content:
            application/json:
              schema:
                type: object
                properties:
                  bank:
                    type: string
                    example: ecb
                  rate_date:
                    type: string
                    format: date
                    example: '2026-08-10'
                  rates:
                    type: array
                    items:
                      $ref: '#/components/schemas/CbRate'
                  source:
                    type: string
                    description: Pair mode
                    example: EUR
                  target:
                    type: string
                    description: Pair mode
                    example: USD
                  rate:
                    type: number
                    format: double
                    description: Pair mode
                    example: 1.0853
                  rate_type:
                    type: string
                    description: Pair mode
                    example: reference
                  derived:
                    type: boolean
                    description: 'Pair mode: true when computed as the inverse of the published rate'
                  method:
                    type: string
                    enum:
                    - published
                    - inverse
                    description: Pair mode
                  attribution:
                    type: object
                    properties:
                      source:
                        type: string
                        example: Official rates published by ECB, served by AllRatesToday
                      url:
                        type: string
                        example: https://allratestoday.com/central-bank-rates-api/ecb/
                      terms:
                        type: string
                        example: Free to use with visible attribution linking to allratestoday.com
        '404':
          description: Unknown source, no published table yet, or pair not covered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/public/central-bank/{bank}:
    get:
      tags:
      - Open Endpoints
      operationId: downloadCentralBankLatest
      summary: Latest official table as JSON (open) or CSV/XLSX download (free account)
      description: The latest published table for one source. JSON is open (no key). `format=csv` and `format=xlsx` return a downloadable file and require a logged-in free account (session cookie) — register at https://allratestoday.com/register. XML is not supported on this endpoint.
      security:
      - {}
      - sessionCookie: []
      parameters:
      - $ref: '#/components/parameters/BankCode'
      - name: format
        in: query
        required: false
        description: json (open) or csv/xlsx file download (requires logged-in session)
        schema:
          type: string
          enum:
          - json
          - csv
          - xlsx
          default: json
      responses:
        '200':
          description: Latest table (raw cache shape) or file download
          content:
            application/json:
              schema:
                type: object
                properties:
                  bank:
                    type: string
                    example: ecb
                  rate_date:
                    type: string
                    format: date
                    example: '2026-08-10'
                  rates:
                    type: array
                    items:
                      type: object
                      properties:
                        base_ccy:
                          type: string
                          example: EUR
                        quote_ccy:
                          type: string
                          example: USD
                        rate_type:
                          type: string
                          example: reference
                        value:
                          type: number
                          format: double
                          example: 1.0853
            text/csv:
              schema:
                type: string
                format: binary
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: File downloads (csv/xlsx) require a logged-in free account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown source or no published table yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/open/geo:
    get:
      operationId: getVisitorGeo
      tags:
      - Open Endpoints
      summary: Visitor's country and currency — keyless
      description: 'The calling IP''s country (from Cloudflare''s edge) and the currency it maps to. Keyless and CORS-open (`Access-Control-Allow-Origin: *`), so browser packages such as react-currency-localizer-realtime can detect a visitor''s currency without a third-party geo-IP service. Never cached — the answer is per-IP. `country` and `currency` are null when the edge cannot determine a country.'
      parameters: []
      responses:
        '200':
          description: Country and mapped currency for the calling IP.
          content:
            application/json:
              schema:
                type: object
                properties:
                  country:
                    type:
                    - string
                    - 'null'
                    description: ISO 3166-1 alpha-2, or null
                  currency:
                    type:
                    - string
                    - 'null'
                    description: ISO 4217 code mapped from the country, or null
                  source:
                    type: string
                    enum:
                    - cloudflare
              example:
                country: GB
                currency: GBP
                source: cloudflare
  /api/compat/{provider}/latest:
    get:
      tags:
      - Open Endpoints
      operationId: compatLatest
      summary: Latest ECB table in a legacy provider's JSON shape — keyless
      description: Drop-in replacement for exchangeratesapi.io, the Fixer free tier, exchangerate.host and Frankfurter. Same fields those APIs returned, plus additive `source` and `attribution`. Keyless, CORS, edge-cached. See https://allratestoday.com/migrate/
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          enum:
          - exchangeratesapi
          - fixer
          - exchangerate-host
          - frankfurter
        description: Which provider's response shape to reproduce.
      - name: base
        in: query
        schema:
          type: string
          example: USD
        description: 'Base currency (Frankfurter alias: from). Default EUR.'
      - name: symbols
        in: query
        schema:
          type: string
          example: GBP,JPY
        description: 'Comma-separated quote currencies (Frankfurter alias: to). Default: all.'
      - name: amount
        in: query
        schema:
          type: number
          default: 1
        description: Frankfurter-style multiplier.
      responses:
        '200':
          description: Provider-shaped table
          content:
            application/json:
              example:
                base: USD
                date: '2026-09-12'
                rates:
                  GBP: 0.7377
                  JPY: 146.91
                source: European Central Bank reference rates, served by AllRatesToday
                attribution: https://allratestoday.com/migrate/
        '400':
          description: Unknown base or bad symbols, in the provider's error shape
  /api/agent/keys:
    get:
      tags:
      - Open Endpoints
      operationId: describeTrialKeys
      summary: How to self-issue a trial key — keyless
      description: Describes the trial-key contract (method, body, limits) so an agent that only knows the URL can use it.
      responses:
        '200':
          description: Endpoint manifest
          content:
            application/json:
              schema:
                type: object
    post:
      tags:
      - Open Endpoints
      operationId: issueTrialKey
      summary: Self-issue a 100-call trial API key — no account, no email
      description: 'Built for AI agents and other machine callers that cannot complete the human sign-up (captcha + email verification). Returns a key with 100 lifetime calls, valid 7 days, that unlocks everything a free account gets: real-time rates, latest central-bank tables, publication calendars (historical and dated rates, market and central-bank, are on paid plans). Limits: 3 keys per IP per day, 100 per day in total. Exhausted keys answer 429 with an upgrade_url. For a lasting key register at https://allratestoday.com/register (free). Send `Content-Type: application/json` (an empty JSON object is fine); a POST without it is rejected as a cross-site form.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                agent:
                  type: string
                  maxLength: 80
                  description: 'Optional: the agent or product requesting the key.'
                purpose:
                  type: string
                  maxLength: 200
                  description: 'Optional: one line on what the rates are for.'
        description: 'Optional fields. Always send `Content-Type: application/json`, with `{}` if you have nothing to say.'
      responses:
        '201':
          description: Trial key issued
          content:
            application/json:
              schema:
                type: object
                required:
                - api_key
                - calls_included
                - expires_at
                properties:
                  api_key:
                    type: string
                    example: art_live_k3j9x2m7q1w8e5r4t6y0u2i8o3p5a7s1
                  calls_included:
                    type: integer
                    example: 100
                  expires_at:
                    type: string
                    format: date-time
                  how_to_use:
                    type: string
                  mcp_url:
                    type: string
                    format: uri
                  included:
                    type: string
                  upgrade:
                    type: object
                    properties:
                      free_account:
                        type: string
                      paid_plans:
                        type: string
                  attribution:
                    type: string
        '429':
          description: Per-IP cap reached or too many attempts
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  retry_after_s:
                    type: integer
        '503':
          description: Today's global allocation is used up
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
  /api/open/reference-rate:
    get:
      tags:
      - Open Endpoints
      operationId: getOpenReferenceRate
      summary: Latest Daily Reference Rate (16:00 London) — keyless
      description: 'AllRatesToday Daily Reference Rate: one immutable mid-market USD table per business day, fixed at 16:00 Europe/London as the per-currency median of five once-a-minute samples (15:57:30–16:02:30). Never revised. Not the WM/Refinitiv fix and not a registered benchmark; for index calculation, research and reporting. Methodology: https://allratestoday.com/reference-rate/ Keyless with attribution; dated tables and history need a key.'
      parameters:
      - name: source
        in: query
        schema:
          type: string
          example: SAR
        description: 'With target: one pair, cross-computed via USD and flagged derived.'
      - name: target
        in: query
        schema:
          type: string
          example: USD
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - csv
          - xml
          - xlsx
        description: Output format (default json).
      responses:
        '200':
          description: Latest table or one pair
          content:
            application/json:
              schema:
                type: object
                properties:
                  rate_date:
                    type: string
                    format: date
                  time:
                    type: string
                    example: 16:00 London
                  base:
                    type: string
                    example: USD
                  window_start:
                    type: string
                    format: date-time
                  window_end:
                    type: string
                    format: date-time
                  samples:
                    type: integer
                  published_at:
                    type: string
                    format: date-time
                  method:
                    type: string
                  rates:
                    type: array
                    items:
                      type: object
                      properties:
                        base:
                          type: string
                        quote:
                          type: string
                        value:
                          type: number
                        low:
                          type: number
                        high:
                          type: number
                        samples:
                          type: integer
                  attribution:
                    type: object
                  disclaimer:
                    type: string
        '404':
          description: Not published yet (next_publication says when)
components:
  parameters:
    PairSource:
      name: source
      in: query
      required: false
      description: 'Pair mode: source currency, 3-letter code (requires target)'
      schema:
        type: string
        minLength: 3
        maxLength: 3
        example: USD
    Format:
      name: format
      in: query
      required: false
      description: Response format (default json). csv is UTF-8 with a BOM; xlsx is a real Excel workbook with typed dates and numbers; xml mirrors the JSON fields.
      schema:
        type: string
        enum:
        - json
        - csv
        - xml
        - xlsx
        default: json
    BankCode:
      name: bank
      in: path
      required: true
      description: Source code from /api/v1/central-banks (e.g. ecb, boc, cbsl, banxico, ustreasury)
      schema:
        type: string
        pattern: ^[a-z0-9_-]{2,20}$
        example: ecb
    PairTarget:
      name: target
      in: query
      required: false
      description: 'Pair mode: target currency, 3-letter code (requires source)'
      schema:
        type: string
        minLength: 3
        maxLength: 3
        example: LKR
  schemas:
    CbRate:
      type: object
      properties:
        base:
          type: string
          example: EUR
        quote:
          type: string
          example: USD
        type:
          type: string
          description: Rate type as labeled by the bank (reference, buying, selling, indicative, ...)
          example: reference
        value:
          type: number
          format: double
          example: 1.0853
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message
        hint:
          type: string
          description: Optional remediation hint
  responses:
    BadRequest:
      description: Invalid or missing parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key from your AllRatesToday dashboard. Example: `Authorization: Bearer art_live_xxxxx`. Free keys at https://allratestoday.com/register. Agents without an account: `POST /api/agent/keys` issues a 100-call trial key instantly.'
    apiKeyQuery:
      type: apiKey
      in: query
      name: key
      description: API key as a query parameter (accepted on /api/rate only; `apiKey` is an alias)
    sessionCookie:
      type: apiKey
      in: cookie
      name: art_session
      description: Session cookie for logged-in dashboard users