satsgate-mcp 0.13.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. satsgate_mcp-0.13.0/LICENSE +201 -0
  2. satsgate_mcp-0.13.0/PKG-INFO +232 -0
  3. satsgate_mcp-0.13.0/README.md +209 -0
  4. satsgate_mcp-0.13.0/pyproject.toml +41 -0
  5. satsgate_mcp-0.13.0/setup.cfg +4 -0
  6. satsgate_mcp-0.13.0/src/satsgate_mcp/__init__.py +3 -0
  7. satsgate_mcp-0.13.0/src/satsgate_mcp/__main__.py +20 -0
  8. satsgate_mcp-0.13.0/src/satsgate_mcp/bolt11.py +118 -0
  9. satsgate_mcp-0.13.0/src/satsgate_mcp/budget.py +88 -0
  10. satsgate_mcp-0.13.0/src/satsgate_mcp/buyer.py +1167 -0
  11. satsgate_mcp-0.13.0/src/satsgate_mcp/challenge.py +393 -0
  12. satsgate_mcp-0.13.0/src/satsgate_mcp/clients.py +50 -0
  13. satsgate_mcp-0.13.0/src/satsgate_mcp/config.py +135 -0
  14. satsgate_mcp-0.13.0/src/satsgate_mcp/manual.py +372 -0
  15. satsgate_mcp-0.13.0/src/satsgate_mcp/nwc.py +41 -0
  16. satsgate_mcp-0.13.0/src/satsgate_mcp/qr.py +20 -0
  17. satsgate_mcp-0.13.0/src/satsgate_mcp/redact.py +46 -0
  18. satsgate_mcp-0.13.0/src/satsgate_mcp/registry.py +232 -0
  19. satsgate_mcp-0.13.0/src/satsgate_mcp/server.py +154 -0
  20. satsgate_mcp-0.13.0/src/satsgate_mcp/store.py +233 -0
  21. satsgate_mcp-0.13.0/src/satsgate_mcp/urls.py +48 -0
  22. satsgate_mcp-0.13.0/src/satsgate_mcp/x402.py +560 -0
  23. satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/PKG-INFO +232 -0
  24. satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/SOURCES.txt +26 -0
  25. satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/dependency_links.txt +1 -0
  26. satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/entry_points.txt +3 -0
  27. satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/requires.txt +5 -0
  28. satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/top_level.txt +1 -0
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1,232 @@
1
+ Metadata-Version: 2.4
2
+ Name: satsgate-mcp
3
+ Version: 0.13.0
4
+ Summary: Charge AI agents in Lightning and USDC on the same 402. 500 free unlocks per UTC month. Buyer-side MCP server. Cobrale a agentes de IA en Lightning y USDC, en el mismo 402.
5
+ License-Expression: Apache-2.0
6
+ Project-URL: Homepage, https://github.com/Mike-io-hash/satsgate
7
+ Project-URL: Issues, https://github.com/Mike-io-hash/satsgate/issues
8
+ Project-URL: Changelog, https://github.com/Mike-io-hash/satsgate/blob/main/CHANGELOG.md
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.10
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Requires-Python: >=3.10
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: mcp<3,>=2.0
18
+ Requires-Dist: httpx>=0.27.0
19
+ Requires-Dist: pymacaroons>=0.13.0
20
+ Requires-Dist: segno>=1.6.0
21
+ Requires-Dist: nostr-sdk<0.46,>=0.45.0
22
+ Dynamic: license-file
23
+
24
+ # satsgate-mcp
25
+
26
+ A buyer-side MCP server. An agent (Claude Desktop, Cursor, or any stdio MCP client) can see the price of a Satsgate-paywalled URL, pay it, and read the response.
27
+
28
+ This package is version **0.13.0**. It talks to whatever URL returned the 402. Works with core 0.20.3 or later. The self-hosted proxy is **0.14.1**. Works with gate 0.15.2 or later. On a gate host (`SATSGATE_MCP_GATE_HOSTS`, default `gate.satsgate.org`) `pay_and_fetch` pays the gate, keeps the receipt, and repeats the request at `redeem_url` when that host is on the allowlist. The receipt is not logged. A stored receipt is returned by `challenge_status`. The body sent to a gate host is not forwarded. A 402 may offer Lightning, x402 (USDC on Base), or both. One 402 lists one USDC network. `list_sites` includes a public route priced only in USD, with `price_currency` and `price_usd_atomic`. This process cannot buy Satsgate credits, and it does not hold a buyer private key. An account tops up on the core with `POST /v1/topup/lightning` or `POST /v1/topup/usdc`. While `SATSGATE_X402_CDP` is on, USDC top-up is Base mainnet only. While it is off, it is Base Sepolia. The USDC path is not an MCP tool.
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ pip install satsgate-mcp
34
+ ```
35
+
36
+ The console script is `satsgate-mcp`.
37
+
38
+ From a checkout: `pip install -e mcp`.
39
+
40
+ ## USDC payments: Base network only
41
+
42
+ USDC payments use Base only. Ethereum mainnet, Polygon, Solana, Arbitrum, and any other chain are not accepted.
43
+
44
+ | Network | Network id | Circle USDC contract | Status |
45
+ | --- | --- | --- | --- |
46
+ | Base Sepolia (testnet) | `eip155:84532` | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://sepolia.basescan.org/token/0x036CbD53842c5426634e7929541eC2318f3dCF7e) | Testing. A site in test mode offers only this USDC. It is not a network for real buyers. |
47
+ | Base | `eip155:8453` | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) | Live when the operator sets `SATSGATE_X402_CDP=1` and both CDP credentials. A site in live mode offers only this USDC. |
48
+
49
+ Merchants: `payTo` must be an address you control on Base. The USDC is paid to that address on the one network that site 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 a Satsgate 402.
50
+
51
+ Satsgate never custodies, receives, forwards, or refunds buyer funds. The USDC moves from the buyer to the merchant's `payTo`. Satsgate does not hold a buyer wallet and does not run its own facilitator.
52
+
53
+ This MCP server does not send that USDC and does not hold a key. It shows the network and the amount printed on the 402. An accept on any other network is reported and is not payable. A test-mode 402 is Base Sepolia and is labeled testing. A live-mode 402 is Base. This server can describe either. It still does not sign. A wallet that signs uses the `extra` on that 402. Base Sepolia is name `USDC`. Base is name `USD Coin`. This server does not substitute a name.
54
+
55
+ `list_sites` reads `GET /v1/sites` on `SATSGATE_MCP_CORE_URL` (default `https://api.satsgate.org`). That is the public directory: approved sites that opted in. Set `SATSGATE_MCP_REGISTRY` only to replace it with a JSON file or another URL.
56
+
57
+ ## Run it
58
+
59
+ ```bash
60
+ pip install satsgate-mcp
61
+ export SATSGATE_MCP_DATA_DIR="$HOME/.local/share/satsgate-mcp"
62
+ export SATSGATE_MCP_MAX_PAYMENT_SATS=100
63
+ export SATSGATE_MCP_DAILY_MAX_SATS=500
64
+ satsgate-mcp
65
+ ```
66
+
67
+ `satsgate-mcp` speaks MCP over stdio. Logs go to stderr. From a checkout: `pip install -e mcp`.
68
+
69
+ Claude Desktop or Cursor config:
70
+
71
+ ```json
72
+ {
73
+ "mcpServers": {
74
+ "satsgate": {
75
+ "command": "satsgate-mcp",
76
+ "env": {
77
+ "SATSGATE_MCP_DATA_DIR": "/absolute/path/to/satsgate-mcp-data",
78
+ "SATSGATE_MCP_MAX_PAYMENT_SATS": "100",
79
+ "SATSGATE_MCP_DAILY_MAX_SATS": "500",
80
+ "SATSGATE_MCP_MAX_PAYMENT_USD": "1",
81
+ "SATSGATE_MCP_DAILY_MAX_USD": "5"
82
+ }
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ Put `SATSGATE_MCP_NWC_URI` in that env block when you want the agent to pay. Do not paste the URI into the chat. The tools have no argument for it, and it is not logged.
89
+
90
+ ## Tools
91
+
92
+ | Tool | What it does |
93
+ | --- | --- |
94
+ | `discover` | GET (or POST) the URL with no payment. Reads `WWW-Authenticate: L402 macaroon="...", invoice="..."` and the JSON body: `amount_sats`, `max_uses`, `access_seconds`, `invoice_expires_at`. When the 402 offers x402, also reads `PAYMENT-REQUIRED` and the JSON `x402` mirror. |
95
+ | `quote` | Same request, plus a short sentence. |
96
+ | `pay_and_fetch` | `mode=human` (default) returns the Lightning invoice, a text QR, and a PNG when that rail is offered. `mode=nwc` pays Lightning from the environment wallet if the sats caps allow it, then fetches. An optional `payment_signature` forwards a `PAYMENT-SIGNATURE` the caller already has. This process does not sign. |
97
+ | `check_payment` | One poll of a human payment. `payment_pending` means call it again after `retry_after_seconds`. On settlement it fetches the URL with `Authorization: L402 <macaroon>` and no preimage. |
98
+ | `credits_balance` | `GET /v1/balance` with the optional restricted key. An `sgr_` key can read the balance. It cannot top up. Nothing is written. |
99
+ | `challenge_status` | `GET /v1/paywall/status/{payment_hash}?consume=false`. The macaroon is the one stored locally. It is not a tool argument. |
100
+ | `list_sites` | Approved, listed sites from `GET /v1/sites`. Routes keep `price_sats` when that is an integer, and `price_currency` plus `price_usd_atomic` when the route is priced in USD. A file or other URL in `SATSGATE_MCP_REGISTRY` replaces the directory. |
101
+
102
+ A token that still has uses, or whose pass has not ended, is sent again and is not paid again. The macaroon stays in the local sqlite file. It is not returned to the model.
103
+
104
+ If the server answers a stored token with a fresh 402 `token_used_up` or `token_expired`, the tool returns the new quote and does not pay. Call `pay_and_fetch` again to pay that invoice. Set `SATSGATE_MCP_AUTO_PAY=1` to pay that replacement inside the same call, and only when it is inside both caps.
105
+
106
+ `discover` followed within 60 seconds by `pay_and_fetch` for the same URL reuses that invoice instead of minting another one.
107
+
108
+ ## Human pay, no preimage
109
+
110
+ 1. `pay_and_fetch` with `mode=human`.
111
+ 2. Pay the BOLT11 invoice in any wallet. You do not need the preimage.
112
+ 3. `check_payment` with the `payment_hash`.
113
+
114
+ When `SATSGATE_MCP_API_KEY` is set and the challenge names a resource, `check_payment` first calls core `GET /v1/paywall/status/{payment_hash}` with the macaroon and `consume=false`. That is the LUD-21 poll. Unpaid is `status=pending`. Settled, it retries the original URL with the macaroon. The proxy then consumes one use and forwards.
115
+
116
+ Without a key, `check_payment` retries the URL directly. The proxy does the core poll. Pending is HTTP 402 `payment_pending` and does not mint a second invoice.
117
+
118
+ If the payee wallet does not advertise LUD-21 (Wallet of Satoshi), core returns `preimage_required`. Human poll cannot finish. Use `mode=nwc`, or a wallet that shows the preimage.
119
+
120
+ ## x402 (USDC on Base)
121
+
122
+ A site may enable only Lightning, only x402, or both. x402 is off until the merchant turns it on. If core has no fresh BTC/USD median, a sats-priced route's 402 offers only its primary currency. This client shows the 402 as it arrived. It does not invent a USDC price, and it does not round the amount again. The server already locked the quote and rounded it up (minimum 0.001 USDC, or 1 sat on Lightning).
123
+
124
+ `PAYMENT-REQUIRED` is base64 of an x402 v2 document. Each accept is returned with `scheme`, `network`, `asset`, `amount_atomic`, `amount_display` (`10000` is `0.01 USDC`), `pay_to`, `resource_url`, and `expires_at` when the body states one. The header is canonical. If the JSON mirror disagrees, the header values are the ones shown. A missing header with only the mirror present is shown with `canonical: false` and is not payable. Expiry is not computed from `maxTimeoutSeconds`.
125
+
126
+ Supported accepts are Circle USDC on Base Sepolia (`eip155:84532`, the network tests and the current gate use) and Circle USDC on Base (`eip155:8453`). Any other network or asset is listed with `supported: false`. The tool does not raise. A `PAYMENT-SIGNATURE` is forwarded only when every accept is one of those two and inside both USD caps, because the signature may select any accept.
127
+
128
+ This server holds no buyer private key. It does not sign, submit, custody, forward, or refund USDC, and it does not run a facilitator. Satsgate does not either. When `payable` is true, the `payment` object is what an external wallet has to pay. Call `pay_and_fetch` again with `payment_signature` set to that `PAYMENT-SIGNATURE`: one line, no spaces, at most 8192 bytes. Do not send an L402 `Authorization` on the same request. An empty `payment_signature` stays on the Lightning path.
129
+
130
+ The gate or proxy runs verify, then the origin, then settle. A 2xx returns the body and, when the server sent one, `payment_response` with `success`, `transaction`, `tx`, `network`, and `payer`. The raw header is not returned. If the origin fails, nothing is settled and no merchant credit is taken. The tool says so, sets `retry_same_payment_signature` true, and the same header can be sent again while the offer is valid. `bad_signature` and `expired` need a new signature. `x402_replay` was already settled, so sending it again does not fetch the resource. `x402_rejected` is either a failed verify (new signature) or a failed settle of a header you already sent (retry that same header). Local USD spend is recorded only after a 2xx, and the signature is not written to sqlite and is not logged.
131
+
132
+ Both `SATSGATE_MCP_MAX_PAYMENT_USD` and `SATSGATE_MCP_DAILY_MAX_USD` must be set or the tool will not proceed. `0` refuses every positive amount. Unset or over the cap, `discover` still returns the parsed requirements with `payable: false`. `pay_and_fetch` then refuses and does not send the header. The sats caps do not apply to USDC. An over-cap USDC amount does not block paying the Lightning invoice on the same 402.
133
+
134
+ `mode=human` still returns the invoice and QR when Lightning is offered, so a person can pay from any phone wallet and the agent continues with `check_payment`. A dual 402 returns that invoice and the x402 block together. An x402-only URL has no invoice. NWC is not required for it. An `sgr_` key is still only for `challenge_status` and `credits_balance`. The x402 tools do not call a route that needs an account key.
135
+
136
+ ## NWC
137
+
138
+ `SATSGATE_MCP_NWC_URI` is `nostr+walletconnect://...?relay=...&secret=...`. Both caps must be set or every NWC payment is refused. `0` refuses every positive amount. The spend ledger is `satsgate-mcp.sqlite` in the data dir (mode 0600). A payment is recorded when the wallet returns a preimage, including when the origin then fails. Sats are not refunded.
139
+
140
+ ## Environment
141
+
142
+ | Variable | Meaning |
143
+ | --- | --- |
144
+ | `SATSGATE_MCP_NWC_URI` | Wallet connection. Never a tool argument. Unset means NWC is off. |
145
+ | `SATSGATE_MCP_MAX_PAYMENT_SATS` | Most sats one invoice may cost. Required for NWC. |
146
+ | `SATSGATE_MCP_DAILY_MAX_SATS` | Most sats in any rolling 24 hours. Required for NWC. |
147
+ | `SATSGATE_MCP_MAX_PAYMENT_USD` | Most USDC one accept may cost, as a decimal with at most 6 places (`0.01` is 10000 atomic). Required before a `PAYMENT-SIGNATURE` is forwarded. Independent of the sats cap. |
148
+ | `SATSGATE_MCP_DAILY_MAX_USD` | Most USDC in any rolling 24 hours, same decimal form. Required together with the per-payment cap. |
149
+ | `SATSGATE_MCP_AUTO_PAY` | `1` pays a `token_used_up` / `token_expired` replacement inside the same call, if the caps allow it. Default off. |
150
+ | `SATSGATE_MCP_DATA_DIR` | sqlite directory. Default `~/.local/share/satsgate-mcp`. |
151
+ | `SATSGATE_MCP_CORE_URL` | Core base URL. Default `https://api.satsgate.org`. |
152
+ | `SATSGATE_MCP_API_KEY` | Optional `sgr_` key for the two read-only tools. An account `sg_` key is ignored. |
153
+ | `SATSGATE_MCP_URL_ALLOWLIST` | Comma-separated hosts. `*.example.com` allows subdomains. Empty allows any http(s) host. |
154
+ | `SATSGATE_MCP_HTTP_TIMEOUT` | Seconds, default 20. |
155
+ | `SATSGATE_MCP_MAX_BODY_BYTES` | Response cap, default 1000000. |
156
+ | `SATSGATE_MCP_REGISTRY` | Optional. A JSON file or http(s) URL that replaces the public directory. Unset uses `{SATSGATE_MCP_CORE_URL}/v1/sites`. |
157
+
158
+ Only `http` and `https` URLs are requested. Userinfo is rejected. Redirects are not followed. Requests time out.
159
+
160
+ ## Registry file
161
+
162
+ ```json
163
+ {
164
+ "sites": [
165
+ {"name": "example", "url": "https://shop.example/blog/post", "description": "One article"}
166
+ ]
167
+ }
168
+ ```
169
+
170
+ Leave `SATSGATE_MCP_REGISTRY` unset to use the public directory. The response uses `hosted_registry: true`, `slug`, `url` (the gate URL, `https://gate.satsgate.org/<slug>/` when that is the configured public base), `description`, and `routes` with `price_sats` when that price is an integer, plus `price_currency` and `price_usd_atomic` when the route is priced in USD. A USD-only route is kept. `list_sites` follows up to five pages. Each request waits at most 5 seconds, and never longer than `SATSGATE_MCP_HTTP_TIMEOUT`. A timeout, a connection failure, or a non-200 body returns `ok: false` and an empty `sites` list. It does not raise.
171
+
172
+ A row that includes `status` other than `approved`, or `listed` other than true, is skipped. The public endpoint does not return those rows. A local file that omits both fields is your own list.
173
+
174
+ If `SATSGATE_MCP_URL_ALLOWLIST` is set, the directory host has to be on it. The default host is the host of `SATSGATE_MCP_CORE_URL`.
175
+
176
+ ## Mainnet check from your machine
177
+
178
+ Use a route priced at 1 to 21 sats. Pay from a wallet that is not the payee.
179
+
180
+ ### Human QR
181
+
182
+ ```bash
183
+ pip install satsgate-mcp
184
+ export SATSGATE_MCP_DATA_DIR="$HOME/.local/share/satsgate-mcp"
185
+ satsgate-mcp-pay 'https://YOUR-PROXY/blog/post'
186
+ ```
187
+
188
+ The process prints the amount, the invoice, a text QR, and the path of a PNG under the data dir. Pay that invoice. It keeps polling until the invoice expires. The wait starts at 2 seconds and grows toward 15 seconds. `--polls N` and `--timeout SECONDS` are optional caps. Status lines start with a UTC timestamp. No NWC URI is required. The macaroon is not printed.
189
+
190
+ If it stops before the origin body is printed, it prints a command you can paste. That command resumes the same `payment_hash` from the data dir and does not mint a new invoice:
191
+
192
+ ```bash
193
+ SATSGATE_MCP_DATA_DIR="$HOME/.local/share/satsgate-mcp" satsgate-mcp-pay --resume PAYMENT_HASH
194
+ ```
195
+
196
+ If it stays on `payment_pending` until expiry, the invoice was unpaid or the payee has no LUD-21 `verify` URL. Wallet of Satoshi needs the NWC path below.
197
+
198
+ ### NWC, optional
199
+
200
+ ```bash
201
+ export SATSGATE_MCP_NWC_URI='nostr+walletconnect://...'
202
+ export SATSGATE_MCP_MAX_PAYMENT_SATS=50
203
+ export SATSGATE_MCP_DAILY_MAX_SATS=200
204
+ satsgate-mcp-pay --nwc 'https://YOUR-PROXY/blog/post'
205
+ ```
206
+
207
+ ### lnget and fetch402 against the proxy
208
+
209
+ These clients pay the 402 header themselves. They are not the MCP server. CI checks the header shape and does not pay. On your machine:
210
+
211
+ The header-shape script lives in the repo. The contributor section below runs it.
212
+
213
+ That request does not pay. It prints whether the lnget and fetch402 parsers accept the header. Then, to spend sats:
214
+
215
+ ```bash
216
+ lnget 'https://YOUR-PROXY/blog/post'
217
+ npm install @getalby/lightning-tools
218
+ export NWC_CONNECTION_STRING='nostr+walletconnect://...'
219
+ node mcp/scripts/fetch402.mjs 'https://YOUR-PROXY/blog/post'
220
+ ```
221
+
222
+ lnget and fetch402 retry with `Authorization: L402 <macaroon>:<preimage>`. A phone wallet that does not return a preimage pays the same invoice and retries with `Authorization: L402 <macaroon>` only. Pending must stay on that invoice (`402 payment_pending`), not a second one.
223
+
224
+ Confirm the origin saw the request and `X-Satsgate-Signature` verifies. A tampered path or a stale `t=` is rejected by the origin snippet.
225
+
226
+ ## For contributors
227
+
228
+ From a checkout: `PYTHONPATH=mcp/src python -m satsgate_mcp`.
229
+
230
+ ```bash
231
+ PYTHONPATH=mcp/src python mcp/scripts/mainnet_l402_clients.py 'https://YOUR-PROXY/blog/post'
232
+ ```
@@ -0,0 +1,209 @@
1
+ # satsgate-mcp
2
+
3
+ A buyer-side MCP server. An agent (Claude Desktop, Cursor, or any stdio MCP client) can see the price of a Satsgate-paywalled URL, pay it, and read the response.
4
+
5
+ This package is version **0.13.0**. It talks to whatever URL returned the 402. Works with core 0.20.3 or later. The self-hosted proxy is **0.14.1**. Works with gate 0.15.2 or later. On a gate host (`SATSGATE_MCP_GATE_HOSTS`, default `gate.satsgate.org`) `pay_and_fetch` pays the gate, keeps the receipt, and repeats the request at `redeem_url` when that host is on the allowlist. The receipt is not logged. A stored receipt is returned by `challenge_status`. The body sent to a gate host is not forwarded. A 402 may offer Lightning, x402 (USDC on Base), or both. One 402 lists one USDC network. `list_sites` includes a public route priced only in USD, with `price_currency` and `price_usd_atomic`. This process cannot buy Satsgate credits, and it does not hold a buyer private key. An account tops up on the core with `POST /v1/topup/lightning` or `POST /v1/topup/usdc`. While `SATSGATE_X402_CDP` is on, USDC top-up is Base mainnet only. While it is off, it is Base Sepolia. The USDC path is not an MCP tool.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pip install satsgate-mcp
11
+ ```
12
+
13
+ The console script is `satsgate-mcp`.
14
+
15
+ From a checkout: `pip install -e mcp`.
16
+
17
+ ## USDC payments: Base network only
18
+
19
+ USDC payments use Base only. Ethereum mainnet, Polygon, Solana, Arbitrum, and any other chain are not accepted.
20
+
21
+ | Network | Network id | Circle USDC contract | Status |
22
+ | --- | --- | --- | --- |
23
+ | Base Sepolia (testnet) | `eip155:84532` | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://sepolia.basescan.org/token/0x036CbD53842c5426634e7929541eC2318f3dCF7e) | Testing. A site in test mode offers only this USDC. It is not a network for real buyers. |
24
+ | Base | `eip155:8453` | [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) | Live when the operator sets `SATSGATE_X402_CDP=1` and both CDP credentials. A site in live mode offers only this USDC. |
25
+
26
+ Merchants: `payTo` must be an address you control on Base. The USDC is paid to that address on the one network that site 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 a Satsgate 402.
27
+
28
+ Satsgate never custodies, receives, forwards, or refunds buyer funds. The USDC moves from the buyer to the merchant's `payTo`. Satsgate does not hold a buyer wallet and does not run its own facilitator.
29
+
30
+ This MCP server does not send that USDC and does not hold a key. It shows the network and the amount printed on the 402. An accept on any other network is reported and is not payable. A test-mode 402 is Base Sepolia and is labeled testing. A live-mode 402 is Base. This server can describe either. It still does not sign. A wallet that signs uses the `extra` on that 402. Base Sepolia is name `USDC`. Base is name `USD Coin`. This server does not substitute a name.
31
+
32
+ `list_sites` reads `GET /v1/sites` on `SATSGATE_MCP_CORE_URL` (default `https://api.satsgate.org`). That is the public directory: approved sites that opted in. Set `SATSGATE_MCP_REGISTRY` only to replace it with a JSON file or another URL.
33
+
34
+ ## Run it
35
+
36
+ ```bash
37
+ pip install satsgate-mcp
38
+ export SATSGATE_MCP_DATA_DIR="$HOME/.local/share/satsgate-mcp"
39
+ export SATSGATE_MCP_MAX_PAYMENT_SATS=100
40
+ export SATSGATE_MCP_DAILY_MAX_SATS=500
41
+ satsgate-mcp
42
+ ```
43
+
44
+ `satsgate-mcp` speaks MCP over stdio. Logs go to stderr. From a checkout: `pip install -e mcp`.
45
+
46
+ Claude Desktop or Cursor config:
47
+
48
+ ```json
49
+ {
50
+ "mcpServers": {
51
+ "satsgate": {
52
+ "command": "satsgate-mcp",
53
+ "env": {
54
+ "SATSGATE_MCP_DATA_DIR": "/absolute/path/to/satsgate-mcp-data",
55
+ "SATSGATE_MCP_MAX_PAYMENT_SATS": "100",
56
+ "SATSGATE_MCP_DAILY_MAX_SATS": "500",
57
+ "SATSGATE_MCP_MAX_PAYMENT_USD": "1",
58
+ "SATSGATE_MCP_DAILY_MAX_USD": "5"
59
+ }
60
+ }
61
+ }
62
+ }
63
+ ```
64
+
65
+ Put `SATSGATE_MCP_NWC_URI` in that env block when you want the agent to pay. Do not paste the URI into the chat. The tools have no argument for it, and it is not logged.
66
+
67
+ ## Tools
68
+
69
+ | Tool | What it does |
70
+ | --- | --- |
71
+ | `discover` | GET (or POST) the URL with no payment. Reads `WWW-Authenticate: L402 macaroon="...", invoice="..."` and the JSON body: `amount_sats`, `max_uses`, `access_seconds`, `invoice_expires_at`. When the 402 offers x402, also reads `PAYMENT-REQUIRED` and the JSON `x402` mirror. |
72
+ | `quote` | Same request, plus a short sentence. |
73
+ | `pay_and_fetch` | `mode=human` (default) returns the Lightning invoice, a text QR, and a PNG when that rail is offered. `mode=nwc` pays Lightning from the environment wallet if the sats caps allow it, then fetches. An optional `payment_signature` forwards a `PAYMENT-SIGNATURE` the caller already has. This process does not sign. |
74
+ | `check_payment` | One poll of a human payment. `payment_pending` means call it again after `retry_after_seconds`. On settlement it fetches the URL with `Authorization: L402 <macaroon>` and no preimage. |
75
+ | `credits_balance` | `GET /v1/balance` with the optional restricted key. An `sgr_` key can read the balance. It cannot top up. Nothing is written. |
76
+ | `challenge_status` | `GET /v1/paywall/status/{payment_hash}?consume=false`. The macaroon is the one stored locally. It is not a tool argument. |
77
+ | `list_sites` | Approved, listed sites from `GET /v1/sites`. Routes keep `price_sats` when that is an integer, and `price_currency` plus `price_usd_atomic` when the route is priced in USD. A file or other URL in `SATSGATE_MCP_REGISTRY` replaces the directory. |
78
+
79
+ A token that still has uses, or whose pass has not ended, is sent again and is not paid again. The macaroon stays in the local sqlite file. It is not returned to the model.
80
+
81
+ If the server answers a stored token with a fresh 402 `token_used_up` or `token_expired`, the tool returns the new quote and does not pay. Call `pay_and_fetch` again to pay that invoice. Set `SATSGATE_MCP_AUTO_PAY=1` to pay that replacement inside the same call, and only when it is inside both caps.
82
+
83
+ `discover` followed within 60 seconds by `pay_and_fetch` for the same URL reuses that invoice instead of minting another one.
84
+
85
+ ## Human pay, no preimage
86
+
87
+ 1. `pay_and_fetch` with `mode=human`.
88
+ 2. Pay the BOLT11 invoice in any wallet. You do not need the preimage.
89
+ 3. `check_payment` with the `payment_hash`.
90
+
91
+ When `SATSGATE_MCP_API_KEY` is set and the challenge names a resource, `check_payment` first calls core `GET /v1/paywall/status/{payment_hash}` with the macaroon and `consume=false`. That is the LUD-21 poll. Unpaid is `status=pending`. Settled, it retries the original URL with the macaroon. The proxy then consumes one use and forwards.
92
+
93
+ Without a key, `check_payment` retries the URL directly. The proxy does the core poll. Pending is HTTP 402 `payment_pending` and does not mint a second invoice.
94
+
95
+ If the payee wallet does not advertise LUD-21 (Wallet of Satoshi), core returns `preimage_required`. Human poll cannot finish. Use `mode=nwc`, or a wallet that shows the preimage.
96
+
97
+ ## x402 (USDC on Base)
98
+
99
+ A site may enable only Lightning, only x402, or both. x402 is off until the merchant turns it on. If core has no fresh BTC/USD median, a sats-priced route's 402 offers only its primary currency. This client shows the 402 as it arrived. It does not invent a USDC price, and it does not round the amount again. The server already locked the quote and rounded it up (minimum 0.001 USDC, or 1 sat on Lightning).
100
+
101
+ `PAYMENT-REQUIRED` is base64 of an x402 v2 document. Each accept is returned with `scheme`, `network`, `asset`, `amount_atomic`, `amount_display` (`10000` is `0.01 USDC`), `pay_to`, `resource_url`, and `expires_at` when the body states one. The header is canonical. If the JSON mirror disagrees, the header values are the ones shown. A missing header with only the mirror present is shown with `canonical: false` and is not payable. Expiry is not computed from `maxTimeoutSeconds`.
102
+
103
+ Supported accepts are Circle USDC on Base Sepolia (`eip155:84532`, the network tests and the current gate use) and Circle USDC on Base (`eip155:8453`). Any other network or asset is listed with `supported: false`. The tool does not raise. A `PAYMENT-SIGNATURE` is forwarded only when every accept is one of those two and inside both USD caps, because the signature may select any accept.
104
+
105
+ This server holds no buyer private key. It does not sign, submit, custody, forward, or refund USDC, and it does not run a facilitator. Satsgate does not either. When `payable` is true, the `payment` object is what an external wallet has to pay. Call `pay_and_fetch` again with `payment_signature` set to that `PAYMENT-SIGNATURE`: one line, no spaces, at most 8192 bytes. Do not send an L402 `Authorization` on the same request. An empty `payment_signature` stays on the Lightning path.
106
+
107
+ The gate or proxy runs verify, then the origin, then settle. A 2xx returns the body and, when the server sent one, `payment_response` with `success`, `transaction`, `tx`, `network`, and `payer`. The raw header is not returned. If the origin fails, nothing is settled and no merchant credit is taken. The tool says so, sets `retry_same_payment_signature` true, and the same header can be sent again while the offer is valid. `bad_signature` and `expired` need a new signature. `x402_replay` was already settled, so sending it again does not fetch the resource. `x402_rejected` is either a failed verify (new signature) or a failed settle of a header you already sent (retry that same header). Local USD spend is recorded only after a 2xx, and the signature is not written to sqlite and is not logged.
108
+
109
+ Both `SATSGATE_MCP_MAX_PAYMENT_USD` and `SATSGATE_MCP_DAILY_MAX_USD` must be set or the tool will not proceed. `0` refuses every positive amount. Unset or over the cap, `discover` still returns the parsed requirements with `payable: false`. `pay_and_fetch` then refuses and does not send the header. The sats caps do not apply to USDC. An over-cap USDC amount does not block paying the Lightning invoice on the same 402.
110
+
111
+ `mode=human` still returns the invoice and QR when Lightning is offered, so a person can pay from any phone wallet and the agent continues with `check_payment`. A dual 402 returns that invoice and the x402 block together. An x402-only URL has no invoice. NWC is not required for it. An `sgr_` key is still only for `challenge_status` and `credits_balance`. The x402 tools do not call a route that needs an account key.
112
+
113
+ ## NWC
114
+
115
+ `SATSGATE_MCP_NWC_URI` is `nostr+walletconnect://...?relay=...&secret=...`. Both caps must be set or every NWC payment is refused. `0` refuses every positive amount. The spend ledger is `satsgate-mcp.sqlite` in the data dir (mode 0600). A payment is recorded when the wallet returns a preimage, including when the origin then fails. Sats are not refunded.
116
+
117
+ ## Environment
118
+
119
+ | Variable | Meaning |
120
+ | --- | --- |
121
+ | `SATSGATE_MCP_NWC_URI` | Wallet connection. Never a tool argument. Unset means NWC is off. |
122
+ | `SATSGATE_MCP_MAX_PAYMENT_SATS` | Most sats one invoice may cost. Required for NWC. |
123
+ | `SATSGATE_MCP_DAILY_MAX_SATS` | Most sats in any rolling 24 hours. Required for NWC. |
124
+ | `SATSGATE_MCP_MAX_PAYMENT_USD` | Most USDC one accept may cost, as a decimal with at most 6 places (`0.01` is 10000 atomic). Required before a `PAYMENT-SIGNATURE` is forwarded. Independent of the sats cap. |
125
+ | `SATSGATE_MCP_DAILY_MAX_USD` | Most USDC in any rolling 24 hours, same decimal form. Required together with the per-payment cap. |
126
+ | `SATSGATE_MCP_AUTO_PAY` | `1` pays a `token_used_up` / `token_expired` replacement inside the same call, if the caps allow it. Default off. |
127
+ | `SATSGATE_MCP_DATA_DIR` | sqlite directory. Default `~/.local/share/satsgate-mcp`. |
128
+ | `SATSGATE_MCP_CORE_URL` | Core base URL. Default `https://api.satsgate.org`. |
129
+ | `SATSGATE_MCP_API_KEY` | Optional `sgr_` key for the two read-only tools. An account `sg_` key is ignored. |
130
+ | `SATSGATE_MCP_URL_ALLOWLIST` | Comma-separated hosts. `*.example.com` allows subdomains. Empty allows any http(s) host. |
131
+ | `SATSGATE_MCP_HTTP_TIMEOUT` | Seconds, default 20. |
132
+ | `SATSGATE_MCP_MAX_BODY_BYTES` | Response cap, default 1000000. |
133
+ | `SATSGATE_MCP_REGISTRY` | Optional. A JSON file or http(s) URL that replaces the public directory. Unset uses `{SATSGATE_MCP_CORE_URL}/v1/sites`. |
134
+
135
+ Only `http` and `https` URLs are requested. Userinfo is rejected. Redirects are not followed. Requests time out.
136
+
137
+ ## Registry file
138
+
139
+ ```json
140
+ {
141
+ "sites": [
142
+ {"name": "example", "url": "https://shop.example/blog/post", "description": "One article"}
143
+ ]
144
+ }
145
+ ```
146
+
147
+ Leave `SATSGATE_MCP_REGISTRY` unset to use the public directory. The response uses `hosted_registry: true`, `slug`, `url` (the gate URL, `https://gate.satsgate.org/<slug>/` when that is the configured public base), `description`, and `routes` with `price_sats` when that price is an integer, plus `price_currency` and `price_usd_atomic` when the route is priced in USD. A USD-only route is kept. `list_sites` follows up to five pages. Each request waits at most 5 seconds, and never longer than `SATSGATE_MCP_HTTP_TIMEOUT`. A timeout, a connection failure, or a non-200 body returns `ok: false` and an empty `sites` list. It does not raise.
148
+
149
+ A row that includes `status` other than `approved`, or `listed` other than true, is skipped. The public endpoint does not return those rows. A local file that omits both fields is your own list.
150
+
151
+ If `SATSGATE_MCP_URL_ALLOWLIST` is set, the directory host has to be on it. The default host is the host of `SATSGATE_MCP_CORE_URL`.
152
+
153
+ ## Mainnet check from your machine
154
+
155
+ Use a route priced at 1 to 21 sats. Pay from a wallet that is not the payee.
156
+
157
+ ### Human QR
158
+
159
+ ```bash
160
+ pip install satsgate-mcp
161
+ export SATSGATE_MCP_DATA_DIR="$HOME/.local/share/satsgate-mcp"
162
+ satsgate-mcp-pay 'https://YOUR-PROXY/blog/post'
163
+ ```
164
+
165
+ The process prints the amount, the invoice, a text QR, and the path of a PNG under the data dir. Pay that invoice. It keeps polling until the invoice expires. The wait starts at 2 seconds and grows toward 15 seconds. `--polls N` and `--timeout SECONDS` are optional caps. Status lines start with a UTC timestamp. No NWC URI is required. The macaroon is not printed.
166
+
167
+ If it stops before the origin body is printed, it prints a command you can paste. That command resumes the same `payment_hash` from the data dir and does not mint a new invoice:
168
+
169
+ ```bash
170
+ SATSGATE_MCP_DATA_DIR="$HOME/.local/share/satsgate-mcp" satsgate-mcp-pay --resume PAYMENT_HASH
171
+ ```
172
+
173
+ If it stays on `payment_pending` until expiry, the invoice was unpaid or the payee has no LUD-21 `verify` URL. Wallet of Satoshi needs the NWC path below.
174
+
175
+ ### NWC, optional
176
+
177
+ ```bash
178
+ export SATSGATE_MCP_NWC_URI='nostr+walletconnect://...'
179
+ export SATSGATE_MCP_MAX_PAYMENT_SATS=50
180
+ export SATSGATE_MCP_DAILY_MAX_SATS=200
181
+ satsgate-mcp-pay --nwc 'https://YOUR-PROXY/blog/post'
182
+ ```
183
+
184
+ ### lnget and fetch402 against the proxy
185
+
186
+ These clients pay the 402 header themselves. They are not the MCP server. CI checks the header shape and does not pay. On your machine:
187
+
188
+ The header-shape script lives in the repo. The contributor section below runs it.
189
+
190
+ That request does not pay. It prints whether the lnget and fetch402 parsers accept the header. Then, to spend sats:
191
+
192
+ ```bash
193
+ lnget 'https://YOUR-PROXY/blog/post'
194
+ npm install @getalby/lightning-tools
195
+ export NWC_CONNECTION_STRING='nostr+walletconnect://...'
196
+ node mcp/scripts/fetch402.mjs 'https://YOUR-PROXY/blog/post'
197
+ ```
198
+
199
+ lnget and fetch402 retry with `Authorization: L402 <macaroon>:<preimage>`. A phone wallet that does not return a preimage pays the same invoice and retries with `Authorization: L402 <macaroon>` only. Pending must stay on that invoice (`402 payment_pending`), not a second one.
200
+
201
+ Confirm the origin saw the request and `X-Satsgate-Signature` verifies. A tampered path or a stale `t=` is rejected by the origin snippet.
202
+
203
+ ## For contributors
204
+
205
+ From a checkout: `PYTHONPATH=mcp/src python -m satsgate_mcp`.
206
+
207
+ ```bash
208
+ PYTHONPATH=mcp/src python mcp/scripts/mainnet_l402_clients.py 'https://YOUR-PROXY/blog/post'
209
+ ```