# Forex API on API Mercado

> Mid-market prices and finalized daily closes & official daily fixings published by central banks. Published by Capital Enesti and sold through API Mercado, an API marketplace: one gateway, one Key, pay per request from a prepaid balance.

This guide is for coding agents and developers. It explains how to get access, how to call this API through the gateway, and how to generate a typed client. Everything an agent needs is here or linked as markdown.

## Identifiers

- Human page: https://apimercado.com/discover/capitalenesti/fx-api
- Provider: Capital Enesti, gateway segment `@capitalenesti` (the public id `e72bpbz582mh` is also accepted, for URLs copied before slugs existed)
- API slug: `fx-api`
- Gateway base URL: `https://eu-north-1.apimercado.com/v1/@capitalenesti/fx-api/`
- Same API under the legacy id URL: `https://eu-north-1.apimercado.com/v1/e72bpbz582mh/fx-api/`
- OpenAPI document (no Key needed): https://eu-north-1.apimercado.com/v1/@capitalenesti/fx-api/openapi.json
- Current version: 1.1.0

## 1. Get a Key (one-time, needs a human with an account)

1. Sign in at https://apimercado.com and pick or create an organization.
2. Open https://apimercado.com/discover/capitalenesti/fx-api and press **Enable** (an org admin; it is instant, no approval).
3. Create a Key at https://apimercado.com/dashboard/keys. Keys start with `mk_live_`, are shown once, and spend the organization's balance, so keep them server-side, in an environment variable such as `APIMERCADO_API_KEY`.
4. Top up the balance at https://apimercado.com/dashboard/billing when the Free buffer is not enough.

## 2. Call it

Every request carries the Key in the `X-API-Key` header and goes to the gateway base URL plus the endpoint path from the OpenAPI document:

```sh
curl -i "https://eu-north-1.apimercado.com/v1/@capitalenesti/fx-api/v1/market" \
  -H "X-API-Key: $APIMERCADO_API_KEY"
```

- The gateway strips the Key, authenticates to the provider itself and forwards the request. Response headers `X-Mercado-Cost-Micros`, `X-Mercado-Fee-Micros` and `X-Mercado-Balance-Micros` report what the call cost (integer micro-dollars, 1,000,000 = $1.00).
- Pricing: Free, plus a $0.00005 proxy fee per request. Every charged request costs the same.
- Errors from the gateway itself are JSON `{ "error": { "code", "message" } }` with codes such as `key_not_authorized`, `api_not_enabled`, `balance_exhausted`, `key_spend_cap_reached`, `org_suspended` and `rate_limited`. Upstream errors pass through unchanged.
- Balance check without spending: `GET https://eu-north-1.apimercado.com/v1/account/balance` with the same header.

## 3. TypeScript client (recommended)

`@apimercado/client` wraps openapi-fetch with the gateway URL, the Key header and the gateway error shape. Generate the types once from the OpenAPI document and commit the file:

```sh
npm install @apimercado/client
npx @apimercado/client generate @capitalenesti/fx-api -o fx-api.d.ts
```

```ts
import { createApimercadoClient, readCost } from "@apimercado/client";
import type { paths } from "./fx-api";

const fx_api = createApimercadoClient<paths>({
  provider: "@capitalenesti",
  api: "fx-api",
  apiKey: "mk_live_...", // read it from your environment, keep it server-side
});

const { data, error, response } = await fx_api.GET("/v1/market");
if (error) throw new Error(error.error.code);
console.log(data, readCost(response).costMicros);
```

In CI, `npx @apimercado/client check fx-api.d.ts` exits 1 when the provider changed the spec; regenerate and let the compiler show what moved.

## 4. Any other language

Point an OpenAPI generator (openapi-generator, openapi-python-client, oapi-codegen, ...) at https://eu-north-1.apimercado.com/v1/@capitalenesti/fx-api/openapi.json. Set the server URL to `https://eu-north-1.apimercado.com/v1/@capitalenesti/fx-api/` and send `X-API-Key` on every request. The document already lists the gateway as its server.

## 5. Endpoints

- `GET /v1/market`: Live FX rates
- `GET /v1/compare`: Market vs central-bank rates, side by side
- `GET /v1/convert`: Convert an amount
- `GET /v1/reference`: Latest central-bank reference rates
- `GET /v1/currencies`: Supported currencies
- `GET /v1/market/history`: Daily FX history
- `GET /v1/reference/history`: Daily central-bank reference history
- `GET /v1/market/fluctuation`: FX fluctuation between two dates

Parameters, request bodies and response schemas are in the OpenAPI document above; the human reference is https://apimercado.com/discover/capitalenesti/fx-api?tab=reference.

## More

- Billing, Keys, spend caps and every error code: https://apimercado.com/llms/billing-and-keys.md
- Selling your own API here: https://apimercado.com/llms/publish-an-api.md
- Every API and document on the marketplace: https://apimercado.com/llms.txt
- Provider terms: https://capitalenesti.com/terms
- Provider privacy policy: https://capitalenesti.com/privacy