API Mercado

Everything a developer needs to call paid APIs on API Mercado: how to authenticate, what each call costs, how balances and spend caps work, and how to read every error the gateway can return.

Authenticating requests

Every request carries a Key in the X-API-Key header:

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

Keys are shown once at creation. Keep them server-side; a leaked Key spends your balance. Revoke and re-create from the Keys page — there is no rotation window and no expiry.

Keyless operations

A few operations need no Key: those an API's provider made keyless (marked security: [] in its published spec), and every API's health check path. They are free and not metered, so a browser can call them directly, and the gateway allows 60 of them per minute per IP address and API (keyless_rate_limited beyond that). A Key sent to one is removed and ignored, and the provider does not see who called.

Test requests from an API page

An org admin can send a test request from any API page their organization has enabled ("Try it"). The marketplace sends it through the gateway with your organization's Portal test key, which it creates on the first test and lists on the Keys page. A test request is billed exactly like any other call, from the same balance, and shows up in your requests and spend. You can give the Portal test key a Spend cap or revoke it; the next test creates a new one. Test requests are limited to 10 per minute per organization.

TypeScript client

@apimercado/client wraps openapi-fetch with the gateway URL, the Key header and the gateway error shape. Every API page shows the one-liner that generates its types; it fetches the API's OpenAPI spec from the gateway and writes a .d.ts file you commit:

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

import { createApimercadoClient } from "@apimercado/client";
import type { paths } from "./<api-slug>";

const api = createApimercadoClient<paths>({
  provider: "@<provider-slug>",
  api: "<api-slug>",
  apiKey: "mk_live_...",
});
const { data, error } = await api.GET("/<path>", { params: { query: { ... } } });

Providers can publish new versions and the gateway always serves the current one. The generated file records the spec hash it was built from, so npx @apimercado/client check <api-slug>.d.ts exits 1 in CI when the spec changed; regenerate and let the compiler point at the calls that no longer match.

Base URL shape

All API traffic goes through the marketplace gateway:

https://eu-north-1.apimercado.com/v1/@<provider-slug>/<api-slug>/…

@<provider-slug> is the provider organization's slug, the same name as in the marketplace URL https://apimercado.com/discover/<provider-slug>/<api-slug>. The provider's public id (shown in small print at the bottom of every API page) works in its place, /v1/<provider-public-id>/<api-slug>/…, so URLs copied before slugs existed keep working. Every API page also has a markdown twin at <page>/llms.txt with this whole setup written for a coding agent.

The same gateway hosts one platform endpoint under the reserved public id account:

GET https://eu-north-1.apimercado.com/v1/account/balance

It is authenticated with any of your org's Keys, exactly like an API call, and is never charged.

The balance endpoint

GET /v1/account/balance returns your organization's current billing state. All money fields are integer micro-dollars (1,000,000 = $1.00) with the unit in the field name:

{
  "monthly_balance_micros": 1000000,
  "topup_balance_micros": 12500000,
  "available_balance_micros": 13500000,
  "month_resets_at": "2026-10-01T00:00:00.000Z",
  "key_spend_micros": 750000,
  "key_spend_cap_micros": 5000000,
  "next_expiring_lot": {
    "amount_micros": 12500000,
    "expires_at": "2028-03-01T00:00:00.000Z"
  }
}

monthly_balance_micros — what remains of this Month's Free buffer.
topup_balance_micros — what remains of your purchased Top-up balance.
available_balance_micros — the two combined; a request is denied when it would cost more than this.
month_resets_at — when the Monthly balance resets (the 1st of next Month, UTC).
key_spend_micros — what the calling Key has spent this Month.
key_spend_cap_micros — the calling Key's Spend cap, or null when unlimited.
next_expiring_lot — the soonest-expiring Top-up Lot with its remaining amount, or null when nothing is left to expire.

Response headers

Every gateway response to an API call carries:

X-Mercado-Cost-Micros — the Cost you paid for that request, in micro-dollars.
X-Mercado-Fee-Micros: the proxy fee part of that Cost.
X-Mercado-Raw-Cost-Micros: what the request would cost before the own-API discount. It equals the Cost except on calls to your own APIs.
X-Mercado-Balance-Micros — your Available balance after the charge.
X-Mercado-Resets-At — when the Monthly balance resets.

A rate-limited request returns 429 with a Retry-After header.

What is charged

You pay the request's Cost: the API's Price plus a fixed proxy fee per request ($0.00005). Every price on the Marketplace is the provider's Price alone, marked "+ proxy fee", so an API with a $0 Price shows as Free; the enable dialog spells the fee out. Providers may vary the Price per request within their published Max price, so check X-Mercado-Cost-Micros rather than assuming the list Price. Calls to an API your own organization publishes are discounted 100%: you pay only the proxy fee. Topping up costs a separate percentage fee, added on top of the amount you buy and shown on your Stripe invoice.

A request is charged when the upstream API answers with a 2xx or 4xx status, except 401, 403, and 429: those mean the provider's upstream rejected or throttled the gateway itself, so you are not charged for them. Upstream 5xx responses, timeouts, and every gateway denial are never charged.

Your Key never leaves the gateway. The X-API-Key header is removed before the request is forwarded, and the provider identifies you only by the X-Mercado-Consumer-Id and X-Mercado-Key-Id headers. APIs with a $0 Price still require a Key and Access, and are rate-limited and logged. They earn the Provider nothing, and cost you only the per-request proxy fee.

Balances: Free buffer and Month reset

Spend draws from two pools, Monthly first:

Monthly balance: the Free buffer every organization gets each Month ($1.00). It is a trial the Marketplace funds, so Spend from it earns the Provider nothing. What you do not spend does not carry over: the balance resets on the 1st of each Month at 00:00 UTC.
Top-up balance: prepaid dollars you purchase. It never resets, and is spent only after the Monthly balance is exhausted.

Spend caps

Each Key can carry an optional monthly Spend cap. When the Key's own Spend this Month reaches its cap, only that Key is denied — your other Keys keep working until the org balance runs out. An unset cap means unlimited (bounded by the org balance).

Expiry

Top-up dollars arrive in Lots, and each Lot expires 18 months after it lands. Spend consumes the soonest-expiring Lot first, so nothing goes stale while a later Lot could be spent. The balance endpoint's next_expiring_lot shows what expires next; expired amounts simply leave the Top-up balance.

Error codes

Gateway-generated errors share one body shape:

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

resets_at is the next Month reset (the 1st of next Month, 00:00 UTC). Every denial the billing coprocess generates carries it — even org_suspended, api_not_enabled, and billing_state_unavailable, which are not really about the Month reset — so a client can always say when the error state may change. Only two bodies use null: the gateway's static 403 from its own key authentication (see api_not_enabled), and the balance endpoint's own 401 (key_not_authorized). docs links to the anchor below.

key_not_authorized

401 — returned only by the balance endpoint itself, when the caller identity the gateway forwarded does not check out: the request bypassed the gateway, or the Key's platform metadata is stale. This is not what a revoked Key sees in normal use — the gateway rejects a revoked or unknown Key first, with api_not_enabled below.

api_not_enabled

403 — the Key has no Access to this API. Enable the API for your organization, or widen the Key's Scope, and retry.

A revoked or unknown Key gets this same code: the gateway's own authentication rejects it before any billing check runs, answering HTTP 403 with a static body whose resets_at is null. Revoked Keys are gone for good — mint a new Key on the Keys page.

org_suspended

403 — the organization is suspended. All Keys are denied until the suspension is lifted; contact support.

balance_exhausted

402: the Available balance (Monthly plus Top-up) cannot cover the most the request can cost, which is the API's Max price plus the proxy fee. The check runs before the call reaches the provider, so a request is never half-paid. Top up, or wait for the Month reset in resets_at.

key_spend_cap_reached

402 — this Key reached its monthly Spend cap. Raise the cap, use another Key, or wait for the Month reset in resets_at.

billing_state_unavailable

503 — the billing system could not read your balance, so the gateway failed closed. Nothing was charged. Retry shortly.

keyless_rate_limited

429 — too many calls to an API's keyless operations (see Keyless operations) from one IP address within a minute. Wait for the next minute and retry.

Disputes

Charged incorrectly? From your request log, an org admin can report any charged request within 30 days, with a description of what went wrong. A resolved refund returns the full Cost to your Top-up balance and shows up in your balance history; the provider is deducted the Price portion and the platform forgoes its fee.

Billing and keys