satsgate-proxy
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.1. 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. While the operator CDP switch is on, a USDC top-up is Base mainnet USDC only. 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
uvx --env-file .env satsgate-proxy --config satsgate-proxy.yaml
docker pull ghcr.io/mike-io-hash/satsgate-proxy:0.14.1
From a checkout: pip install -e proxy.
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 |
x402_mode: live. Available only when the operator sets SATSGATE_X402_CDP=1 and both CDP credentials. 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
-
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 withsgr_.Resources are
route:<name>orsite. A prefix ofroute:covers every route-scoped route in the example config. Omitresource_prefixif you also usescope: 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:"}'
-
Generate one origin secret and give it to both the proxy and the origin.
openssl rand -hex 32is a good value. Shorter than 16 characters refuses to start. Shorter than 32 logs a warning. -
Copy
satsgate-proxy.example.yamltosatsgate-proxy.yaml. Setupstream.base_urlto the origin (no path, no userinfo). Put thesgr_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. -
Add an origin check from
snippets/(FastAPI, Express, or nginx). Reject a missing or badX-Satsgate-Signature. A client who can reach the origin directly must not skip the paywall. Stock Caddy does not verify HMAC;snippets/Caddyfileonly shows a network gate in front of that check. -
Start the proxy and do not publish the origin port.
export SATSGATE_API_KEY='sgr_...' export SATSGATE_ORIGIN_SECRET="$(openssl rand -hex 32)" docker compose -f proxy/docker-compose.yml up --build
Buyers use the proxy's published port.
GET /healthzis the proxy ({"ok":true,"component":"satsgate-proxy","version":"0.14.1"}). It is not forwarded.Startup logs
key fpand 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.
From a checkout: pip install -e proxy.
The image listens as uid 65532. Build it from the repo root: docker build -f proxy/Dockerfile -t satsgate-proxy:0.14.1 .
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 credit balance, 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 credit 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. A credit is taken 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-Ipunless 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
OPTIONSon the route or a free path. Accept-Encodingis forced toidentity. The proxy does not gzip.Locationis 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. Credits are never refunded. There is no idempotency key.
- Aperture cannot verify satsgate macaroons. lnget and
fetch402can, using the 402 header andmac: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: sitecannot mix prices.scope: routetokens do not unlock other routes.- The restricted key's
resource_prefixis a case-sensitive prefix of the resource id the proxy sends.
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 stalet=is rejected. - Alby
fetch402. The macaroon is treated as opaque. The retry includes the preimage. The macaroon base64 does not contain the substringsL402orLSAT(the core re-rolls those). - Phone wallet. Pay the invoice without a preimage. Retry
Authorization: L402 <macaroon>untilpayment_pendingstops and the origin responds.Retry-Afteris present while pending, and a second invoice is not minted. - A used
per_requesttoken gets a new 402, not 401. - The payee receives the sats when the invoice is paid. The account loses one credit on the first successful delivery only, after the origin returns 2xx. A second use of a bundle does not charge another credit. A failed origin takes no credit.
- Against hosted core, the proxy sends
X-Satsgate-Buyer-Ipand it is ignored unless that egress IP was added toSATSGATE_TRUSTED_PROXIES. Record what you observed.
Metadata
Release files for satsgate-proxy 0.14.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| satsgate_proxy-0.14.1.tar.gz | 39.1 kB | With provenance | Details for satsgate_proxy-0.14.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| satsgate_proxy-0.14.1-py3-none-any.whl | Python 3 | none | any | Details for satsgate_proxy-0.14.1-py3-none-any.whl |
Total release size: 76.1 kB
Release files / satsgate_proxy-0.14.1.tar.gz
| Download URL | satsgate_proxy-0.14.1.tar.gz |
|---|---|
| Size | 39.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a75cd1236de7f04ed40351c1dda44a3f869db4e503008206b5011b02863c1fa1
|
|
BLAKE2b-256 checksum How to use checksums |
306a5a7945ace6ba6b937c921c446946b83e290c13ef3ce64a7e7c2089d90a7b
|
| 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 logRelease files / satsgate_proxy-0.14.1-py3-none-any.whl
| Download URL | satsgate_proxy-0.14.1-py3-none-any.whl |
|---|---|
| Size | 37.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
13194fcfd7d5264f4106b32c5cc7615c3967b00bc7f918cf3bb6af2f15961366
|
|
BLAKE2b-256 checksum How to use checksums |
b6b3102f56df0efe35c0d83926a863252721313de205cabc7e74b19a282f7a27
|
| 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 logSecurity for satsgate-proxy 0.14.1
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.
Attestation for satsgate_proxy-0.14.1.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 logA 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.