How to onboard an API that agents actually want to pay for

Listing an API on bolthub takes minutes. Making it an endpoint that agents keep coming back to (and paying for) takes a little thought. Your customers are no longer humans clicking through a signup flow. They are autonomous programs that read your schema, price the call, pay a Lightning invoice, parse the response, and move on, all in a couple of seconds with no one watching. That changes what "a good API" means.

Here is what separates an endpoint that earns from one that gets tried once and dropped.

Data quality is the product

An agent cannot squint at your response and guess what you meant. It either parses cleanly or it fails. Optimize for the machine reader:

• •Return structured, typed data. JSON with stable field names and consistent types. Do not return a number as a string in one call and a number in the next. Do not omit a field when it is null; return null.
• •Keep the schema stable. Agents cache your shape. A silent breaking change strands every workflow built on you. Version in the path (/v1/...) and add fields rather than repurposing them.
• •Make errors machine-actionable. A body like {"error": "rate_limited", "retry_after_s": 30} tells an agent exactly what to do. A 200 wrapping an HTML error page tells it nothing and costs it a paid call.
• •Be deterministic where you can. If the same request returns the same answer, agents can cache it. bolthub sets X-Cache: HIT/MISS on cacheable GETs; lean into it for reference data.
• •Say what you return. Fill in your OpenAPI spec and parameter descriptions. Agents discover you through /.well-known/l402-gateway.json and your OpenAPI document; the better those read, the more often you get called correctly on the first try.

Pick the pricing model that matches the work

bolthub gives you five hosted models. The choice decides how agents budget for you and how often they can afford to call.

A good rule: if a caller will make many requests in a short span, do not make them pay a fresh Lightning invoice every time. The payment itself has latency. Price for the workload, not just the call.

Response size and time compound

Every extra kilobyte and every extra 100ms is multiplied by the number of calls in an agent's loop.

• •Keep payloads tight. Return what was asked for; offer a fields= parameter for fat resources. On a per-KB endpoint a bloated response is literally more expensive for your buyer.
• •Paginate large collections instead of returning everything.
• •Answer fast. Agents set timeouts, and a slow, flaky origin also loses you money: if your origin fails to deliver, the buyer is not charged.
• •Support cacheable responses for anything that does not change per call.

Design for how agents interact

Most agents now reach you through an MCP server that exposes the whole bolthub marketplace as tools. They will search_apis, read get_api_details, call preview_cost to see the price, and only then call_api. Two things make that smooth: a clear, self-describing schema, and idempotency where it matters so a retried call is safe.

The new building blocks worth designing for

We recently shipped a set of agent-native capabilities. You benefit from most of them for free, but a couple change how you should think about your endpoint.

• •Prepaid bundles. If agents hit your endpoint in a loop, offer bundle sizes (say 100 or 500 calls at a small discount). A buyer pays once and spends the block down with no further Lightning round-trips, which makes you dramatically cheaper to use at scale.
• •Delegation. A buyer can mint scoped child credentials for sub-agents, so one purchaser may become many concurrent callers sharing one paid grant. Design assuming concurrency; the usage limits are enforced server-side, so you are protected.
• •Your status codes now carry billing meaning. This is the one behavior change worth internalizing. Return 5xx, 429, or 408 and bolthub treats it as "you delivered nothing": the buyer's proof stays spendable and their retry is free (no sats move back over Lightning; the sats you already received stay yours until the retry consumes them). Return a real 4xx and the call stays paid. So use your status codes honestly. A 500 when you meant 400 hands your buyer a free retry loop; a 200 wrapping an error denies them the free retry they should have gotten.
• •Receipts. Every paid call produces a verifiable receipt from the Lightning preimage. Nothing to build; it makes you easier to trust and to expense.

Origin protection is not optional

Here is the mistake that quietly costs sellers money. Your hosted gateway is a public URL that collects payment and forwards to your origin. If someone finds your origin's real address, they can skip the gateway and skip the payment entirely. All your careful pricing means nothing if the origin is open to the internet.

Lock it down:

• •Verify the gateway signature. Every forwarded request carries an X-Gateway-Signature (HMAC) or X-Gateway-Secret. Reject anything without a valid one. This is the single most important step, and the SDKs make it one function call.
• •Restrict by source IP to the gateway's addresses as a second layer.
• •Rotate your secret periodically.

Do this on day one. An endpoint that takes payment at the front door and leaves the back door open is not a paid API; it is a free API with extra steps.

A quick pre-launch checklist

- Structured, typed, stable JSON; null over missing fields.

- Machine-readable errors with actionable fields.

- Honest status codes (5xx/429/408 retryable, 4xx a real answer).

- Versioned path; additive schema changes only.

- Pricing model matched to the workload; bundle sizes for loop-heavy endpoints.

- Tight, fast, paginated, cacheable responses.

- Full OpenAPI spec and parameter descriptions.

- Origin protection verified before you take a single sat.

Get these right and you are not just listed on bolthub. You are the endpoint an agent picks, pays, and calls again.

Publish your API →