Skip to main content

satsgate-proxy

Charge AI agents in Lightning and USDC on the same 402. Payments go straight to your wallet. 500 free unlocks a month.

A reverse proxy a merchant runs beside an existing HTTP API. The buyer hits the proxy. The proxy sells the request through Satsgate and forwards only a paid request to the origin. The merchant does not write paywall code.

The proxy is version 0.14.2. It works with core 0.20.3 or later and with gate 0.15.2 or later. Default mode: paywall talks to the Satsgate core paywall (challenge, verify, status, charge, and x402 verify/settle). mode: receipt does not call core and does not use an API key. It checks Satsgate-Receipt with the site secret and forwards a successful check to the origin. The proxy does not sell prepaid balance and does not call the facilitator. Top up on the core with POST /v1/topup/lightning or POST /v1/topup/usdc. On api.satsgate.org a USDC top-up is Base mainnet USDC (a self-hosted core needs SATSGATE_X402_CDP=1; see self-hosting). The hosted gate is a separate program and only sells receipts. Buyer USDC on a proxied paywall route goes to the merchant's verified payTo. In receipt mode the buyer already paid the gate.

Install

pip install satsgate-proxy

or

uvx --env-file .env satsgate-proxy --config satsgate-proxy.yaml

or

docker pull ghcr.io/mike-io-hash/satsgate-proxy:0.14.2

satsgate init --docker writes a compose file for that image. The minor tag is ghcr.io/mike-io-hash/satsgate-proxy:0.14.

USDC payments: Base network only

USDC payments use Base only. Ethereum mainnet, Polygon, Solana, Arbitrum, and any other chain are not accepted.

Network Network id Circle USDC contract Status
Base Sepolia (testnet) eip155:84532 0x036CbD53842c5426634e7929541eC2318f3dCF7e Testing. x402: true without x402_mode, or x402_mode: test, offers only this USDC. It is not a network for real buyers.
Base eip155:8453 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 Live mode (on by default on api.satsgate.org; a self-hosted core needs SATSGATE_X402_CDP=1 and CDP credentials, self-hosting). The 402 offers only this USDC.

Merchants: payTo must be an address you control on Base. Prove it with the same EVM challenge the hosted gate uses. The USDC is paid to that address on the one network the route is in. Try on Base Sepolia with your agent first, then switch the site to live. Buyers: USDC sent on another network will not be accepted. A balance on Ethereum, Polygon, Solana, or Arbitrum does not pay this proxy.

Satsgate never custodies, receives, forwards, or refunds buyer funds. The USDC moves from the buyer to the merchant's payTo. The proxy does not hold a buyer wallet and does not run its own facilitator.

Run it

  1. On the core, with the account key (sg_...), set the Lightning Address that should be paid. Then mint a restricted key. The proxy refuses any key that does not start with sgr_.

    Resources are route:<name> or site. A prefix of route: covers every route-scoped route in the example config. Omit resource_prefix if you also use scope: site.

    curl -s -X POST https://api.satsgate.org/v1/api-keys \
      -H 'Content-Type: application/json' \
      -H 'X-Api-Key: sg_...ACCOUNT_KEY...' \
      -d '{"label":"shop-proxy","resource_prefix":"route:"}'
    
  2. Generate one origin secret and give it to both the proxy and the origin. openssl rand -hex 32 is a good value. Shorter than 16 characters refuses to start. Shorter than 32 logs a warning.

  3. Run satsgate init to write satsgate-proxy.yaml. Set upstream.base_url to the origin (no path, no userinfo). Put the sgr_ key and the origin secret in the environment, not in the file. Upstream credentials, if you inject any, are also environment variables and are never logged.

  4. Add an origin check from snippets/ (FastAPI, Express, or nginx). Reject a missing or bad X-Satsgate-Signature. A client who can reach the origin directly must not skip the paywall. Stock Caddy does not verify HMAC; snippets/Caddyfile only shows a network gate in front of that check.

  5. Start the proxy and do not publish the origin port.

    export SATSGATE_API_KEY='sgr_...'
    export SATSGATE_ORIGIN_SECRET="$(openssl rand -hex 32)"
    uvx --env-file .env satsgate-proxy --config satsgate-proxy.yaml
    

    Buyers use the proxy's published port. GET /healthz is the proxy ({"ok":true,"component":"satsgate-proxy","version":"0.14.2"}). It is not forwarded.

    Startup logs key fp and 12 hex characters. That is the start of SHA-256 of the API key. It is not a prefix of the key, and the key itself is not written to the log.

The image listens as uid 65532.

Receipt mode

Set mode: receipt and a receipt block. There is no core block and no sgr_ key. The buyer pays https://gate.satsgate.org/<site><path>, then calls this proxy with Satsgate-Receipt. A 2xx from the origin commits one use. The origin still sees the HMAC in X-Satsgate-Signature.

mode: receipt
core:
  base_url: https://api.satsgate.org
upstream:
  base_url: https://origin.example
origin:
  secret_env: SATSGATE_ORIGIN_SECRET
receipt:
  site: my-shop
  gate_base: https://gate.satsgate.org
  store: /data/receipts.sqlite3
routes:
  - path: /blog/post
    price_sats: 21

core.base_url is still required by the config parser. Receipt mode does not call it and does not read SATSGATE_API_KEY. price_sats is stored on the route and is not charged here. The buyer already paid the gate.

proxy/snippets/fastapi_receipt.py is the five-line SDK wrapper. proxy/snippets/express_receipt.js checks the same test vectors in tests/fixtures/receipt_vectors.json with Node's crypto module and no npm dependency.

What a buyer sees

An unpaid request gets 402 and:

WWW-Authenticate: L402 macaroon="<standard base64>", invoice="<bolt11>"

macaroon comes before invoice, which is what lnget and Alby fetch402 parse. The JSON body has amount_sats, payment_hash, invoice, invoice_expires_at, max_uses, access_seconds (null when that side is unset), and a hint for the no-preimage path.

A paid retry is Authorization: L402 <macaroon>:<64-hex-preimage> (LSAT is accepted too). The proxy calls POST /v1/paywall/verify with consume=true.

Authorization: L402 <macaroon> with no preimage calls GET /v1/paywall/status/{payment_hash}?consume=true. That is the phone-wallet path: the wallet pays the invoice and does not return a preimage. While the invoice is unpaid the proxy answers 402 payment_pending with Retry-After and does not mint a second invoice. Pending does not consume a use.

A token for another route, a used-up bundle, or an expired pass becomes a fresh 402, not 401, so a standard client can pay again. The body includes reason (token_used_up, token_expired, resource mismatch, and the other core reject strings).

Core 429 (buyer_rate_limited, too_many_open_challenges_for_buyer, rate_limited, too_many_open_challenges) is passed through with Retry-After. A revoked key, a missing payee, an empty prepaid service balance (and no free unlocks left), or a resource outside the key prefix is 502 paywall_unavailable for the buyer. The core error code is logged on the proxy only.

Routes

First match wins. Anything that is not a free path or a route is 404. A path that matches with the wrong method is 405 and does not mint an invoice. OPTIONS is not special: list it, or put the path in free_paths, if a browser must call it.

access Core policy Meaning
per_request max_uses: 1 One payment, one request
uses:N max_uses: N A bundle of N requests (N is 1 to 100000)
pass:<seconds> access_seconds A time pass starting at settlement (1 to 604800 seconds)

scope: route binds the macaroon to route:<name>. A token for one route does not open another. scope: site binds every site-scoped route to the resource site. Those routes must share price_sats and access, because one macaroon has one amount. Startup fails if they differ.

free_paths are forwarded with no challenge. Globs: * is one segment, a trailing /** is that prefix and anything under it (including the prefix). path_regex is a full match. A route has one of path or path_regex.

description is sent as the challenge memo, trimmed to 250 characters.

Price

A new account gets 500 free unlocks per UTC month. After that, each unlock is 2 sats, with a 10% cap. The fee is taken once per payment, and only after the origin returns 2xx. uses:N and pass:<seconds> still bundle requests inside that one payment. pricing.sats_per_credit in an old config is ignored.

The Lightning payment goes to the merchant's payee when the invoice is paid, before the origin runs. A failed origin takes no fee and no use. The buyer retries the same macaroon or signature. Any remedy for that failed origin is between the buyer and the merchant. USDC test payments through this proxy do not use the free unlocks or the prepaid balance.

Buyer IP

When the proxy resolved a real IP, it sends X-Satsgate-Buyer-Ip on challenge create. X-Forwarded-For is used only when the TCP peer is in this proxy's server.trusted_proxies. Otherwise the peer is the buyer. A non-IP peer (the test client, for example) is omitted rather than sent.

Hosted https://api.satsgate.org ignores that header unless the proxy's egress IP is listed in the core's SATSGATE_TRUSTED_PROXIES. The core's Caddyfile also deletes X-Satsgate-Buyer-Ip on public requests, because Caddy is the trusted peer. Until an operator trusts the proxy and stops stripping the header, per-buyer limits do not apply. The merchant's per-client caps still do. Self-hosting the core: set SATSGATE_TRUSTED_PROXIES to the proxy egress IP and let the header through only from that address.

The core stores an HMAC of a truncated address (IPv4 /24, IPv6 /64), not the raw IP.

What the origin receives

When the payment is confirmed, the proxy forwards the original method, raw path, and raw query. The unlock fee and the use are taken only after a 2xx. It does not follow redirects.

Headers added:

Header Value
X-Satsgate-Signature t=<unix>, v1=<hex hmac-sha256>
X-Satsgate-Payment-Hash lowercase payment hash
X-Satsgate-Resource route:<name> or site
X-Satsgate-Paid-Sats sats for this challenge

The signed message is:

{unix}|{METHOD}|{target}|{payment_hash}

target is the raw path, then ? and the raw query string when a query is present. Percent-encoding is kept and the query is not reordered. The method is uppercased. Default skew is 300 seconds (origin.max_skew_seconds).

Client X-Satsgate-* headers are stripped before this, so a buyer cannot forge the signature. Authorization is removed when the scheme is L402 or LSAT. Other schemes, such as Bearer, are forwarded unless inject_headers replaces that name. Hop-by-hop headers are dropped. Accept-Encoding is set to identity.

inject_headers reads the value from value_env. The name cannot be hop-by-hop or X-Satsgate-*. The value is not logged. Startup fails if the variable is unset.

Responses drop Server, Via, X-Powered-By, Location, and Content-Encoding. A 3xx from the origin becomes 502 upstream_redirect with no Location, so an internal host does not leak. The proxy does not follow the redirect.

The response is buffered up to limits.max_response_bytes (default 10 MiB, max 64 MiB). Over that, the buyer gets 502 upstream_response_too_large instead of a truncated 200. A request larger than limits.max_request_bytes (default 1 MiB, max 32 MiB) is 413 before any core call, so it does not mint an invoice or consume a use.

If the origin fails

The proxy confirms the payment first and calls the origin next. The unlock fee is debited from the prepaid service balance (or the monthly free quota) only when that response is 2xx. An origin 4xx or 5xx is passed through with the host headers removed, and nothing is debited. The same macaroon can be retried. If the origin times out, refuses the connection, redirects, or returns a body over the cap, the buyer gets a proxy error with use_spent: false. Do not put internal hostnames in an origin error body.

A route may set x402: true. Without x402_mode, that is test mode (Base Sepolia only). x402_mode: live is Base only, and core rejects it while SATSGATE_X402_CDP is off. x402_mode without x402: true refuses to start. The two networks are never in the same 402. Try on Base Sepolia with your agent first, then switch the site to live. See USDC payments: Base network only. x402 also requires server.public_base, the http:// or https:// origin buyers pay (no path). The account needs a verified EVM payee on Base, the same challenge used by the hosted gate. The 402 then includes PAYMENT-REQUIRED. Test mode is labeled testing: true. PAYMENT-SIGNATURE is verified, the origin is called with X-Satsgate-Paid-Usd-Atomic and no X-Satsgate-Paid-Sats, and settle runs only after a 2xx. PAYMENT-RESPONSE carries success, transaction, network, payer, and tx. An origin 4xx or 5xx does not settle and does not debit. The buyer retries the same PAYMENT-SIGNATURE. Sending both Authorization: L402 and PAYMENT-SIGNATURE is 400 one_rail_only. The proxy never calls the facilitator. The settle call uses the restricted sgr_ key, and core records that key's id on the new ledger debit. The key string is not stored.

A retry of the same token takes another use when the bundle still has one. A per_request token is then token_used_up, and the next call is a new 402. Pending polls do not consume.

Known limitations

  • Hosted core ignores X-Satsgate-Buyer-Ip unless the proxy egress IP is trusted and the edge does not strip the header. Per-buyer limits are then off. Per-client caps remain.

  • The query string is signed only as part of target. An origin that checks the path and ignores the query is not checking what the buyer paid for.

  • Responses are buffered up to the size cap. This is not an unbounded stream. WebSockets are not supported.

  • There is no CORS middleware. A browser preflight needs OPTIONS on the route or a free path.

  • Accept-Encoding is forced to identity. The proxy does not gzip.

  • Location is always removed. An origin that redirects the buyer has to use a URL in the body, or not redirect.

  • An origin failure does not burn the use. A retry after a lost 2xx can take another use if the first charge succeeded and the buyer did not see it. A debited unlock fee is not refunded. There is no idempotency key.

  • Aperture cannot verify Satsgate macaroons. lnget and fetch402 can, using the 402 header and mac:preimage. A phone wallet uses the macaroon-only poll.

  • Replicas of the proxy do not need shared state. Uses, buyer limits, and challenge reuse live in the core database. The core's in-memory challenge rate limit is per core process.

  • The macaroon-only path decodes the macaroon to learn the payment hash. A garbage token becomes a fresh 402.

  • scope: site cannot mix prices. scope: route tokens do not unlock other routes.

  • The restricted key's resource_prefix is a case-sensitive prefix of the resource id the proxy sends.

Contributors' note

From a checkout: pip install -e proxy. Build the image from the repo root with docker build -f proxy/Dockerfile -t satsgate-proxy:0.14.2 ., or docker compose -f proxy/docker-compose.yml up --build.

Mainnet check with a small payment

Use 1 to 21 sats on a test route. Pay from a different wallet than the payee.

  • lnget. The 402 header parses, the macaroon is standard base64, the payment hash is in the L402 identifier, payment succeeds, and the retry is L402 <macaroon>:<preimage>. The origin sees the request and the signature verifies. A tampered path, a tampered payment hash, or a stale t= is rejected.
  • Alby fetch402. The macaroon is treated as opaque. The retry includes the preimage. The macaroon base64 does not contain the substrings L402 or LSAT (the core re-rolls those).
  • Phone wallet. Pay the invoice without a preimage. Retry Authorization: L402 <macaroon> until payment_pending stops and the origin responds. Retry-After is present while pending, and a second invoice is not minted.
  • A used per_request token gets a new 402, not 401.
  • The payee receives the sats when the invoice is paid. The unlock fee is debited from the prepaid service balance (or the monthly free quota) on the first successful delivery only, after the origin returns 2xx. A second use of a bundle does not debit again. A failed origin takes nothing.
  • Against hosted core, the proxy sends X-Satsgate-Buyer-Ip and it is ignored unless that egress IP was added to SATSGATE_TRUSTED_PROXIES. Record what you observed.

Metadata

Release files for satsgate-proxy 0.14.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for satsgate-proxy 0.14.2
File Size Uploaded Provenance Actions
satsgate_proxy-0.14.2.tar.gz 39.3 kB With provenance Details for satsgate_proxy-0.14.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for satsgate-proxy 0.14.2
File Interpreter ABI Platform Actions
satsgate_proxy-0.14.2-py3-none-any.whl Python 3 none any Details for satsgate_proxy-0.14.2-py3-none-any.whl

Total release size: 76.4 kB

Release files / satsgate_proxy-0.14.2.tar.gz

Download URL satsgate_proxy-0.14.2.tar.gz
Size 39.3 kB
Tags Source
SHA-256 checksum
How to use checksums
597c69ae4ae050043aa50f0fda3989b62c23669ef52f94c51f2d65e7d736e10c
BLAKE2b-256 checksum
How to use checksums
435f1a06a29ce2d60546343605329a7947c75d1c173767fa9f9861cf3aca743e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / satsgate_proxy-0.14.2-py3-none-any.whl

Download URL satsgate_proxy-0.14.2-py3-none-any.whl
Size 37.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
868af071cc06033384721adc5a272f6ef1cf7a2b95fd1b384a4bbdb97ce1e699
BLAKE2b-256 checksum
How to use checksums
b98be2e344014c5a44251c42347106f03e76aa8369abb2d5d818182eeccb9f37
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for satsgate-proxy 0.14.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for satsgate_proxy-0.14.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.14.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page