Docs — Patchbay

Consumers Agents (L402) Providers API reference

For consumers

Consumers need no account. Pay with Bitcoin Lightning — your payment preimage is your access credential.

Quick start

# 1. Browse providers
curl https://patchbay.space/api/providers

# 2. Send a query — you'll get a 402 back
curl -X POST https://patchbay.space/api/query \
  -H "Content-Type: application/json" \
  -d '{"provider_id": "<id>", "prompt": "Summarize Bitcoin in one sentence"}'

# Response: HTTP 402
# WWW-Authenticate: L402 token="<macaroon>", invoice="lnbc..."
# {
#   "message": "Payment required",
#   "amount_sats": 5,
#   "invoice": "lnbc...",
#   "macaroon": "<macaroon>",
#   "poll_id": "<btcpay-invoice-id>"
# }

# 3. Pay the Lightning invoice with your wallet
# Your wallet reveals the preimage after settlement

# 4. Retry with Authorization header
curl -X POST https://patchbay.space/api/query \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 <macaroon>:<preimage>" \
  -d '{"provider_id": "<id>", "prompt": "Summarize Bitcoin in one sentence"}'

# Response: { "completion": "...", "tokens_used": 45 }

Polling for results (web / mobile wallets)

If your wallet doesn't return the preimage programmatically, use the poll_id from the 402 response to poll for the result after paying:

GET /api/query/invoice-status/<poll_id>

# Returns one of:
# { "status": "pending" }                          — waiting for payment
# { "status": "executing" }                        — payment received, running query
# { "status": "completed", "query_id": "...", ... } — result ready
# { "status": "failed" }                           — query failed after payment

For autonomous agents

Patchbay implements Lightning Labs L402. Agents using Lightning Agent Tools can query Patchbay providers natively with lnget.

With lnget (Lightning Agent Tools)

# lnget handles the 402 → pay → retry flow automatically
lnget -X POST https://patchbay.space/api/query \
  -d '{"provider_id": "<id>", "prompt": "Your query"}'

L402 protocol summary

Request: Standard HTTP POST to /api/query
Challenge: Patchbay returns HTTP 402 with WWW-Authenticate: L402 token="<macaroon>", invoice="lnbc..."
Payment: Agent pays the BOLT11 invoice. Payment reveals a 32-byte preimage. sha256(preimage) == payment_hash
Access: Agent retries with Authorization: L402 <macaroon>:<preimage>
Verify: Patchbay checks sha256(preimage) == payment_hash locally — no database lookup. Forwards to provider.

Macaroon delegation

Parent agents can attenuate a macaroon for sub-agents without contacting Patchbay. This enables multi-agent workflows with spending caps.

For providers

List your open-weight model, data feed, or tool. Earn sats per query, pushed directly to your Lightning address after each completed request. Zero transaction fee — 100% goes to you.

What you need

A public HTTP endpoint you own and operate
A Lightning address for payouts (e.g. you@strike.me, you@getalby.com)
Three routes: GET /health, and either POST /complete (inference) or GET /query (data/tool)

Endpoint specification

GET /health
→ { "status": "ok", "type": "inference|data|tool", "price_per_unit": 5, "price_unit": "sats_per_1k_tokens|sats_per_query", "avg_response_ms": 1400 }

POST /complete  (inference providers)
← { "prompt": "string", "max_tokens": 500, "temperature": 0.7 }
→ { "completion": "string", "tokens_used": 412, "model": "...", "provider_id": "uuid" }

GET /query?q=<query>  (data/tool providers)
→ { "result": ..., "source": "string", "freshness": "ISO8601", "provider_id": "uuid" }

Lightning address compatibility

Patchbay pushes payouts server-side via LNURL-pay. Your Lightning address must be reachable from our servers — this is validated at registration. Strike, Wallet of Satoshi, Alby, and Phoenix all work. Some wallets that block server-side requests will be rejected with a clear error.

Provider accounts

Registration is anonymous by default — you get a provider ID, save it, done. Optionally create an account to manage multiple providers from a dashboard, track earnings across all agents, and build aggregated reputation.

API reference

Method	Path	Description
GET	/api/providers	List active providers. Filter: ?type=inference&sort=price&max_price=10
GET	/api/providers/:id	Provider detail and stats
POST	/api/providers/register	Register a new provider. Validates Lightning address and endpoint health before saving.
POST	/api/query	Submit query. Returns 402 with invoice + macaroon + poll_id if unpaid. Returns result if valid L402 header present.
GET	/api/query/invoice-status/:poll_id	Poll query status by BTCPay invoice ID. Returns pending / executing / completed / failed.
GET	/api/query/:id	Query receipt by query ID
GET	/api/stats	Ecosystem stats (providers, queries, volume)
POST	/api/auth/register	Create provider account { email, password, claim_provider_id? }
POST	/api/auth/login	Log in { email, password } — sets session cookie
POST	/api/auth/logout	Destroy session
GET	/api/auth/me	Returns current session email and accountId

Documentation