Skip to main content
Financial Data API is macro and global-markets data infrastructure built to be read and called by LLM agents, not only by humans. It serves official and public-domain macro indicators, rates and yields, FX reference rates, the economic calendar, SEC fundamentals, and derived analytics as predictable JSON, with per-observation provenance and rights metadata. Every endpoint is read-only and GET. Every response shares one envelope. Every error carries a stable, machine-readable code. That consistency is what makes an agent reliable against the API: it never has to guess the shape of a response or parse free-form error prose.

​
Why Financial Data API is agent-native

One predictable envelope

Every response is { data, meta, requestId }. Lists carry meta.pagination. An agent learns the shape once and reuses it across every endpoint.

Stable error codes

Errors return a machine-readable code (bad_request, unauthorized, forbidden, not_found, rate_limited, internal_error) plus a requestId. Unknown query params fail closed with bad_request rather than being silently ignored, so a typo surfaces instead of returning wrong data.

Discoverable by design

GET /llms.txt and GET /llms-full.txt describe the entire API as plain text an agent can read with no key. GET /openapi.json is the OpenAPI 3.1 source of truth.

Auditable provenance

Observations carry source attribution, source URL, freshness, a raw payload reference, and rights metadata. GET /v1/provenance/observations/{observationId} returns the full chain from official release to API response, so an agent can cite where a number came from.

​
The three ways an agent consumes Financial Data API

Native MCP server

The Financial Data API Model Context Protocol server exposes the API as read-only tools (screen_macro, get_latest_observations, cross_country, rates_analytics, observation_provenance, and more). Add it to Claude Code, Claude Desktop, or Cursor and your agent can query macro data conversationally with no glue code. This is the lowest-friction path for a chat-driven agent.

Self-describing text indexes

Point an agent at /llms.txt for a compact, sectioned index of every endpoint, or /llms-full.txt for the full reference with parameters. Both need no API key and stay in lock-step with the OpenAPI spec. An agent can fetch one, learn the surface, then call endpoints directly with HTTP.

Typed SDK

The @financialdatapi/client TypeScript SDK wraps the same envelope and errors. It constructs with your apiKey, throws a typed FinancialDataApiError on non-2xx, auto-paginates cursor pages via an async iterator, and ships a buildScreenerFilter helper for the screener DSL. Use it when your agent runs inside a TypeScript or JavaScript runtime.

​
Base URL and auth

All paths are relative to https://api.financialdatapi.com. Send your key as x-api-key: <key> or Authorization: Bearer <key>. The following endpoints need no key: GET /health, GET /ready, GET /openapi.json, GET /llms.txt, GET /llms-full.txt. Everything under /v1 requires a key.
Create an API key at app.financialdatapi.com: sign up, verify your email, and it is active immediately, with no card required. Keys are SHA-256 hashed server-side and never returned.

​
Conventions an agent should know

  • Envelope. Lists return { "data": [...], "meta": { "request_id", "requestId", "api_version", "pagination" }, "requestId" }. Items return { "data": { ... }, "meta": { ... }, "requestId" }.
  • Pagination. Cursor-based: limit (1 to 500, default 100) and an opaque cursor. Follow meta.pagination.next_cursor while has_more is true.
  • Time model. period / period_start / period_end filter the period a value describes (for example May 2026 CPI). start_date / end_date filter knowledge-time (observed_at, when the value became known). as_of returns the latest vintage known on or before a timestamp; revisions are retained, never overwritten.
  • Rights-aware. /v1/public/* returns only redistribution-safe official and public-domain data. Licensed vendor data is internal-only and never appears on the public surface.
  • Read-only. Every endpoint is GET.
as_of currently approximates the ingestion timestamp, not a full provider-vintage reconstruction. Full vintage reconstruction is future work. Treat as_of as “known to Financial Data API on or before this time” rather than “published by the provider on or before this time”.

​
Latest readings in one call

To see the live breadth of what is covered (catalog totals, public indicator categories, covered countries), call GET /v1/public/coverage rather than relying on a number hard-coded in docs.

​
Next steps

MCP server

Add Financial Data API’s read-only tools to Claude Code, Claude Desktop, or Cursor.

llms.txt

The keyless, self-describing indexes an agent reads to discover the API.