For agents

This page is the reference an agent reads first. Every page on this site is also markdown: append index.md to its URL, or send Accept: text/markdown. The site map is /llms.txt, and /llms-full.txt holds every page in one file.

Find an API

Search the catalog with a goal or keywords:

GET https://apimercado.com/discover/llms.txt?q=<keywords>

The answer is markdown, best match first. Words are OR-ed and ranked, so describe the goal and try two or three variants. Every public API is also listed in the catalog’s own llms.txt.

Read an API

Each API page has two machine-readable twins, both readable without a Key:

URL	What it is
https://apimercado.com/discover/<provider-slug>/<api-slug>/llms.txt	The setup guide: gateway base URL, pricing, how to get a Key, a typed client, every endpoint.
https://apimercado.com/discover/<provider-slug>/<api-slug>/openapi.json	The OpenAPI document as consumers see it, with the gateway as its server.

MCP server

The catalog is also a remote MCP server, read-only and without sign-in, over Streamable HTTP:

https://apimercado.com/mcp

To add it to Claude Code:

claude mcp add --transport http apimercado https://apimercado.com/mcp

In Claude.ai or Claude Desktop, add the URL as a custom connector under Settings > Connectors.

Tool	Returns
search_apis({ q, category? })	Catalog search results, the same markdown as /discover/llms.txt?q=.
get_api_guide({ provider, api })	An API’s setup guide, the same markdown as its llms.txt.
get_openapi({ provider, api })	An API’s OpenAPI document as JSON, with the gateway as its server.

provider and api are the two slugs in a result’s link, /discover/<provider-slug>/<api-slug>. An unknown API returns a tool error. Calling an API still needs a Key, as described below. Tool names are stable: renaming one is a breaking change in the Changelog.

Call an API

Every call goes through the gateway with a Key in the X-API-Key header:

curl -H "X-API-Key: $APIMERCADO_API_KEY" "https://eu-north-1.apimercado.com/v1/@<provider-slug>/<api-slug>/<path>"

• A Key starts with mk_live_ and needs a human: an org admin enables the API on its page and creates the Key there, or on the Keys page.
• Keys stay server-side, in an environment variable. A Key spends its organization’s balance, so it never belongs in a browser, a repository or a prompt. A Spend cap on the Key bounds what it can spend in a Month.
• Response headers report what each call cost (X-Mercado-Cost-Micros, in micro-dollars) and the balance left. See Response headers.
• To bound what one call may cost, send X-Mercado-Max-Cost-Micros (an integer in micro-dollars, proxy fee included). When the called operation’s price cap plus the proxy fee is above it, the gateway answers 402 max_cost_exceeded before the provider is called and charges nothing; otherwise the provider receives the value and can scale the work to it. See Max cost.

TypeScript client

@apimercado/client generates types from an API’s OpenAPI document and wraps the gateway URL, the Key header and the error shape:

npm install @apimercado/client
npx @apimercado/client generate @<provider-slug>/<api-slug> -o <api-slug>.d.ts

npx @apimercado/client check <api-slug>.d.ts exits 1 when the provider has changed the spec since the file was generated. For any other language, point an OpenAPI generator at the API’s openapi.json.

The same package sets a Max cost on every call (maxCostMicros), reads the billing headers (readCost), types the balance and request lookup (createAccountClient), and, for providers, the Provider API (createProviderClient).

Errors

Errors the gateway generates share one envelope:

{
  "error": {
    "code": "balance_exhausted",
    "message": "The organization balance is exhausted.",
    "resets_at": "2026-11-01T00:00:00.000Z",
    "docs": "https://docs.apimercado.com/billing-and-keys/#balance_exhausted"
  }
}

Branch on code, never on message. docs links to that code’s section under Error codes, which says what caused it and what to do. Errors from the provider’s own API pass through unchanged.

Provider API

A provider’s servers and CI use the Provider API to work with their own APIs without a portal login. It lives at https://admin-api.apimercado.com under /v1/provider/*:

Operation	What it does
GET /v1/provider/whoami	Checks a key: its id, organization and scopes.
POST /v1/provider/apis/{apiId}/refresh	Re-reads an API’s spec from its URL now.
POST /v1/provider/requests/{requestId}/settle	Sets the final price of a deferred request.
GET /v1/provider/requests/{requestId}	Returns a deferred request’s hold and status.

Authenticate with a provider API key, Authorization: Bearer mpk_.... An org admin creates it under Settings > Provider API; it is shown once. It cannot call APIs or sign in to the portal. Its errors are { "error": "<code>: <detail>" }. The details are in Provider API. To get an API ready to publish, read Publish an API.

Watch for breaking changes

API Mercado is in beta: features and fees may change. Every Release is listed in the Changelog, newest first, and changes that need action are under a “Breaking changes” heading in that Release’s entry. To watch it, fetch https://docs.apimercado.com/changelog/index.md now and then and look for that heading in entries newer than the last one you read.