# Loop Gateway

Loop Gateway is an AI infrastructure product built and operated by Loop XXI LLC,
a private holding and capital allocation company.

API base: https://api.loopxxi.com/v1
Purchase: https://gateway.loopxxi.com/buy
Company and current products: https://loopxxi.com/businesses
Support: business@loopxxi.com
Payment discovery: https://api.loopxxi.com/.well-known/agent-payments.json
Skill: https://api.loopxxi.com/skills/loop-gateway/SKILL.md
Agent guide: https://api.loopxxi.com/llms.txt
Example topup body: https://api.loopxxi.com/examples/topup.json
Example chat ping body: https://api.loopxxi.com/examples/chat-ping.json

## Start here

A stranger agent can complete this path without human chat. Use these live
URLs. Do not invent hosts, invoice amounts, model ids, or rail availability.

1. GET https://api.loopxxi.com/.well-known/agent-payments.json
   Read recommended_payment, start_here, and payment_discovery.
   Treat payment_discovery.l402.available as the only L402 availability signal.
2. GET https://api.loopxxi.com/v1/models
   Copy a current model id. Do not rely on a cached catalog.
3. GET https://api.loopxxi.com/v1/pricing
   Read current sat prices. Do not rely on a cached price.
4. POST https://api.loopxxi.com/v1/topup
   Prepaid Lightning (sats) is the preferred path. Minimum 5000 sats.
   Example body: https://api.loopxxi.com/examples/topup.json

   {"amount_sats":5000}

   Optional opaque external_id may be stored on the ledger for the caller's
   bookkeeping (not KYC). The response includes a bearer token and a BOLT11
   invoice.
5. Pay only that invoice after checking it against your own budget.
   Keep the bearer token private. Reading this guide does not pay anything.
   Only your wallet can authorize payment.
6. GET https://api.loopxxi.com/v1/balance
   Header: Authorization: Bearer <token>
   Confirm available credit after settlement. Pending invoices and unknown
   loop_* tokens return HTTP 401 type=authentication_error
   code=unknown_prepaid_token and do not create an account. The response
   includes spend_policy when a cap is set.
7. Optional: PUT https://api.loopxxi.com/v1/spend-policy
   Header: Authorization: Bearer <token>
   {"auto_approve_sats":50}
   Caps each prepaid request before burning credit. Over-cap returns HTTP 402
   type=human_above code=budget_exceeded and does not deduct.
8. POST https://api.loopxxi.com/v1/chat/completions
   Same bearer token. OpenAI-compatible JSON.
   Example body: https://api.loopxxi.com/examples/chat-ping.json
   Replace the model id with one from step 2 if that id is absent.

   {"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"ping"}],"max_tokens":16}

9. GET https://api.loopxxi.com/v1/receipts
   Same bearer token. Append-only settled inference usage (request_id, sats,
   model). This is not a Lightning invoice list and does not prove a top-up
   settled. No raw token or payment preimage is returned. Empty receipts
   after a deposit and before chat are expected.

Credit pays for API usage. It is not a deposit, investment, or interest in
company assets.

## Agent buyer CLI

A stock buyer is served at https://api.loopxxi.com/install/loop-buy.sh
(no company Lightning console, no private-repo clone). The same CLI also
lives in this repository at `cmd/loop-buy`.

Curl-only helper (no Go, no wallet). Default command is discover and pays
nothing:

https://api.loopxxi.com/examples/agent-buy.sh

```
curl -fsSL https://api.loopxxi.com/install/loop-buy.sh -o loop-buy
chmod +x loop-buy
./loop-buy first
```

`first` is the first-paid-chat walkthrough: discover → prepaid topup →
wait for settlement → chat ping → GET /v1/receipts. It does not pay the
invoice. Pay from your own wallet. Keep the bearer token private.

```
./loop-buy discover -json
./loop-buy topup -amount-sats 5000 -json
./loop-buy balance -json -token "$LOOP_GATEWAY_TOKEN"
./loop-buy chat -json -message "hello" -token "$LOOP_GATEWAY_TOKEN"
./loop-buy receipts -json -token "$LOOP_GATEWAY_TOKEN"
```

Repo checkout alternative: `go run ./cmd/loop-buy first`.

`discover` reads https://api.loopxxi.com/.well-known/agent-payments.json
(or `{base-url}/.well-known/agent-payments.json`). L402 availability is the
`payment_discovery.l402.available` field in that document — do not assume it.
Preferred first purchase is prepaid POST /v1/topup. Pay the printed BOLT11 from
your own wallet; `loop-buy` does not embed a wallet and does not pay.
Amounts below the product minimum fail closed. Prefer `-json` so an agent can
parse stdout. Keep the bearer token private.

For pay-per-call L402 (only after discovery advertises the rail), use a stock
OpenAI-shaped payer. Do not put node credentials, connection strings, or
preimages in this repository:

- lnget (go install / lightning-agent-tools) — generic POST L402
- @bolthub/pay L402Client — npm HTTP L402 client
- @lightninglabs/l402-ai / L402sdk — Vercel AI / LangChain
- @getalby/mcp fetch_l402 — MCP tool; not an OpenAI baseURL drop-in

## Lightning Agent Tools

Machine-readable skill: https://api.loopxxi.com/skills/loop-gateway/SKILL.md
Packet: docs/LIGHTNING_AGENT_TOOLS.md in this repository.
Discovery: https://api.loopxxi.com/.well-known/agent-payments.json

Preferred path is prepaid POST /v1/topup (min 5000 sats), pay the BOLT11
from your own wallet, then POST /v1/chat/completions with Bearer.
lightning-mcp-server talks to YOUR Lightning node, not Loop inference.

Per-call L402 via lnget / BoltHub L402Client is only valid when
payment_discovery.l402.available is true. Preview with lnget --no-pay
before paying. Do not invent lnget flags. Do not hardcode L402 as on or off.

```
curl -sS -X POST https://api.loopxxi.com/v1/topup \
  -H "Content-Type: application/json" \
  -d '{"amount_sats":5000}'

lnget --no-pay --json --max-cost 1000 \
  -X POST --content-type application/json \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}' \
  https://api.loopxxi.com/v1/chat/completions
```

## Optional L402

Prepaid POST https://api.loopxxi.com/v1/topup is the preferred path.

Per-call L402 is optional. Use it only when payment_discovery.l402.available
is true on https://api.loopxxi.com/.well-known/agent-payments.json.

If available is true, an unauthenticated POST to
https://api.loopxxi.com/v1/chat/completions may return HTTP 402 with a
Lightning challenge. Read payment_discovery.l402.min_amount_sats before
paying.

If available is false, do not treat unauthenticated chat as a pay-per-request
path. That request may return HTTP 503 with rail_unavailable / l402_disabled.
Stay on prepaid topup.

Do not hardcode L402 as on or off.

## Stock L402 payers

Prepaid POST https://api.loopxxi.com/v1/topup is the preferred first sale.
L402 is optional when payment_discovery.l402.available is true on
https://api.loopxxi.com/.well-known/agent-payments.json.

Stock clients that can pay a live L402 challenge (no secrets in this list):

- lnget
- @bolthub/pay
- @lightninglabs/l402-ai
- Alby fetch_l402

Pay only an invoice you have checked against your own budget.

## Other rails

This onboarding path is prepaid Lightning (sats). Other keys under
payment_discovery are not a substitute for this sequence. Do not send bitcoin
to an address inferred from source code, historical memory, or an unrelated
wallet. Read the live discovery document before paying any optional rail.

## Spend policy (prepaid)

After top-up, set a per-request soft budget on the same bearer token:

```
curl -X PUT https://api.loopxxi.com/v1/spend-policy \
  -H "Authorization: Bearer loop_<token>" \
  -H "Content-Type: application/json" \
  -d '{"auto_approve_sats":50}'
```

- omitted / null auto_approve_sats: no per-request cap (default)
- 0: refuse all paid inference
- N: refuse when estimated cost exceeds N sats

Over-budget response is HTTP 402 with type=human_above and code=budget_exceeded.
No sats are deducted. Raise the cap or send a cheaper request. This is fail-closed.

GET /v1/spend-policy and GET /v1/balance report the current cap.
GET /v1/receipts returns append-only settled inference usage for this token
(not Lightning invoices; no raw token or payment preimage).
Unknown prepaid bearers on those routes and the prepaid chat path return HTTP 401
code=unknown_prepaid_token and do not create an account. The token must have a
settled top-up. Missing Authorization returns code=missing_prepaid_token.

Daily rolling budgets are not enforced yet. Do not treat daily_budget_sats as a live limit.

## Errors and budgets

Check both HTTP status and the structured error. Do not retry a payment blindly.
For 401/402, inspect credentials, balance, and spend-policy type/code
(human_above / budget_exceeded is not the same as insufficient_funds).
For 429, back off. Retry transient 5xx responses at most three times with backoff.
Never increase spend limits automatically.

## Scope

The supported inference route documented here is
https://api.loopxxi.com/v1/chat/completions.
Health is https://api.loopxxi.com/health and includes
commit, `l402_disabled` (effective pay-per-request kill), and `preferred_rail`.
Health alone does not prove that a paid request or settlement succeeds.
Current company catalog: https://loopxxi.com/products.json