HEDGR Rates API

openapi: 3.2.0
info:
  title: HEDGR public Rates API
  version: 1.0.0
  description: HEDGR is the AI FX agent for SME finance teams. This document covers the genuinely public, unauthenticated surface (health checks, public rates, OAuth discovery metadata) plus the MCP endpoint agents use to call Hedgr's read-only dashboard tools. The authenticated /api/* dashboard namespace used by the Hedgr web app is intentionally not enumerated here - see https://hedgr.app/developer-docs for why.
  contact:
    name: HEDGR support
    email: support@hedgr.app
    url: https://hedgr.app/support
  termsOfService: https://hedgr.app/terms
  x-logo:
    url: https://hedgr.app/hedgr-logo-icon.svg
  x-api-version: '2026-08-22'
  x-versioning-policy:
    strategy: header
    header: Hedgr-API-Version
    current_version: '2026-08-22'
    supported_versions:
    - '2026-08-22'
    response_header: Every /api response carries `Hedgr-API-Version` naming the contract that answered it.
    request_pinning: A client MAY pin by sending `Hedgr-API-Version`. An unrecognised value is rejected with 400 and a typed ApiError rather than silently served the current shape, so a pin is never quietly ignored.
    mcp: The MCP endpoint versions separately, per request, via the JSON-RPC `protocolVersion` field. GET /mcp lists every accepted version in `protocolVersions`; POST /mcp with method=initialize negotiates one and echoes the agreed value.
    deprecation: A version being retired is announced on its responses with the standard `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers before removal, and in CHANGELOG.md. Versions are added append-only; an older version keeps serving until its Sunset date passes.
    breaking_change_definition: Removing or renaming a field, narrowing a type, or changing an existing status code. Adding a new optional field is not breaking and does not bump the version.
servers:
- url: https://hedgr.app
  description: Production
security:
- mcpOAuth:
  - fx:read
tags:
- name: Rates
  description: Public FX reference rates.
paths:
  /api/rates/public:
    get:
      operationId: getPublicRates
      tags:
      - Rates
      summary: Public FX reference rates
      description: Public reference rates for CSV/manual-workspace users who have not connected an accounting provider. No authentication required.
      security: []
      parameters:
      - name: Hedgr-API-Version
        in: header
        required: false
        description: Optional version pin. Send the version your integration was built against; an unrecognised value is rejected with 400 rather than silently served the current shape. Every response echoes the serving version in the header of the same name.
        schema:
          type: string
          enum:
          - '2026-08-22'
          example: '2026-08-22'
      - name: baseCurrency
        in: query
        required: false
        description: ISO 4217 base currency. Defaults to the platform base currency (GBP).
        schema:
          type: string
          example: GBP
      - name: source
        in: query
        required: false
        description: Rate source override.
        schema:
          type: string
          default: frankfurter
      responses:
        '200':
          description: Current reference rates against the requested base currency.
          headers:
            Hedgr-API-Version:
              schema:
                type: string
                example: '2026-08-22'
              description: The API contract version that served this response.
            Deprecation:
              schema:
                type: string
              description: RFC 9745. Present only while this version is being retired.
            Sunset:
              schema:
                type: string
              description: RFC 8594. Present only while this version is being retired; the date after which it stops responding.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicRates'
        '400':
          description: Unrecognised `Hedgr-API-Version` pin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Rate source unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message. Stable enough to match on for known cases (e.g. "Missing Bearer token"), but not a separate machine-readable error code today.
    PublicRates:
      type: object
      description: Reference FX rates against a base currency.
      required:
      - base
      - rates
      - source
      properties:
        base:
          type: string
          example: GBP
        rates:
          type: object
          additionalProperties:
            type: number
          description: Currency code -> rate against base.
        source:
          type: string
          example: frankfurter
        timestamp:
          type: integer
          description: Unix epoch ms of the cached rate set.
  securitySchemes:
    mcpOAuth:
      type: oauth2
      description: OAuth 2.1 authorization-code flow with PKCE and dynamic client registration. See /.well-known/oauth-authorization-server.
      flows:
        authorizationCode:
          authorizationUrl: https://hedgr.app/mcp/oauth/authorize
          tokenUrl: https://hedgr.app/mcp/oauth/token
          scopes:
            fx:read: Read-only access to FX exposure, cash position, hedge portfolio, P&L, policy, and related dashboard data via MCP tools.
    partnerKey:
      type: http
      scheme: bearer
      bearerFormat: hpk_live_...
      description: 'Partner API key issued by Hedgr to a broker firm. Send as Authorization: Bearer <key>. See https://hedgr.app/partner-api.'
externalDocs:
  description: Developer boundary summary
  url: https://hedgr.app/developer-docs