Skip to main content

Setting Up Your Proxy

This guide walks you through every step required to take an existing API and make it discoverable and payable by AI agents using the L402 protocol. You do not need to change any code in your API.

Who this is for: API providers who want AI agents to find their API, understand what it does, and pay per request in Bitcoin over Lightning. If you are an agent developer looking to consume an existing L402 API, see MCP Quickstart instead.

What you will have at the end: A live proxy URL that enforces per-request Lightning payments, a public manifest that AI agents can read to discover your endpoints and pricing, and an optional listing in the public L402 registry.

Table of Contents​

  1. Prerequisites
  2. Step 1 — Create a proxy
  3. Step 2 — Set a default price
  4. Step 3 — Configure the manifest
  5. Step 4 — Add your endpoints
  6. Step 5 — Review pricing per endpoint
  7. Step 6 — Publish and share
  8. Troubleshooting

Prerequisites​

  • An active Lightning Enable subscription (Agentic Commerce — Individual at $99/mo or Agentic Commerce — Business at $299/mo). Both include a 30-day free trial.
  • A payment provider account — Strike (recommended) or OpenNode — with your API key saved in Dashboard → Settings.
  • An API you own or have permission to proxy. The creation form rejects raw IP-address hosts, internal hostnames (.local, .internal, .svc.cluster.local), and non-standard ports (only 80 and 443 are accepted) — so for most production APIs on standard HTTPS this isn't a constraint you'll think about. The runtime forwarding path additionally blocks targets that resolve to private/internal IP addresses, regardless of port.
Your API needs no changes

The proxy wraps your API from the outside. Your API never knows that payments are happening. It receives normal HTTP requests and returns normal HTTP responses.

Step 1 — Create a proxy​

Open the dashboard at api.lightningenable.com/dashboard and click Create Proxy to launch the guided wizard.

Name​

Pick a name your customers and agents will recognize. This appears in the proxy list and in the public manifest.

Good example: OpenWeather Current Conditions Avoid: proxy1, test, my api

Proxy ID​

Lightning Enable auto-generates a Proxy ID from your name. When you create through the dashboard wizard, the name is lower-cased, spaces become hyphens, and an 8-character hex suffix is appended to keep it unique. For OpenWeather Current Conditions you would get something like openweather-current-conditions-a1b2c3d4. The Proxy ID becomes part of the URL where your proxy lives:

https://api.lightningenable.com/l402/proxy/openweather-current-conditions-a1b2c3d4/

AI agents and clients send their requests to this URL. The proxy forwards them to your actual API.

You cannot change the Proxy ID after creation.

Target URL​

This is the base URL of the real API you are proxying. Every request that arrives at your proxy URL is forwarded to this address.

Your proxy URLGets forwarded to
/l402/proxy/openweather-current-conditions-a1b2c3d4/current?city=miamihttps://api.openweathermap.org/data/2.5/current?city=miami

The dashboard wizard accepts any well-formed https:// or http:// URL. Two stricter sets of rules apply on top of that:

  • At runtime, on every forwarded request: targets resolving to private, internal, loopback, or link-local IP addresses are blocked. This is a security check that runs regardless of how the proxy was created.
  • When creating via the REST API (POST /api/proxy): in addition to the runtime block above, the API also rejects raw IP-address hosts, non-standard ports, and known internal hostnames (.local, .internal, .svc.cluster.local, etc.).

For most production APIs (public HTTPS endpoints on standard ports) you will satisfy both layers without thinking about them.

Handling APIs that require authentication​

Lightning Enable does not store or inject upstream API credentials. The proxy forwards client headers transparently and strips the incoming Authorization header (LE consumes that one for the L402 payment check). If the API you are proxying requires its own auth — an API key, bearer token, signed request, mTLS — that authentication has to happen between your infrastructure and your upstream, not through us.

Recommended pattern: a thin auth-injecting front in your own infrastructure.

Stand up a small reverse proxy or edge worker on a subdomain you control (for example, monetized-api.your-domain.com) that:

  1. Accepts unauthenticated incoming requests from Lightning Enable
  2. Adds your upstream API key / bearer / signature
  3. Forwards to your real API

Then set your Lightning Enable proxy's Target URL to that subdomain instead of your raw API. Your credentials stay in your environment, you can rotate them without touching Lightning Enable, and LE never sees them.

Example — nginx:

location / {
    proxy_pass https://api.your-upstream.com;
    proxy_set_header Authorization "Bearer YOUR_UPSTREAM_KEY";
    proxy_set_header Host api.your-upstream.com;
}

Adapt the same pattern to whatever edge-proxy / API-gateway / serverless function your stack already uses — the only requirement is that LE-bound traffic gets an Authorization header attached before it reaches your real upstream.

If your API has no auth (it's already public and you want to add Lightning monetization in front of it), skip this step — just set Target URL to your API directly.

Deeper integration available

For commercial APIs where running a separate auth-injecting proxy isn't a fit, Native L402 integration is now available. Your API validates L402 tokens directly using Lightning Enable's hosted producer endpoints, and Lightning Enable acts as a payment broker that never sees your traffic. Drop-in middleware packages for Express (Node) and ASP.NET Core (.NET) ship today; FastAPI (Python) and Go (net/http) are in development.

Step 2 — Set a default price​

After creating the proxy you land on the proxy detail page. Open the Pricing tab.

The Default Fallback Price is the number of satoshis charged for any request that does not match a per-endpoint rule. Think of it as the "everything else" price.

If you charge the same amount for every endpoint, set this once and you are done. If you want different prices for different endpoints, set a reasonable base price here and then configure per-endpoint overrides in Step 5.

How to choose a starting price:

The wizard shows a live USD preview next to whatever number you enter (at current rates 100 sats is roughly 6 cents USD, though Bitcoin price moves continuously). Use this table as a rough starting point:

Use caseSuggested starting price
Public data (weather, sports scores)10–50 sats
Enrichment APIs (address validation, geocoding)50–200 sats
AI inference (summarization, classification)200–1000 sats
Proprietary data feedsSet based on your commercial price

Enter the number in the Price per Request (sats) field and click Save.

Step 3 — Configure the manifest​

The manifest is a structured JSON file that lives at a public URL on your proxy. AI agents read it to learn what your API does, what it costs, and how to pay.

Without a manifest, your proxy is invisible to agents — they have no way to discover it or know what it costs. With a manifest, your API can appear in the public L402 registry, agents can discover your endpoints automatically, and they can pay per call and use your API autonomously.

Enable Manifest​

Turn on the Enable Manifest switch. This publishes the manifest file at:

https://api.lightningenable.com/l402/proxy/{proxyId}/.well-known/l402-manifest.json

Any agent that knows your proxy URL can fetch this file.

The proxy also adds a Link header to every 402 response pointing to this file, so agents that encounter your proxy for the first time can auto-discover the manifest without knowing the URL in advance.

Service Description​

One or two plain-language sentences describing what your API does.

This text appears in:

  • Registry search results (when agents or developers search the public registry by keyword)
  • The top of the manifest JSON (agents read this to decide if your API is relevant to their current task)

Write it for an AI agent, not a marketing audience. Concrete is better than superlative.

Good example: Returns current weather conditions and 7-day forecasts for any US city or zip code. Data refreshes every 15 minutes from NWS and NOAA sources.

Avoid: The best weather API — fast, reliable, and affordable!

Contact Email​

A public email address for integration questions. Visible in the manifest. Human developers who want to use your API may reach out here. This field is optional.

Documentation URL​

A link to your full API documentation — the human-readable docs you already have. AI agents may follow this URL to get endpoint-level detail beyond what the manifest captures. Optional but recommended if you have docs.

Terms of Service URL​

A link to your terms of service or usage policy. Some agents check for a ToS URL before paying and require acceptance before they proceed. Optional.

Save Settings​

Click Save Settings after filling in any of these fields. The manifest file updates immediately.

Step 4 — Add your endpoints​

The endpoints table tells agents exactly which paths exist, what each one does, and what it costs. Without endpoints listed, the manifest advertises your default price but gives agents no detail about individual operations.

You have two options for populating this table.

Option A — Scan API (recommended if your API has an OpenAPI spec)​

If your API serves an OpenAPI (Swagger) specification, the scanner can read it and import all your endpoints automatically.

What Scan API does:

  1. Fetches your API's OpenAPI spec (either from a URL you provide, or by probing standard locations on your target URL).
  2. Parses every endpoint: path, HTTP method, summary, description, request schema, response schema.
  3. Imports them into the manifest endpoint table with your default price applied to each one.

Standard locations the scanner probes automatically:

When you leave "Spec URL (optional)" blank, the scanner tries these paths on your target URL:

  • /openapi.json
  • /swagger/v1/swagger.json
  • /swagger.json
  • /api-docs
  • /v3/api-docs
  • /.well-known/openapi.json

If your spec is at one of these locations, click Scan API with the field empty. If the scan succeeds, you will see a confirmation message listing how many endpoints were imported.

If auto-scan fails:

The most common reason is that your spec is served at a non-standard URL. In that case, paste the full URL to your spec in the Spec URL field and click Scan API again.

Example: https://api.example.com/v2/docs/swagger.json

If the scan still fails, your API may not publish an OpenAPI spec. Use Option B instead.

What happens after a successful scan:

Discovered endpoints are added to the table with:

  • Your default fallback price set on each one
  • L402 payment enabled
  • The endpoint visible in the public manifest

You can adjust any of these settings per-endpoint after import.

Scans are idempotent — running Scan API a second time only imports endpoints not already in the table. Existing entries are not overwritten.

Option B — Add Manual​

Click Add Manual to open a form where you enter a single endpoint by hand.

Use this when:

  • Your API does not have an OpenAPI spec
  • You only want to expose a subset of endpoints
  • You want to add endpoints with custom descriptions that the spec does not include

Fields to fill in:

  • Path — the URL path, starting with / (e.g., /v1/forecast)
  • HTTP Method — GET, POST, PUT, PATCH, or DELETE
  • Summary — one sentence describing what this endpoint does (shown in the manifest)
  • Description — optional longer explanation (agents may read this for context)
  • Base Price (sats) — sats per request for this specific endpoint

The dialog also exposes optional fields you can leave at their defaults:

  • Pricing Model — Per-request (default), Free, or other models for unusual pricing
  • Base Price (USD cents) — set this if you want to price in USD; the manifest converts to sats live at the current rate
  • Visible in Manifest — toggle off to hide an internal endpoint
  • L402 Required — toggle off if this endpoint should be free / not gated
  • Rate Limits — per-minute and per-day caps that agents are expected to respect

Step 5 — Review pricing per endpoint​

After populating the endpoint table, review the Price column on each row.

Each row shows the price that the public manifest advertises to agents for that endpoint. This is the amount the agent expects to pay when it reads your manifest.

Default vs per-endpoint prices​

There are two layers of pricing:

Default Fallback Price (top of the Pricing tab): Charged when a request arrives at your proxy but does not match any per-endpoint rule. This is the safety net for paths you have not configured individually.

Per-endpoint prices (in the table): The price listed in the manifest for a specific endpoint. When an agent pays and sends a request to that path, this is the amount the agent was told to expect.

Both values must agree with what the proxy actually charges at runtime. See the Sync section below for how to fix disagreements.

Editing per-endpoint pricing​

Click the edit icon on any row to change the price, description, summary, or visibility for that endpoint.

FieldEffect
Price (sats)What the manifest advertises for this endpoint
VisibleWhether this endpoint appears in the public manifest
L402Whether payment is required for this endpoint

The Sync chip​

When a sats-priced endpoint's manifest price differs from what the proxy would actually charge at runtime, a yellow chip appears on that row:

manifest 100 / runtime 50 — Sync

This means the manifest is advertising 100 sats but calls to this path will actually cost 50 sats. An agent that reads the manifest and pays the advertised price may be over- or under-charged. This is confusing and can break agents that verify charges.

What causes this: The most common cause is that a wildcard pricing rule (like /v1/* at 50 sats) applies to this path at runtime, but the endpoint was later configured in the manifest with a different price.

What Sync does: Clicking the chip and confirming writes an exact-path pricing rule that matches only this endpoint's path, at the manifest price, with the highest priority. The wildcard rule remains — it still covers paths not in the table — but this path is now explicitly set to match the manifest.

After syncing, the chip disappears from that row.

When the chip does NOT appear (even if the numbers differ):

  • Free endpoints (Pricing Model = Free) — they have no sats price to mirror, so Sync would have nothing meaningful to write
  • USD-priced endpoints (Base Price (USD cents) set) — the manifest converts USD to sats live at request time using the current BTC rate, so the runtime sats number is expected to drift. Sync is intentionally skipped here
  • Endpoints with Base Price (sats) = 0 — same reason as Free; nothing positive to mirror
  • Config-driven proxies — runtime pricing lives in App Service config, not the database, so the dashboard can't compute a runtime number to compare against

For these cases, if you want the runtime to match the manifest you'll need to address it through the appropriate channel: switch the endpoint to a sats-priced Per Request model and re-save, or update the App Service config directly for a config-driven proxy.

Step 6 — Publish and share​

List in Public Registry​

Turn on the List in Public Registry switch to include your proxy in the public L402 API registry at:

https://api.lightningenable.com/api/manifests/registry

The registry is where AI agents and developers search for available L402 APIs by keyword or category. Once listed, your API appears in results matching your name, description, and service description.

Requirements:

  • Enable Manifest must be on
  • Service Description is strongly recommended — it is the text that appears in search results and determines whether agents consider your API relevant

The three URLs in Preview & Share​

The Preview & Share section at the bottom of the Pricing tab shows three URLs.

JSON URL — the machine-readable manifest:

/l402/proxy/{proxyId}/.well-known/l402-manifest.json

This is what AI agents fetch. Share it with developers who want to write code that uses your API. Open it in a browser to verify everything looks right before announcing your API.

Markdown URL — a human-readable preview of the same information at /api/proxy/{proxyId}/manifest.md. This endpoint is authenticated — it requires your merchant API key and is intended for previewing or exporting the manifest as Markdown, not for public sharing. To share the manifest externally, give people the JSON URL above (which is public) or copy the rendered Markdown into your own README / docs.

Registry URL:

https://api.lightningenable.com/api/manifests/registry

This is the registry itself, not a URL specific to your proxy. Share it when pointing someone to the broader ecosystem of L402 APIs — for example, in a blog post or announcement. Agents use this URL to search for available APIs by keyword.

Troubleshooting​

"Could not find an OpenAPI/Swagger specification at any well-known location"​

This message appears when Scan API probes all standard locations and finds nothing. It does not mean your API is broken — it means your API does not expose an OpenAPI spec at a standard path, or the spec is protected behind authentication.

Try this:

  1. Check your API docs for a link to your Swagger or OpenAPI spec.
  2. Paste the full URL to your spec in the Spec URL field and click Scan API again.
  3. If your spec requires authentication, your API provider will need to either expose a public copy or you will need to add endpoints manually using Add Manual.

Common non-standard spec paths:

  • https://your-api.com/docs/openapi.yaml
  • https://your-api.com/api/swagger
  • https://your-api.com/specification.json

"Legacy wildcard pricing rules detected"​

This warning appears when the proxy has any active pricing rule that uses a wildcard pattern (a PathPattern containing *, like /v1/*). The warning is informational — it surfaces the precedence behavior so you understand what Sync does.

The warning by itself does NOT mean anything is wrong. It only means: if a manifest endpoint's price differs from what the wildcard would charge for that path, the Sync chip will write a more specific exact-path rule that wins over the wildcard.

If you see yellow Sync chips on rows: click Sync on each one to write an exact-path rule for that endpoint at its manifest price. The wildcard remains and still applies to paths the table doesn't cover. After every sats-priced row has either matched the wildcard or been explicitly synced, the chips disappear (and the warning becomes informational only).

If you see the warning but no chips: your manifest endpoints either already match the wildcard, are Free/USD-priced (where the chip is intentionally suppressed), or there are no entries to compare against. No action needed.

If you intended the wildcard price to apply to everything: update the per-endpoint prices in the table to match the wildcard price, then sync each sats-priced row.

The manifest shows no endpoints​

If you enabled the manifest but the endpoint table is empty, the JSON manifest will have an empty endpoints array. Agents can still discover your proxy and pay for requests using the default price, but they will not know what individual paths exist.

Populate the endpoint table using Scan API or Add Manual. Endpoints with Visible turned on appear in the manifest; endpoints with it turned off do not.

An endpoint I added does not appear in the manifest​

Check that:

  • The Visible toggle on that row is on (green)
  • Enable Manifest is turned on at the top of the Pricing tab
  • You clicked Save Settings after enabling the manifest

My proxy is active but agents get a 404​

Verify that the Target URL in the Overview tab is correct and reachable. A 404 from the proxy itself means the proxy could not find your API at that URL. A 404 from your API means the path the agent requested does not exist on your API.

Next Steps​