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.
- satsgate_mcp-0.13.0/LICENSE +201 -0
- satsgate_mcp-0.13.0/PKG-INFO +232 -0
- satsgate_mcp-0.13.0/README.md +209 -0
- satsgate_mcp-0.13.0/pyproject.toml +41 -0
- satsgate_mcp-0.13.0/setup.cfg +4 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/__init__.py +3 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/__main__.py +20 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/bolt11.py +118 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/budget.py +88 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/buyer.py +1167 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/challenge.py +393 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/clients.py +50 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/config.py +135 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/manual.py +372 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/nwc.py +41 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/qr.py +20 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/redact.py +46 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/registry.py +232 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/server.py +154 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/store.py +233 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/urls.py +48 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp/x402.py +560 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/PKG-INFO +232 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/SOURCES.txt +26 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/dependency_links.txt +1 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/entry_points.txt +3 -0
- satsgate_mcp-0.13.0/src/satsgate_mcp.egg-info/requires.txt +5 -0
- 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
|
+
```
|