# Currency-Exchange.app API Reference

> Currency exchange rate API for production applications: live and historical FX rates, conversion, and a searchable fiat currency catalog.

The API is served at `https://api.currency-exchange.app` (the same API is also reachable same-origin at `https://currency-exchange.app/api`). All endpoints authenticate with an `x-api-key` header and are billed per call.

## Start here

- Interactive API reference (with one-click MCP install buttons): https://currency-exchange.app/open-api
- MCP integration guide for AI agents: https://currency-exchange.app/guides/mcp-server
- OpenAPI document (machine-readable, this is the contract): https://currency-exchange.app/json/open-api.json
- Pricing and credit packs: https://currency-exchange.app/pricing
- Live demo in the browser: https://currency-exchange.app/try
- Guides: https://currency-exchange.app/guides
- Technical articles: https://currency-exchange.app/blog

## MCP server for AI agents

- Endpoint: https://api.currency-exchange.app/mcp
- Transport: Streamable HTTP — POST JSON-RPC 2.0, header `Accept: application/json, text/event-stream`
- Auth: `x-api-key` header with a product API key (host-scoped; cross-product keys are rejected with A1003)
- Demo access: key `demo-key` with a valid TOTP in `x-ct` (rate-limited, evaluation only)
- Billing: 1 credit per tool call; `account_whoami` is free; HTTP 402 means out of credits (top up at https://currency-exchange.app/pricing)
- Tools: - account_whoami (free identity probe)
- currency_list (paginated catalog with search)
- currency_get_rate (live/historical + inverse rate)
- currency_convert (amount conversion with rate detail)
- Discovery: https://currency-exchange.app/.well-known/mcp/server-card.json · this llms.txt · the Scalar MCP panel on /open-api
- The server returns agent instructions in the MCP initialize result.

## Authentication and errors

- `x-api-key` header (or `x-api-key` query parameter) — create keys at https://currency-exchange.app/account/api-keys. Keys are scoped to this product host.
- `x-jwt-token` header — session alternative; when both are present the API key wins.
- Error envelope: `{ "error": "CODE", "message": "...", "issues": [...] }`. Auth codes: A1001 missing credential, A1002 malformed key, A1003 unknown/disabled key or cross-host key, A1004 invalid TOTP, A1006 unverified account, A1008 authentication required, A1009 admin required.
- Rate limits: guest limits are strict and per-IP; authenticated keys get plan-based limits (429 with Retry-After when exceeded).

## API endpoints

### Currency
- `GET /v1-convert-currency` — Convert an amount: Convert a source amount into a target currency using the latest available exchange rate, or a historical rate when you provide a date.
- `GET /v1-get-currency-exchange-rate` — Get an exchange rate: Return the current or historical exchange rate for a currency pair, including the inverse rate and rate timestamp.
- `GET /v1-get-currency-details` — Get currency metadata: Look up display-ready currency metadata such as the ISO code, symbol, native name, countries, denominations, and decimal precision.
- `GET /v1-list-currencies` — List supported currencies: Browse and search the currencies supported by Currency-Exchange.app. Use filters to request specific codes or trim fields for faster responses.

### API Key
- `POST /v1-create-api-key` — Create an API key: Create a new API key for calling Currency-Exchange.app endpoints from your application or backend service.
- `POST /v1-list-api-keys` — List API keys: List the API keys available for your account so you can display, audit, or rotate credentials.
- `POST /v1-get-api-key-details` — Get API key details: Retrieve details for one API key, including status, allowed services, environment, and timestamps.
- `POST /v1-update-api-key` — Update an API key: Rename an API key, enable or disable it, or update the services it can access.
- `POST /v1-delete-api-key` — Delete an API key: Permanently delete an API key you no longer want to use.
- `GET /v1-who-am-i` — Inspect the current API key: Check which account and request context are associated with the API key used for the request.

### API Usage
- `GET /v1-get-api-usage` — Get daily usage: Return daily request counts for your Currency-Exchange.app usage over a selected date range.
- `GET /v1-download-api-usage` — Export usage data: Generate a downloadable usage export for reporting, reconciliation, or cost tracking.

## Workflows

- Payroll and contractor payments — convert invoice amounts with currency_convert and store rateTime for audit.
- Expense automation — normalize multi-currency receipts with currency_convert.
- Marketplace pricing — keep prices fresh using currency_get_rate on a schedule; historical dates supported.
- Rate monitoring — watch pairs with currency_get_rate and alert on thresholds.

## Notes for agents

- All lookups are read-only and cache-backed; pass `skipCache=true` only when freshness matters.
- The bulk JSON upload endpoints run asynchronously: upload, poll list status, then download results.
- Tool calls over MCP and REST calls cost the same credits and return the same data shapes.