Publish an API

How to get an existing HTTP API ready to sell on API Mercado. It is written so you can hand it to a coding agent working in your API's repository: each section says what to change in the code and what to set in the portal.

How a request flows

A consumer calls the gateway with their Key:

https://eu-north-1.apimercado.com/v1/<provider-public-id>/<api-slug>/<path>

The gateway checks their balance, strips their X-API-Key, adds your upstream credential and the platform headers, and forwards the request to your upstream base URL plus <path>. When your response comes back, the gateway charges the consumer, removes your pricing header, and returns the response with their Cost attached. You never handle keys, billing, or rate limits yourself.

1. Publish an OpenAPI spec at a URL

The spec is imported from a URL, never pasted, and fetched again every hour.

• OpenAPI 3.x, in JSON or YAML, at most 1 MB.
• info.version is required. When it changes, the new version is released automatically, so bump it whenever the API changes.
• servers[0].url is used as the upstream base URL if you do not enter one. Consumers never see it: the published spec shows the gateway URL instead, and your own security schemes are removed, since consumers authenticate with their Key.
• The URL must be publicly reachable over http or https. Addresses on private networks, loopback, and link-local ranges are rejected, for both the spec URL and the upstream base URL.

Most frameworks can serve a generated spec (for example /openapi.json). Serve it from the same deployment as the API so it never drifts from the code.

2. Accept only gateway traffic

In the portal, open your API's Authorization tab and add the credential the gateway should send to your upstream: an API key header, a bearer token, basic auth, or a custom header. It is encrypted at rest and never shown to consumers.

In your code, reject any request that does not carry that credential. Answer 401 or 403: consumers are never charged for those statuses, so a misconfigured credential cannot bill anyone.

The gateway also sends these headers on every request:

Trust them only on requests that passed your credential check.

3. Add a health endpoint

Publishing requires a passing health check. Add a cheap endpoint (for example GET /health) that answers a fixed status without calling paid dependencies. In Settings you choose the path, the method (GET, HEAD, or POST), the expected status code, and a timeout between 500 and 30,000 ms.

4. Pricing and the adjustable cost

You set two numbers in Settings:

• Price: what one charged request pays you, from $0 up to $1,000. You receive it in full.
• Max price: the most a single request can cost. It must be at least the Price. Consumers see the range from Price to Max price on your API page.

Consumers pay the Price plus a fixed proxy fee of $0.00005 per request. Which responses are charged is explained in What is charged.

Charging a different amount per request

When requests are not all worth the same (results returned, pages rendered, tokens generated), set the X-Mercado-Price-Micros header on your response. Its value is the Price for that one request, as an integer number of micro-dollars (1,000,000 micro-dollars = $1.00).

The gateway removes the header before the response reaches the consumer, and adds X-Mercado-Cost-Micros with what they actually paid (your amount plus the proxy fee). The header only matters on responses that are charged at all.

Rules for your code:

• Send whole numbers only. 1500 works; 1500.5, $0.0015, and 1.5e3 fall back to the Price from Settings.
• Compute it from the work the request actually did, after the work is done.
• Raise the Max price in Settings before your code starts sending higher values, or they are silently capped.
• If every request costs the same, do not send the header, and leave Max price equal to Price.

Example: Price $0.001 (1000 micro-dollars) as the floor, Max price $0.01, and $0.0005 per result returned.

Node (Express):

const PRICE_PER_RESULT_MICROS = 500;
const MIN_PRICE_MICROS = 1000;

app.get('/search', async (req, res) => {
  const results = await search(req.query.q);
  const price = Math.max(MIN_PRICE_MICROS, results.length * PRICE_PER_RESULT_MICROS);
  res.set('X-Mercado-Price-Micros', String(price));
  res.json({ results });
});

Hono:

app.get('/search', async (c) => {
  const results = await search(c.req.query('q'));
  const price = Math.max(1000, results.length * 500);
  c.header('X-Mercado-Price-Micros', String(price));
  return c.json({ results });
});

Python (FastAPI):

@app.get("/search")
async def search_route(q: str, response: Response):
    results = await search(q)
    price = max(1000, len(results) * 500)
    response.headers["X-Mercado-Price-Micros"] = str(price)
    return {"results": results}

Describe the pricing rule in your API's description or in each operation's description, so consumers know what a call will cost before they make it.

What you earn

You earn the Price of every charged request once the consumer pays from purchased dollars. Requests paid from a consumer's monthly $1.00 Free buffer are a trial funded by the Marketplace and earn nothing. Calls from your own organization are charged normally and never earn.

5. Go-live checklist

Every item must pass before the API can go public. The Publish tab shows the same list with a link to fix each one.

1. An OpenAPI spec version is uploaded.
2. The spec is imported from a URL.
3. Your legal name, contact email, and country are set.
4. The current Provider Agreement is accepted.
5. Terms of Service and Privacy Policy URLs are set.
6. The health check is enabled and passing.
7. At least one successful call went through the gateway with your own Key while the API is Private. Enable your own API, create a Key, and call it.

A summary and a category are recommended, so consumers can find the API.

Prompt for your coding agent

Paste this into a coding agent opened in your API's repository:

Read https://apimercado.com/llms/publish-an-api.md and prepare this repo to be published on API Mercado, including per-request pricing.