# CurrencyCore for AI agents

CurrencyCore is a currency data platform for developers and AI agents. It provides
a REST API for currency conversion and exchange rates, a native Model Context
Protocol (MCP) server, and a natural-language AI endpoint. This file is a
machine-readable summary so agents and crawlers can understand what the product
does, how to call it, and how it is priced.

- Website: https://currency-core.com
- Dashboard (sign up, API keys, billing): https://app.currency-core.com
- API base URL: https://api.currency-core.com
- Documentation: https://currency-core.com/docs/getting-started
- Pricing: https://currency-core.com/pricing
- Status: https://currency-core.com/status
- Support: support@currency-core.com

## What it does

- Convert any ISO 4217 currency pair with one authenticated request.
- Pull USD-base (or chosen-base) exchange-rate maps for many currencies at once.
- Query historical rates back to 1949 (time-series, prior-day, and as-of lookups), plus time-series and analysis APIs for trends, comparisons, and movers (Growth+).
- Connect AI assistants over MCP so they can use the same tools, keys, and limits.
- Ask currency questions in plain English and get a precise answer backed by live rates.
- Manage usage as a team: organizations, shared API keys, roles, SSO, and audit logs.

## Authentication

All API requests use a Bearer API key from the dashboard:

```
Authorization: Bearer cc_live_your_key
```

Keys are scoped to an organization. Live and test keys are supported. Get a free
key at https://app.currency-core.com (1,000 requests and 100 AI credits per month
on the free plan, no credit card).

## REST endpoints

Base URL: `https://api.currency-core.com`

- `GET /v1/convert?from=USD&to=INR&amount=100`: convert an amount between two currencies.
- `GET /v1/rates?base=USD`: base-currency exchange-rate map.
- `GET /v1/history?currency=INR&from=&to=&base=USD&interval=daily`: one currency's daily exchange-rate time series, rebased to `base`, dense (gaps carried forward), today included live; `interval=daily|weekly|monthly|yearly` averages into buckets (Growth plan or higher).
- `GET /v1/history/analysis?base=&currencies=&from=&to=&period=&sort=&limit=&interval=&stats=&assetClass=`: historical trends, comparisons, and "movers" — pass `currencies=GBP,EUR,AED` to compare, or omit to rank ALL currencies vs base (`sort=strengthened|weakened`, `limit`, `assetClass=fiat|metals|all`); returns per-currency `startRate`/`endRate`, `changePct`, `strengthenedPct`, optional `stats`, and optional trend `series`. `period` shorthand: 10y/6m/30d/ytd/max (Growth plan or higher).
- `GET /v1/ppp/analysis?countries=IND,DEU,USA&from=&to=&period=&sort=&limit=&stats=`: PPP (purchasing-power-parity) over time — per-country PPP factor at the window endpoints, `changePct`, optional yearly `series`; omit `countries` to rank all (Growth plan or higher).
- `GET /v1/volatility?currency=EUR&base=USD&from=&to=&sort=&limit=`: annualized volatility of daily returns; name `currency`/`currencies` to measure/compare, or omit to rank the liquid set by stability (Growth plan or higher).
- `GET /v1/correlation?base=EUR&currencies=GBP,CHF,SEK&from=&to=`: Pearson correlation of each currency's daily returns with `base` (Growth plan or higher).
- `GET /v1/drawdown?currency=EUR&base=USD&from=&to=`: maximum peak-to-trough decline with peak/trough/recovery dates (Growth plan or higher).
- `GET /v1/currencies`: list of supported currencies (160+).
- `GET /v1/countries`: list of countries with currency metadata.
- `GET /v1/ai?q=Convert%2050%20EUR%20to%20INR`: natural-language query (costs 1 AI credit). On Growth+ it also answers trends, PPP-over-time, volatility/stability, correlation, and drawdown questions.

Historical data is available on the rate endpoints via a `date=YYYY-MM-DD` parameter. The **analytics & time-series API** — `/v1/history`, `/v1/history/analysis`, `/v1/ppp/analysis`, `/v1/volatility`, `/v1/correlation`, `/v1/drawdown` — requires the Growth plan or higher (free/starter return 403).

### Example

```
curl https://api.currency-core.com/v1/convert \
  -H "Authorization: Bearer cc_live_your_key" \
  -G \
  --data-urlencode "from=USD" \
  --data-urlencode "to=INR" \
  --data-urlencode "amount=100"
```

```
{ "from": "USD", "amount": 100, "date": "2026-06-09",
  "results": [{ "to": "INR", "result": 8345.00, "rate": 83.45 }] }
```

## MCP server

CurrencyCore ships a native Model Context Protocol server, so AI assistants
(Claude, Cursor, VS Code, Gemini, and others) can fetch live rates and convert
using your organization's keys, usage, and limits. MCP is included on every plan,
including Free. It also exposes `get_history` (one currency's rebased time series)
and `analyze_history` (trends, comparisons, and movers) tools, which require the
Growth plan or higher (enforced at call time). See https://currency-core.com/docs/mcp.

## AI queries

The `/v1/ai` endpoint turns a natural-language question into a precise answer
backed by live rates, returning both the human-readable answer and the structured
numbers behind it. It can also answer historical-trend and comparison questions in
plain English (e.g. "How did EUR perform vs USD over the last decade?", "Which
currencies strengthened most against INR since 2015?"); the historical analysis
requires the Growth plan or higher. One AI credit per query. See
https://currency-core.com/docs/ai-endpoint.

## Pricing

API requests and AI usage are metered separately. Billing is handled by Dodo
Payments (Merchant of Record) with tax applied at checkout. MCP access is included
on every plan. Annual billing is roughly two months free. Upgrades take effect
instantly; downgrades take effect at the end of the billing cycle.

### Plan comparison

| Feature | Free | Starter | Growth | Growth Plus | Business | Enterprise |
| --- | --- | --- | --- | --- | --- | --- |
| Price (monthly) | $0 | $9 | $29 | $79 | $199 | Custom |
| Price (annual) | $0 | $90 | $290 | $790 | $1,990 | Custom |
| API requests / month | 1,000 | 50,000 | 500,000 | 2,000,000 | 10,000,000 | Custom |
| Rate limit | 60/min | 120/min | 600/min | 3,000/min | 6,000/min | Custom |
| Over-usage (per 1,000 requests) | No overage | $0.05 | $0.04 | $0.04 | $0.03 | Custom |
| AI credits / month | 100 | 1,000 | 5,000 | 20,000 | 50,000 | Custom |
| Team seats | 3 | 10 | Unlimited | Unlimited | Unlimited | Unlimited |
| Historical data | 30-day history | Full history | Full history | Full history | Full history | Full history |
| Analytics & time-series API | No | No | Yes | Yes | Yes | Yes |
| MCP access | Yes | Yes | Yes | Yes | Yes | Yes |
| OIDC SSO | No | No | No | No | Yes | Yes |
| Audit logs | No | No | No | No | Yes | Yes |
| Priority support | No | No | Yes | Yes | Yes | Yes |
| Custom SLA | No | No | No | No | No | Yes |

Growth is the most popular plan. Enterprise is custom: contact
support@currency-core.com for volume pricing, SSO, audit logs, priority support,
and a dedicated SLA. Over-limit requests on paid plans are billed as metered
overage at the per-1,000 rate above; Free hard-caps at its limit (no overage).

### AI credit add-ons

1 AI credit = 1 AI request. Each plan includes a monthly AI credit allowance that
resets every billing cycle. You can top up any plan with one-time credit packs;
purchased credits never expire and are used only after the monthly allowance is
spent. See https://currency-core.com/docs/ai-credits.

| Pack | Credits | Price |
| --- | --- | --- |
| 10k | 10,000 | $19 |
| 25k | 25,000 | $49 |
| 50k | 50,000 | $89 (best value) |
| 100k | 100,000 | $169 |

## Features by area

- Currency API: conversion, base-currency rate maps, 160+ currencies, edge-cached.
- Historical data: rates back to 1949, time-series, prior-day, and as-of lookups; plus the **analytics & time-series API** (Growth+) — `/v1/history`, `/v1/history/analysis` (trends/comparisons/movers), `/v1/ppp/analysis` (PPP over time), `/v1/volatility`, `/v1/correlation`, and `/v1/drawdown`.
- MCP server: included on every plan, governed by the same keys and limits.
- AI queries: natural-language currency questions, one credit each.
- Team workspaces: organizations, shared API keys, member invites, per-org usage.
- Enterprise: OIDC Single Sign-On, audit logs, role-based access, unlimited seats, priority support, custom SLA.

## Security

- DDoS protection: always-on, unmetered mitigation across Cloudflare's global edge, in front of every request.
- OIDC Single Sign-On (SSO): connect Okta, Microsoft Entra ID, Google Workspace, and other OIDC providers, with DNS domain verification and optional Require-SSO enforcement (Business and Enterprise plans).
- Audit logs: a durable, exportable trail of every API key, billing, team, and security change in your organization (Business and Enterprise plans).
- Role-based access control: owner, admin, and member roles govern who can manage keys, billing, and members.
- API key security: keys are hashed at rest, scoped to a single organization, separated into live and test environments, and revocable instantly.
- Encrypted in transit: every request is served over HTTPS (TLS).
- Rate limiting and abuse controls: per-plan rate limits, brute-force protection on sign-in, and per-organization quotas and hard caps.
- No card data stored: payments run through Dodo Payments as Merchant of Record, so full card details never touch our systems.

## Documentation index

- Getting started: https://currency-core.com/docs/getting-started
- Authentication: https://currency-core.com/docs/authentication
- Convert endpoint: https://currency-core.com/docs/convert-endpoint
- Rates endpoint: https://currency-core.com/docs/rates-endpoint
- History endpoint: https://currency-core.com/docs/history-endpoint
- History analysis endpoint: https://currency-core.com/docs/history-analysis-endpoint
- AI endpoint: https://currency-core.com/docs/ai-endpoint
- AI credits: https://currency-core.com/docs/ai-credits
- MCP server: https://currency-core.com/docs/mcp
- Currencies: https://currency-core.com/docs/currencies
- Countries: https://currency-core.com/docs/countries
- Error codes: https://currency-core.com/docs/errors
- Code examples: https://currency-core.com/docs/code-examples

## Legal

- Privacy policy: https://currency-core.com/privacy
- Terms of service: https://currency-core.com/terms