Publishing Your API

Discovery endpoints

Every active tenant on bolthub gets automatic discovery endpoints on their gateway subdomain. These require no extra configuration; they are generated from the metadata you enter in the dashboard.

Enriching your metadata

The more metadata you provide, the better your API appears in the directory, agent configs, and OpenAPI specs:

1. Project description and tags: Go to Settings > Directory listing in the dashboard.
2. Endpoint descriptions: On each endpoint's detail page, click Add under "Discovery metadata".
3. Example request/response: Add JSON examples when creating or editing an endpoint. These populate the playground, OpenAPI spec, and agent tool definitions.

For AI agents

How agents discover your API

AI agents (LLMs with tool use, autonomous agents, MCP servers) find your endpoints through:

1. MCP tool config: The API route GET /directory/{slug}/mcp-config returns a JSON config that can be pasted directly into any MCP-compatible client (Cursor, Claude Desktop, OpenClaw). It uses npx @bolthub/mcp-bridge which auto-discovers your endpoints and handles L402 payments. Also available at /.well-known/mcp.json on your gateway domain.

2. L402 discovery file: Agents can fetch /.well-known/l402-gateway.json from your gateway domain to discover all endpoints, pricing, SDK references, and the mcpConfigUrl.

3. OpenAPI spec: The /.well-known/openapi.json endpoint returns a standard OpenAPI 3.1 spec with x-l402-pricing annotations. Importable by Postman, Swagger UI, or LLM agents.

4. Directory API: The public GET https://api.bolthub.ai/directory API returns all active tenants and endpoints with search and tag filtering. Agents can query this programmatically. The human-facing catalog is the API Hub.

MCP bridge (recommended for AI agents)

The fastest way to connect an AI agent is via the MCP bridge. Paste this config into your MCP client (Cursor, Claude Desktop, OpenClaw):

{
  "mcpServers": {
    "acme-api": {
      "command": "npx",
      "args": ["@bolthub/mcp-bridge", "--gateway", "https://acme.gw.bolthub.ai"],
      "env": {
        "LND_REST_HOST": "<your-lnd-rest-url>",
        "LND_MACAROON": "<hex-encoded-admin-macaroon>",
        "BUDGET_SATS": "1000"
      }
    }
  }
}

Wallet options: LND is shown above (recommended, fastest <200ms). Alternatives: LNBITS_URL + LNBITS_ADMIN_KEY, or NWC_URI (easiest but slower). Only one wallet type is needed. BUDGET_SATS is optional and caps total spending per session (remove for unlimited).

The bridge auto-discovers endpoints from the OpenAPI spec, creates MCP tools with proper inputSchema, and handles L402 payment transparently on each tool call.

Agent SDKs

For programmatic integration, bolthub provides SDKs that handle the L402 flow automatically:

TypeScript:

npm install @bolthub/agent

import { L402Client, LndWallet } from "@bolthub/agent";

const client = new L402Client({
  wallet: new LndWallet({ host: "https://lnd:8080", macaroon: "..." }),
  maxPerRequestSats: 100,
  budgetSats: 1000,
});

const resp = await client.get("https://acme.gw.bolthub.ai/v1/weather?city=berlin");
const data = await resp.json();

Python:

pip install bolthub

from bolthub import L402Client, LndWallet

with L402Client(
    wallet=LndWallet(host="https://lnd:8080", macaroon="..."),
    max_per_request_sats=100,
    budget_sats=1000,
) as client:
    resp = client.get("https://acme.gw.bolthub.ai/v1/weather", params={"city": "berlin"})
    data = resp.json()

Configuring agents to use your API

To connect an AI agent to your API:

1. MCP clients: Grab the config from https://api.bolthub.ai/directory/{slug}/mcp-config or the API Hub listing, paste into your client config with your NWC_URI.
2. CLI: Developers can test your API instantly from the terminal with bolthub call {slug} /path, with no code needed.
3. SDK agents: Install the agent SDK (TypeScript or Python), configure a Lightning wallet, and use the gateway URL as the endpoint.
4. The CLI, SDKs, and MCP bridge all handle the 402 → pay → retry flow automatically.

For human developers

Alby browser extension (recommended)

The Alby browser extension provides the smoothest experience for humans interacting with L402-gated APIs:

1. Install Alby from getalby.com.
2. Fund your Alby wallet with sats.
3. Visit the API Playground at https://bolthub.ai/hub/{slug}.
4. Click Pay & Try. Alby automatically detects the 402 response and prompts for payment.
5. After payment, the response appears immediately.

Alby implements the WebLN standard, which the bolthub playground uses to automate the payment flow.

Manual payment (any Lightning wallet)

If you don't have Alby installed, you can use any Lightning wallet:

1. Send a request to the gateway endpoint.
2. The 402 response includes a paymentRequest (bolt11 invoice) in the JSON body.
3. Copy the invoice and pay it with your wallet (Wallet of Satoshi, Phoenix, Zeus, etc.).
4. Extract the preimage from your wallet.
5. Retry the request with Authorization: L402 {macaroon}:{preimage}.

Embeddable badge

Add a badge to your README or website to show that your API is available on bolthub:

[![bolthub](https://api.bolthub.ai/badge/YOUR-SLUG.svg)](https://bolthub.ai/hub/YOUR-SLUG)

<a href="https://bolthub.ai/hub/YOUR-SLUG">
  <img src="https://api.bolthub.ai/badge/YOUR-SLUG.svg" alt="Pay with Lightning on bolthub" />
</a>

Replace YOUR-SLUG with your tenant slug.

Pricing tips

• Start low: 1-10 sats per request is attractive for agents that optimize for cost
• Use per_request for simple APIs, time_pass for high-frequency use cases
• metered (prepaid) works well for compute-heavy APIs where agents want budget control
• Highlight "pay-per-request in sats" in your listing; it's the killer feature for autonomous agents