How to list a self-hosted L402 API in the bolthub directory without using the bolthub gateway.

Overview

If you host your own L402 gateway (e.g., using Aperture or a custom implementation), you can list your API in the bolthub directory to reach more consumers. Your API keeps running on your infrastructure; bolthub only provides the discovery layer.

How it works

You submit your API's metadata and gateway URL via the registration API
We verify the gateway is reachable and the L402 flow works
Once approved, your API appears in the bolthub API Hub
Consumers discover your API via the directory, MCP registry, llms.txt, and JSON feed
Traffic goes directly to your gateway; bolthub never proxies or touches the data

Prerequisites

Your gateway must:

Support the L402 protocol (return 402 Payment Required with WWW-Authenticate: L402 macaroon="...", invoice="...")
Be publicly accessible via HTTPS
Serve a discovery endpoint at /.well-known/l402-gateway.json (recommended, for auto-populating endpoint metadata)

Submit a listing

curl -X POST https://api.bolthub.ai/external-listings \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "my-weather-api",
    "name": "My Weather API",
    "description": "Real-time weather data for any location.",
    "tags": ["weather", "data"],
    "gatewayUrl": "https://weather.example.com",
    "contactEmail": "admin@example.com"
  }'

Field	Required	Description
`slug`	Yes	URL-safe identifier (3-63 chars, letters/numbers/hyphens)
`name`	Yes	Display name (max 200 chars)
`description`	No	Short description (max 1000 chars)
`tags`	No	Up to 10 category tags
`gatewayUrl`	Yes	Your L402 gateway base URL
`contactEmail`	Yes	For review communication
`endpoints`	No	Array of endpoint metadata (auto-discovered from `/.well-known/l402-gateway.json` if omitted)

Endpoint metadata

If your gateway doesn't serve /.well-known/l402-gateway.json, provide endpoint metadata manually:

{
  "endpoints": [
    {
      "path": "/v1/weather",
      "method": "GET",
      "title": "Current Weather",
      "description": "Get current weather for a city.",
      "pricingModel": "per_request",
      "priceSats": 5
    }
  ]
}

Check listing status

curl https://api.bolthub.ai/external-listings/my-weather-api/status

Returns:

{
  "slug": "my-weather-api",
  "name": "My Weather API",
  "status": "pending",
  "createdAt": "2026-03-22T12:00:00Z"
}

Statuses: pending (awaiting review), approved (live in directory), rejected, suspended.

Review process

We verify:

The gateway is reachable over HTTPS
The L402 flow works (402 response with valid WWW-Authenticate header)
Invoices are payable and the preimage validates
The API returns meaningful responses after payment
The content complies with the acceptable use policy

Review typically completes within 1-3 business days. We'll email the contact address with the result.

Health monitoring

Once approved, bolthub monitors your gateway with the same health checks used for managed APIs:

Checks run every 5 minutes
Uptime and response time are tracked and displayed in the directory
If your gateway becomes unreachable for an extended period, the listing may be temporarily suspended

Updating your listing

To update metadata after approval, email contact@bolthub.ai with your slug and the changes you'd like to make. Submitting a new listing with the same slug will be rejected since slugs must be unique.

Pricing

External listings are currently free during the beta period. In the future, there may be a small listing fee to cover health monitoring and directory infrastructure costs.

Listing External APIs