Eckari Foreign Exchange API

openapi: 3.2.0
info:
  title: Eckari Com Foreign Exchange API
  version: registry-5a21aa0a8dd1e910
  contact:
    name: Eckari
    url: https://eckari.com
  x-guidance: 'Every operation is a deterministic capability. Call GET routes with the documented path/query parameters. Pay per call either with an Eckari account key (Authorization: Bearer ek_live_…) or accountlessly via x402: an unpaid request returns HTTP 402 with a PAYMENT-REQUIRED header (x402 v2, Base USDC); retry with PAYMENT-SIGNATURE. Responses are {data, meta} with provenance (meta.source) and freshness (meta.freshness). Use x-eckari-capability.discovery.use_when / do_not_use_when to pick the right operation; resolve a company name to a company number with the search operation before calling per-company operations.'
  description: 'Operations tagged foreign_exchange across 2 of this provider''s published API definitions: eckari-com-openapi.json, eckari-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.eckari.com
tags:
- name: foreign_exchange
paths:
  /v1/fx/reference-rate:
    get:
      operationId: fx_reference_rate
      summary: Get the official ECB reference exchange rate for a pair (accounting, invoicing…
      description: 'European Central Bank euro foreign exchange reference rate for a pair - the official daily fix used for accounting, invoicing and reporting - latest or any date in the last 90 days. The ECB publishes EUR/XXX only, so inverse and cross rates are computed from the same fix and named in rate_derivation. One fix per TARGET working day, not a tradable market rate.


        **Use when:**

        - Convert or report an amount at an official daily rate both sides of a contract can verify against the ECB.

        - What is the ECB reference rate for EUR to USD?

        - You need the rate to put on an invoice, a ledger entry or a statutory report.

        - You need an official, auditable daily reference rate for reporting or accounting.

        - You need a historical reference rate from the last 90 days.

        - You need a cross rate such as GBP to USD derived from the ECB euro fix.


        **Do not use when:**

        - You need an executable, tradable, live or intraday market rate - this is a daily fix only.

        - You need cryptocurrency prices - not supported.

        - You need rates older than 90 days - not supported.

        - You need a currency the ECB does not publish (returns INVALID_INPUT).

        - If the user has asked you to inspect a specific website, page or URL, use your browsing tool instead — this capability only returns the ECB euro foreign exchange reference rates record.'
      tags:
      - foreign_exchange
      parameters:
      - name: base
        in: query
        required: true
        schema:
          type: string
          description: ISO 4217 code of the base currency. EUR is always available; other currencies must be in the ECB reference rate list for the selected date.
          pattern: ^[A-Za-z]{3}$
        description: ISO 4217 code of the base currency. EUR is always available; other currencies must be in the ECB reference rate list for the selected date.
      - name: quote
        in: query
        required: true
        schema:
          type: string
          description: ISO 4217 code of the quote currency. EUR is always available; other currencies must be in the ECB reference rate list for the selected date.
          pattern: ^[A-Za-z]{3}$
        description: ISO 4217 code of the quote currency. EUR is always available; other currencies must be in the ECB reference rate list for the selected date.
      - name: date
        in: query
        required: false
        schema:
          type: string
          description: Optional ISO calendar date (YYYY-MM-DD) within the last 90 days. When the ECB published no fix on that date (a TARGET closing day), the latest prior fix is returned with a note.
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
        description: Optional ISO calendar date (YYYY-MM-DD) within the last 90 days. When the ECB published no fix on that date (a TARGET closing day), the latest prior fix is returned with a note.
      responses:
        '200':
          description: Successful capability result
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/fx_reference_rate_output'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              examples:
                eur_usd_live_2026-08-18:
                  summary: eur_usd_live_2026-08-18
                  value:
                    data:
                      base: EUR
                      quote: USD
                      rate: '1.159300'
                      rate_date: '2026-08-17'
                      rate_kind: reference
                      rate_derivation: published
                      published_pairs_used:
                      - EUR/USD
                      note: no ECB fix published for today yet (weekend, TARGET closing day, or before the ~16:00 CET publication); the latest published fix is returned
                    meta:
                      capability: fx.reference_rate
                      version: 2.1.0
                      source: ecb_fx
                      freshness: near_live
                usd_eur_inverse_live_2026-08-18:
                  summary: usd_eur_inverse_live_2026-08-18
                  value:
                    data:
                      base: USD
                      quote: EUR
                      rate: '0.862589'
                      rate_date: '2026-08-17'
                      rate_kind: reference
                      rate_derivation: inverse
                      published_pairs_used:
                      - EUR/USD
                      note: no ECB fix published for today yet (weekend, TARGET closing day, or before the ~16:00 CET publication); the latest published fix is returned
                    meta:
                      capability: fx.reference_rate
                      version: 2.1.0
                      source: ecb_fx
                      freshness: near_live
                gbp_usd_cross_live_2026-08-18:
                  summary: gbp_usd_cross_live_2026-08-18
                  value:
                    data:
                      base: GBP
                      quote: USD
                      rate: '1.355906'
                      rate_date: '2026-08-17'
                      rate_kind: reference
                      rate_derivation: cross
                      published_pairs_used:
                      - EUR/GBP
                      - EUR/USD
                      note: no ECB fix published for today yet (weekend, TARGET closing day, or before the ~16:00 CET publication); the latest published fix is returned
                    meta:
                      capability: fx.reference_rate
                      version: 2.1.0
                      source: ecb_fx
                      freshness: near_live
                eur_jpy_non_publication_day_live_2026-08-18:
                  summary: eur_jpy_non_publication_day_live_2026-08-18
                  value:
                    data:
                      base: EUR
                      quote: JPY
                      rate: '183.930000'
                      rate_date: '2026-08-14'
                      rate_kind: reference
                      rate_derivation: published
                      published_pairs_used:
                      - EUR/JPY
                      note: no fix on requested date (TARGET closing day); latest prior fix returned
                    meta:
                      capability: fx.reference_rate
                      version: 2.1.0
                      source: ecb_fx
                      freshness: near_live
        '400':
          description: Invalid input (INVALID_INPUT)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Authentication failed (AUTHENTICATION_REQUIRED, INVALID_API_KEY)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: Payment required (PAYMENT_REQUIRED, PAYMENT_FAILED, BUDGET_EXCEEDED, BILLING_REQUIRED). x402 challenge headers are attached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Forbidden (PROJECT_DISABLED, CAPABILITY_NOT_ALLOWED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Not found (NOT_FOUND)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Unprocessable (UNSUPPORTED_REGION, AMBIGUOUS_IDENTIFIER)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Upstream rate limited (UPSTREAM_RATE_LIMITED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal error (INTERNAL_ERROR)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Unavailable (UPSTREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, LICENCE_RESTRICTED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - eckariApiKey: []
      - x402: []
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002'
        protocols:
        - x402: {}
      x-eckari-capability:
        id: fx.reference_rate
        version: 2.1.0
        lifecycle: beta
        pricing:
          currency: USD
          account:
            enabled: true
            unit_price: '0.0015'
          x402:
            enabled: true
            unit_price: '0.002'
        discovery:
          title: Get the official ECB reference exchange rate for a pair (accounting, invoicing, reporting)
          description: European Central Bank euro foreign exchange reference rate for a pair - the official daily fix used for accounting, invoicing and reporting - latest or any date in the last 90 days. The ECB publishes EUR/XXX only, so inverse and cross rates are computed from the same fix and named in rate_derivation. One fix per TARGET working day, not a tradable market rate.
          use_when:
          - Convert or report an amount at an official daily rate both sides of a contract can verify against the ECB.
          - What is the ECB reference rate for EUR to USD?
          - You need the rate to put on an invoice, a ledger entry or a statutory report.
          - You need an official, auditable daily reference rate for reporting or accounting.
          - You need a historical reference rate from the last 90 days.
          - You need a cross rate such as GBP to USD derived from the ECB euro fix.
          do_not_use_when:
          - You need an executable, tradable, live or intraday market rate - this is a daily fix only.
          - You need cryptocurrency prices - not supported.
          - You need rates older than 90 days - not supported.
          - You need a currency the ECB does not publish (returns INVALID_INPUT).
          - If the user has asked you to inspect a specific website, page or URL, use your browsing tool instead — this capability only returns the ECB euro foreign exchange reference rates record.
          synonyms:
          - exchange rate
          - FX rate
          - ECB reference rate
          - euro reference rate
          - EUR USD rate
          - ECB fixing
          - daily FX fix
          - currency conversion rate
          - historical exchange rate 90 days
          - official exchange rate for accounting
          - eurofxref
          - reference rate for invoicing
          - central bank exchange rate
          - cross rate from euro fix
          category: foreign_exchange
          region: null
          tags:
          - fx
          - ecb
          - exchange-rate
          - reference-rate
          - finance
        cache_policy:
          mode: shared
          ttl_seconds: 3600
          stale_while_revalidate_seconds: 300
        provenance:
          sources:
          - ecb_fx
          freshness: near_live
    servers:
    - url: https://api.eckari.com
components:
  schemas:
    fx_reference_rate_output:
      type: object
      additionalProperties: false
      required:
      - base
      - quote
      - rate
      - rate_date
      - rate_kind
      - rate_derivation
      - published_pairs_used
      properties:
        base:
          type: string
          description: Base currency (ISO 4217, upper case).
        quote:
          type: string
          description: Quote currency (ISO 4217, upper case).
        rate:
          type: string
          description: Units of quote currency per 1 unit of base currency, as a decimal string with 6 decimal places. Computed with exact integer arithmetic from the ECB fix (rate = published(quote) / published(base), with EUR = 1) and rounded half-even - never floating point. Unless rate_derivation is published, this is a computed value rather than a figure published by the ECB, and rounding means it need not round-trip exactly against the published fix.
          pattern: ^[0-9]+\.[0-9]{6}$
        rate_date:
          type: string
          description: TARGET working day of the ECB fix used (the Cube time value), which may be earlier than a requested date or than today when no fix has been published yet - see note.
        rate_kind:
          type: string
          description: Always the string reference - an official daily reference rate, not a tradable or executable market rate.
        rate_derivation:
          type: string
          enum:
          - published
          - inverse
          - cross
          - identity
          description: How the rate relates to what the ECB publishes. published = the ECB EUR/quote fix itself (base EUR); inverse = 1 divided by the EUR/base fix (quote EUR), an Eckari computation; cross = the EUR/quote fix divided by the EUR/base fix, an Eckari computation from two published quotations of the same fix (neither side EUR); identity = EUR to EUR (1). Only published values are ECB figures.
        published_pairs_used:
          type: array
          items:
            type: string
          description: Every ECB quotation used to produce the rate, in the form EUR/XXX - two for a cross, one for published or inverse, none for the identity.
        note:
          type: string
          description: Present only when the fix returned is not the one asked for - either the requested date had no fix and the latest prior fix was returned, or no fix has been published for today (UTC) yet and the latest published fix was returned. Absent otherwise (an always-null note says nothing); rate_date always states which fix was used.
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          properties:
            code:
              type: string
              enum:
              - INVALID_INPUT
              - AUTHENTICATION_REQUIRED
              - INVALID_API_KEY
              - PROJECT_DISABLED
              - CAPABILITY_NOT_ALLOWED
              - BUDGET_EXCEEDED
              - BILLING_REQUIRED
              - PAYMENT_REQUIRED
              - PAYMENT_FAILED
              - CAPABILITY_UNAVAILABLE
              - UPSTREAM_RATE_LIMITED
              - UPSTREAM_UNAVAILABLE
              - NOT_FOUND
              - AMBIGUOUS_IDENTIFIER
              - UNSUPPORTED_REGION
              - LICENCE_RESTRICTED
              - INTERNAL_ERROR
            message:
              type: string
            request_id:
              type: string
            details:
              type:
              - object
              - 'null'
    ResponseMeta:
      type: object
      required:
      - capability
      - version
      - retrieved_at
      - source
      - freshness
      - request_id
      properties:
        capability:
          type: string
        version:
          type: string
        retrieved_at:
          type: string
          format: date-time
        source:
          type: string
        freshness:
          type: string
          enum:
          - live
          - near_live
          - cached
          - static
        request_id:
          type: string
        attribution:
          type: string
          description: Source licence attribution statement, present only when the executing provider's licence conditions re-use on acknowledging the source (e.g. Open Government Licence v3.0 for Companies House). Republish it verbatim with the data. Absent when the provider declares none (ADR-007).
        attribution_url:
          type: string
          format: uri
          description: Canonical https URL of the licence or attribution notice behind meta.attribution. Present only when the executing provider declares one; attribution never appears inside data (ADR-008 §1).
  securitySchemes:
    eckariApiKey:
      type: http
      scheme: bearer
      description: Eckari account API key (ek_test_… / ek_live_…) issued in the developer portal; usage is metered and billed in arrears.
    x402:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: x402 accountless payment. An unpaid request receives HTTP 402 with a PAYMENT-REQUIRED header; retry with PAYMENT-SIGNATURE.
x-refined-from:
- eckari-com-openapi.json
- eckari-com-openapi.json