402-mcp

402-mcp

Nostr: npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2

AI エージェントに経済的な自律性をもたらす L402 クライアント MCP です。設定した上限の範囲内で、Lightning と ecash の決済が必要な API を見つけ、支払い、利用できます。人間による登録も、API キーも、仲介者も不要です。

• 発見：Nostr で有料 API を検索します。事前に URL を用意する必要はありません
• 自動支払い：Lightning（NWC）、Cashu ecash、LNURLcash のベアラーノート、または人間が QR コードを使うフォールバックに対応
• 認証情報を暗号化してキャッシュ：保存時に AES-256-GCM で暗号化します
• あらゆる L402 サーバーで動作：toll-booth、Aperture、または今後実装されるあらゆるサーバーに対応

クイックスタート

インストールは不要です。MCP クライアントが初めて起動するときに、npx が 402-mcp を取得します。手動で npx 402-mcp を実行すると、標準入力からのクライアント接続を待機する stdio サーバーが起動するだけです（Ctrl+C で停止）。これは起動確認には使えますが、実際の利用には使いません。

1. MCP クライアントに接続する

Claude Code：

claude mcp add 402-mcp -- npx 402-mcp

Claude Desktop または Cursor の場合は、MCP 設定ファイルに記述します。

{
  "mcpServers": {
    "402-mcp": {
      "command": "npx",
      "args": ["402-mcp"]
    }
  }
}

2. 試してみる

Claude に 「l402-search を使って有料のジョーク API を検索して」 と尋ねてみましょう。ウォレットは不要で、検索だけを行います。

3. API 呼び出しの支払い（任意）：NWC ウォレットを接続する

402-mcp は Nostr Wallet Connect URI をプライベートファイルから読み込みます。環境変数やコマンドラインから読み込むことはありません。まず所有者のみがアクセスできる権限でファイルを作成し、URI がシェルの履歴に残らないよう、エディターで貼り付けます。

mkdir -p ~/.402-mcp
touch ~/.402-mcp/wallet.nwc
chmod 600 ~/.402-mcp/wallet.nwc
# open ~/.402-mcp/wallet.nwc in an editor, paste the URI on one line, save

URI はウォレットサービスから取得します。プレースホルダーを自分の値に置き換えると、次のような形式になります。

nostr+walletconnect://<wallet-pubkey-hex>?relay=<wss-relay-url>&secret=<secret-hex>

ウォレットの公開鍵として 64 文字の 16 進数、1～8 個の relay 値、64 文字の 16 進数の secret が必要です。lud16 を含めることもできます。それ以外のパラメーターは拒否されます。ファイルは通常の空でないファイルで、サイズは 8 KiB 未満でなければなりません。また、macOS と Linux では、グループおよびその他のユーザーに権限がない場合（chmod 600）に限り使用できます。pay_invoice 権限を指定し、支出上限を設定して接続を作成してください（lookup_invoice も指定すると、l402-reconcile が不明な結果についてウォレットに問い合わせられます）。ウォレットは NIP-44 v2 暗号化に対応している必要があります。

次に、絶対パスを指定して 402-mcp を登録します（コマンドの実行時に、シェルで $HOME が展開されます）。

claude mcp remove 402-mcp
claude mcp add 402-mcp -e NWC_URI_FILE="$HOME/.402-mcp/wallet.nwc" -e MAX_AUTO_PAY_SATS=1000 -- npx 402-mcp

Claude Desktop または Cursor の場合は、同じサーバーエントリーに env ブロックを追加してください。JSON では ~ や $HOME は展開されないため、作成したファイルの絶対パスを記述します。

{
  "mcpServers": {
    "402-mcp": {
      "command": "npx",
      "args": ["402-mcp"],
      "env": {
        "NWC_URI_FILE": "/absolute/path/to/.402-mcp/wallet.nwc",
        "MAX_AUTO_PAY_SATS": "1000"
      }
    }
  }
}

生の NWC_URI 変数は起動時に拒否されます。Cashu、LNURLcash、またはウォレットを使わない場合や、初めての有料呼び出しについては、完全版クイックスタートガイドをご覧ください。

Node.js 22.4 以降が必要です。

仕組み

graph LR
    A["1. l402-config()"] --> B["2. l402-discover(url)"]
    B --> C["3. Agent reasons<br/>about pricing"]
    C --> D["4. l402-buy-credits()<br/>or l402-fetch(autoPay)"]
    E["5. l402-fetch(url)<br/>with stored credential"]
    D --> E
    E --> F["6. Data returned<br/>+ balance cached"]

セッション例：

Agent: "I need routing data from routing.example.com"

1. l402-config()
   -> nwcConfigured: true, maxAutoPaySats: 1000

2. l402-discover("https://routing.example.com/api/route")
   -> 10 sats/request, toll-booth detected, tiers available

3. Agent reasons: "I need ~20 requests. The 500-sat tier
   gives 555 credits. Better value."

4. l402-buy-credits(url, amountSats=500)
   -> Paid 500 sats, received 555 credits

5. l402-fetch("https://routing.example.com/api/route?from=...&to=...")
   -> 200 OK, route data, 545 credits remaining

ステップ 5 では autoPay は不要です。ステップ 4 でそのサーバーの認証情報が保存されており、l402-fetch がそれを送信するためです。保存済みの認証情報がない場合、autoPay: true を指定しない限り l402-fetch は支払いを行わず、代わりに価格と paymentHash を返します（支出上限を参照）。

アーキテクチャと決済フローの詳しい図は、docs/architecture.mdをご覧ください。

設定

変数	デフォルト	説明
NWC_URI_FILE	-	NWC ベアラー URI を含む、アクセス権が 0600 のファイルへのパス
CASHU_TOKENS	-	Cashu トークンストアファイルへのパス。ホームディレクトリ内にある必要があります
LNURLCASH_NOTES	-	LNURLcash ベアラーノートストアファイル（LUD-25）へのパス。ホームディレクトリ内にある必要があります
MAX_AUTO_PAY_SATS	1000	1 回の自動支払いで許可される上限額です。これを超える金額は支払われず、チャレンジがエージェントに戻されます。0 にすると自動支払いが無効になります
MAX_SPEND_PER_MINUTE_SATS	10000	任意の連続する 60 秒間に許可される自動支出額です。0 にするとすべての自動支払いがブロックされます。デフォルト設定では、下記の日次上限が先に適用されます（支出上限を参照）
MAX_SPEND_PER_DAY_SATS	5000	任意の連続する 24 時間に許可される自動支出額です。再起動してもリセットされないよう、~/.402-mcp/spend-ledger.json に保存されます。0 にするとすべての自動支払いがブロックされます
CREDENTIAL_STORE	~/.402-mcp/credentials.json	macaroon／認証情報の永続ストレージです。ホームディレクトリ内にある必要があります
TRANSPORT	stdio	トランスポートモードです。stdio または http を指定します
PORT	3402	HTTP サーバーのポート（TRANSPORT=http の場合）
BIND_ADDRESS	127.0.0.1	HTTP のバインドアドレス
HTTP_AUTH_TOKEN_FILE	-	HTTP クライアントが送信する必要のあるベアラートークンを保持する、アクセス権が 0600 のファイルです。TRANSPORT=http の場合は必須です
HTTP_ALLOWED_HOSTS	-	HTTP トランスポートが受け付ける追加の Host ヘッダー値（カンマ区切り）です。リバースプロキシの名前などを指定します
CORS_ORIGIN	無効	HTTP トランスポートの CORS オリジンです（* または 1 つのオリジン）。* を指定すると警告が記録され、すべての Web サイトからサーバーを呼び出せるようになります
TRANSPORT_PREFERENCE	onion,hns,https,http	複数の URL があるサービスで優先するトランスポートの順序（カンマ区切り）
TOR_PROXY	-	.onion アドレス専用の SOCKS5 プロキシ（例：socks5h://127.0.0.1:9050）
SOCKS_PROXY	-	有料 API リクエストすべてに使用する SOCKS5 プロキシ（例：socks5h://127.0.0.1:9050 の Tor）。これまたは TOR_PROXY のいずれか一方を設定してください。両方は設定しないでください
HNS_GATEWAY_URL	https://query.hdns.io/	Handshake 名の解決に使用する DNS-over-HTTPS リゾルバーです。通常の DNS で検索できないホスト名は、ここで検索されます
HUMAN_PAY_TIMEOUT_S	600	支払いページがなく、ポーリング対象がない場合に、人間の支払者が決済を確認するためサーバーにポーリングする時間（秒）
HUMAN_PAY_POLL_S	3	人間の支払者がポーリングする最初の間隔（秒）。最大 30 秒まで延長されます
FETCH_TIMEOUT_MS	30000	各送信 HTTP リクエストのタイムアウト
FETCH_MAX_RETRIES	2	状態を変更しないリクエストの再試行回数。金銭を変更する POST は再試行されません
FETCH_MAX_RESPONSE_BYTES	10485760	受け入れ可能なレスポンスボディの最大サイズ（10 MiB）
SSRF_ALLOW_PRIVATE	false	プライベートアドレスおよびループバックアドレスへのリクエストを許可します。ローカル開発専用です
ALLOW_INSECURE_TLS	false	NODE_TLS_REJECT_UNAUTHORIZED=0 が設定されている場合に、そのリスクを了承します。これ（または SSRF_ALLOW_PRIVATE=true）が設定されていない場合、402-mcp はその状態での起動を拒否します

NWC_URI と HTTP_AUTH_TOKEN は起動時に拒否されます。両方のシークレットは、それぞれの *_FILE 変数からのみ読み込まれます。支出上限、MAX_AUTO_PAY_SATS、FETCH_MAX_RETRIES には 0 以上の整数を指定する必要があります。タイムアウト、サイズ上限、ポーリング間隔には 1 以上の値を指定してください。PORT は 1～65535 の範囲で指定してください。

トランスポートの選択とフォールバック

kind 31402 イベントで複数の URL（トランスポートごとに 1 つ）が通知された場合、402-mcp は設定に基づいて最適なものを選択します。

1. 優先順位を適用：URL は、デフォルトでは onion,hns,https,http の順に、TRANSPORT_PREFERENCE に従って試されます。値として使用できるのは onion、hns、https、http のみで、それ以外の値はありません。TLD が .hns の URL は hns として扱われます。TLD が見慣れないもの（.pub、.fyi）にすぎない URL は、ICANN の名前である可能性が高いため、それ自体に優先順位はありません。hns と https のうち、設定した順序で後になる方の直後に試される、推定 hns 名として扱われます。デフォルトでは https の直後です。TRANSPORT_PREFERENCE から hns を除外した場合、このような URL は最後に試されます。
2. 対応状況でフィルタリング：TOR_PROXY または SOCKS_PROXY が設定されていない場合、.onion URL はスキップされます。そのため、プロキシがなければデフォルトの順序は HNS とクリアネットから始まります。
3. 利用可能なトランスポートにフォールバック：トランスポートに接続できない場合（接続拒否、タイムアウト）、次の URL が試されます。

サービスは、異なるトランスポートで同じサービス（同じ料金、同じ macaroon キー）に対して複数のエンドポイントを通知できます。これは検閲耐性のためだけのもので、トランスポートを切り替えても再認証する必要はありません。.onion エンドポイントには TOR_PROXY または SOCKS_PROXY が必要です。Handshake エンドポイントには設定が不要です。HNS_GATEWAY_URL にデフォルト値があるためです。ただし、SOCKS_PROXY の使用時は例外で、Handshake の名前解決が無効になります（Tor と SOCKS5 を参照）。

トランスポート間での認証情報の共有。 l402-fetch にサービスの pubkey（l402-search から取得）を指定すると、認証情報はその pubkey をキーとして保存・検索されるため、urls に渡されたすべてのトランスポート URL で 1 回の購入を利用できます。pubkey を指定しない場合、認証情報はリクエストのオリジンをキーとして保存されます。どちらの場合も、認証情報には購入に使用したオリジンが記録され、その後のリクエストでどの pubkey が指定されても、そのオリジンにのみ送信されます。そのため、購入時に両方の URL が urls に含まれていれば、Tor の隠しサービス経由で購入した macaroon はクリアネットの URL でも使用でき、他のホストに送信されることはありません。

Tor と SOCKS5

• TOR_PROXY は .onion リクエストをプロキシ経由で送信します。それ以外はすべて直接接続します。
• SOCKS_PROXY はリダイレクトを含め、有料 API へのすべてのリクエストをプロキシ経由で送信します。ホスト名はこのマシンではなくプロキシによって解決されるため、Tor プロキシを使うと IP アドレスと検索する名前の両方が隠されます。SSRF ガードは引き続き、プライベート IP のリテラルや localhost などのローカル名を拒否します。接続先で名前が何に解決されるかは確認できませんが、Tor の出口ノードはプライベート範囲への接続を拒否します。

どちらの設定も、ウォレットやディスカバリーの通信には適用されません。NWC リレー、Cashu と LNURLcash のミント、l402-search が照会する Nostr リレーは、引き続き直接接続します。DNS-over-HTTPS クエリがプロキシを経由せずに送信されるため、SOCKS_PROXY の使用時は Handshake の名前解決が無効になります。

SOCKS5 のサポートには undici の Socks5ProxyAgent を使用しています。Node ではこれが実験的機能として扱われるため、プロキシを設定すると stderr に ExperimentalWarning が 1 回出力されます。

ツール

コア L402（すべてのサーバー）

ツール	説明
l402-config	支払い機能（ウォレット、上限、認証情報の件数）を確認します
l402-discover	支払いを行わずにエンドポイントを調査し、料金を確認します
l402-fetch-preview	支払いを行わずにエンドポイントの料金を表示します。支払い確認ウィジェットを起動します
l402-fetch	autoPay が設定され、料金が上限内の場合に 402 チャレンジの支払いを行う HTTP リクエストです
l402-pay	l402-fetch または l402-discover が返したチャレンジを、支払いハッシュで支払います。それ以外の請求書には人間の承認が必要です
l402-reconcile	結果が不明な支払いを一覧表示または解決します。解決するまで、そのサービスへの自動支払いは一時停止されます
l402-credentials	保存済みの認証情報とキャッシュされた残高を一覧表示します
l402-balance	サーバーのキャッシュされたクレジット残高を確認します
l402-search	Nostr リレー上の L402 サービス（kind 31402 の告知）を検索します
l402-store-token	支払いページで取得した L402 トークンを保存します

ウィジェット（MCP Apps ホスト）

ツール	説明
l402-service-directory	l402-search で見つかったサービスを検索・閲覧できるインタラクティブなディレクトリです
l402-wallet-dashboard	ウォレットの状態、上限、保存済み認証情報をインタラクティブに表示します

l402-fetch-preview には支払い確認ウィジェットもあります。

toll-booth の拡張機能

ツール	説明
l402-buy-credits	ボリュームディスカウントの段階を閲覧し、購入します
l402-redeem-cashu	Cashu トークンを直接引き換えます（Lightning の往復を回避します）

引数と結果

* は必須の引数を示します。すべてのツールは JSON テキストを返し、失敗時には MCP の isError フラグを設定します。

ツール	引数	戻り値
l402-config	なし	nwcConfigured、cashuConfigured、cashuBalanceSats、maxAutoPaySats、maxSpendPerMinuteSats、maxSpendPerDaySats、spentLast24HoursSats、credentialCount。LNURLcash のノートは報告されません
l402-discover	url*、method（デフォルトは GET。POST、PUT、PATCH、DELETE、HEAD、OPTIONS も指定可能）	url、costSats、invoice、macaroon、paymentHash。トールブースに対しては、さらに server と creditTiers も返します。L402 チャレンジのみを読み取り、l402-pay 用にチャレンジをキャッシュします
l402-fetch-preview	url*、urls（バッチ、最大 10 件）、method、headers、pubkey	endpoint、protocol、costSats（x402 の場合は costUsd）、paymentMethod（支払いに使用するウォレット）、paymentHash、expiresAt、message を含む status（preview、free、error）。urls が指定された場合は配列
l402-fetch	url*、urls（l402-search のすべてのトランスポート URL、最大 10 件）、pubkey（l402-search から取得）、method（l402-discover と同様）、headers（文字列のオブジェクト）、body（文字列、最大 1,000,000 文字）、autoPay（デフォルトは false）、maxCostSats（整数。この呼び出しの上限を引き下げます）、txHash（完了した x402 支払いの 0x に続く 64 桁の 16 進数）、paymentFlow（ストレージサービスのお知らせを参照）。支払い方法の引数はありません	支払い済みまたは無料の場合：status、headers、body（信頼できないコンテンツとしてマーク）、creditsRemaining、satsPaid、および IETF Payment、LNURLcash、xCashu のいずれかの決済手段で支払われた場合は paymentMethod。未払いのチャレンジの場合：status: 402、costSats、invoice、paymentHash、creditsExhausted、提示されている場合は tiers、message。人間が支払う場合：paymentUrl または請求書の QR コード。失敗時には paymentState（failed、unknown、blocked）または error が含まれます
l402-pay	paymentHash（l402-fetch または l402-discover のチャレンジから取得）、method（nwc、cashu、lnurlcash、human のいずれか）、invoice と macaroon（チャレンジで生成されなかった請求書の場合のみ。人間による承認が必要です）	paid、paymentState（paid、failed、unknown、blocked）、credentialsStored、method、成功しなかった場合は reason
l402-reconcile	paymentHash（64 桁の 16 進数。一覧表示する場合は省略）、preimage（64 桁の 16 進数）、abandon（ブール値。人間による承認が必要です）	一覧表示の場合：unresolved（各項目に paymentHash、origins、costSats、protocol、method、createdAt を含む）と message。解決の場合：paymentHash、resolved、state（settled、failed、pending、abandoned）、決済済みの場合は credentialsStored、message
l402-credentials	なし	credentials：各項目に origin、origins、paymentHash、creditBalance、storedAt、lastUsed、server を含みます。Macaroon と preimage は表示されません
l402-balance	origin*（https://api.example.com のような URL）	origin、creditsRemaining、lastUpdated、stale（5 分より古い場合は true）。その origin の情報が保存されていない場合はエラー
l402-search	query*（最大 200 文字）、topics（最大 10 件）、paymentMethod（お知らせの pmi タグの最初の値：l402、cashu、xcashu、lnurlcash、x402、payment のいずれか）、relays（最大 10 件の URL）、maxResults（1～100、デフォルトは 20）、timeout（1000～30000 ms、デフォルトは 5000）	サービスの配列：name、about、urls、pubkey、paymentMethods、pricing（capability、amount、unit）、topics、capabilities、ストレージサービスの場合は storage。お知らせのテキストは信頼できないコンテンツとしてマークされます
l402-store-token	url、token（macaroon:preimage）	stored: true、origin、Macaroon から読み取れる場合は paymentHash。preimage または Macaroon の形式が正しくない場合はエラー
l402-buy-credits	url*（トールブースサーバー）、amountSats（ティアを一覧表示する場合は省略）、method（nwc、cashu、human のいずれか）	amountSats を指定しない場合：tiers。指定した場合：paid、amountSats、creditsReceived、credentialsStored、method。人間が支払う場合は、代わりに QR コードと paymentHash を返します
l402-redeem-cashu	url（トールブースサーバー）、token（Cashu トークン）	redeemed: true、creditsReceived、credentialsStored、認証情報を保存できなかった場合は warning

支払い方法

402 の支払い方法は、サーバーが送信したチャレンジと、Lightning インボイスの場合はそれを支払うペイヤーという、別々の 2 つの選択によって決まります。

Lightning インボイスのペイヤー。 L402 または IETF Payment チャレンジでは、l402-pay と l402-buy-credits は、次の順序で最初に利用可能なペイヤーを使ってインボイスを支払います。

1. NWC（Nostr Wallet Connect）：完全に自動で、接続済みウォレットから支払います。NWC_URI_FILE が設定されている場合に利用できます。
2. Cashu：完全に自動で、ecash トークンをメルトしてインボイスを支払います。CASHU_TOKENS ストアに残高がある場合に利用できます。
3. LNURLcash：完全に自動で、LUD-25 ベアラーノートをメルトしてインボイスを支払います。LNURLCASH_NOTES ストアに残高がある場合に利用できます。
4. 人間の介在：上記のいずれも利用できない場合、または l402-pay や l402-buy-credits に method: "human" が渡された場合にのみ使用されます。l402-fetch は待機せず、料金所の支払いページ URL、または QR コードとインボイスをすぐに返します。ユーザー自身のウォレットから支払った後、エージェントが l402-pay を呼び出します。これは料金所の支払いページを最大 120 秒間ポーリングします（支払いページがない場合は、サーバーの /invoice-status/<hash> エンドポイントを HUMAN_PAY_TIMEOUT_S 秒間ポーリングします）。決済を確認できるのは、サーバーがその情報を返す場合のみです。料金所は返しますが、ほかの L402 サーバーは返しません。料金が MAX_AUTO_PAY_SATS を超える場合、人間のペイヤーにも引き継がれず、チャレンジは未払いのままエージェントに戻されます。

支払いごとに選択されるペイヤーは 1 つで、フォールバックはありません。失敗した場合はその失敗が報告され、次のペイヤーは試されません。別のペイヤーを使うには、l402-pay に method（nwc、cashu、lnurlcash、human のいずれか）を渡すか、l402-buy-credits に method（nwc、cashu、human のいずれか）を渡してください。l402-fetch に支払い方法の引数はありません。必要な方法だけを設定することもできます。

サーバーが送信したチャレンジ。 l402-fetch は 4 種類の HTTP 402 チャレンジと、実験的な x402 形式に対応しています。レスポンスに複数含まれている場合は、以下の順序で確認し、対応可能な最初のものを使用します。どの決済手段でも、autoPay: true であり、価格が上限内である必要があります。

順序	プロトコル	チャレンジヘッダー	支払い
1	LNURLcash（LUD-25）	X-LNURLcash: lnurlcashreq1…	ノートストアからベアラーノートを取り出し、そのまま渡します（LNURLCASH_NOTES が必要）。上記のペイヤー順序は経由しません
2	xCashu（NUT-18）	X-Cashu: creqA…	Cashu ストアから ecash トークンを直接送信します（CASHU_TOKENS が必要）。上記のペイヤー順序は経由しません
3	x402（実験的なカスタム形式）	X-Payment-Required: x402 + JSON ボディ	x402 仕様（サーバーが base64 の PAYMENT-REQUIRED ヘッダーを送信するもの）ではなく、カスタム形式です。そのため、実際の x402 サービスには対応していません。支払いの詳細が人間に提示され、ユーザー自身のウォレットから支払います
4	IETF Payment（draft-ryan-httpauth-payment-01）	WWW-Authenticate: Payment	Lightning インボイス。上記のペイヤー順序で支払います
5	L402	WWW-Authenticate: L402	Lightning インボイス。上記のペイヤー順序で支払います

LNURLcash を最初に確認するのは、ベアラーノートはすでに手元にあるお金であり、それを支払うのに Lightning の中継もミントでのスワップも不要だからです。ノートはそのまま再試行ヘッダーに含められ、サーバーが決済します。価格と完全に一致するノートがない場合、ミントでノートを分割し、お釣りはストアに残ります。該当するノートがない場合、またはノートストアが設定されていない場合は、同じレスポンスに含まれる残りのチャレンジが通常どおり試されます。上記の一覧にある LNURLcash ペイヤーは別の経路で、ノートをメルトして Lightning インボイスを支払います。 l402-fetch-preview は、支払いを行わずに検出したチャレンジを報告し、支払いに使用するウォレット（paymentMethod）も示します。チャレンジの種類を l402-fetch とは異なる順序（IETF Payment、L402、LNURLcash、xCashu、x402）で確認するため、サーバーが一度に複数の種類を送信する場合、プレビューで示される決済手段は l402-fetch が使用するものと異なることがあります。

支出上限

402-mcp は自動支払いのたびに次の上限を確認し、エージェントは l402-config でその内容を確認できます。

• MAX_AUTO_PAY_SATS は各支払いの上限です。これを超える価格のチャレンジは、支払いを行わずにエージェントへ返されます。0 にすると自動支払いが無効になり、価格のあるチャレンジはすべてエージェントに返されます。
• l402-fetch の maxCostSats は、1 回の呼び出しについてこの上限を引き下げます。そのため、l402-fetch-preview に表示された価格が適用されます。上限を引き上げることはできません。
• MAX_SPEND_PER_MINUTE_SATS と MAX_SPEND_PER_DAY_SATS は、移動期間内の自動支払い総額に上限を設定します。日次の期間は永続化されるため、サーバーを再起動してもリセットされません。どちらかを 0 にすると自動支払いが全面的にブロックされます。デフォルト値（1 分あたり 10,000、1 日あたり 5,000）では日次上限のほうが低く、どの 1 分間の支出も日次上限に加算されるため、日次上限を引き上げるか、分単位の上限を引き下げない限り、分単位の上限には達しません。
• 支払いの結果が不明な場合、l402-reconcile で解決されるまで、そのサービスへの自動支払いは一時停止されるため、同じものを二重に購入することはありません。

実際に効く厳格な上限は、NWC 接続に設定した予算です。 上記の内容はすべて、このプロセスが実行されているマシン上でソフトウェアにより適用されます。多くの NWC ウォレットでは、接続の作成時に支出予算を設定できます。バグや不正な動作をするエージェントでも引き上げられない上限なので、必ず設定してください。Cashu と LNURLcash の場合、厳格な上限はトークンまたはノートのストアに設定した金額です。

プライバシー

402-mcp は認証情報を実行中のマシンにのみローカル保存します（~/.402-mcp/credentials.json。保存時は AES-256-GCM で暗号化されます）。暗号化キーは、利用可能な場合は OS のキーチェーンに保存されます（macOS では security ツールを介した Keychain、その他の環境ではオプションの keytar モジュール。ただし、現在の Node では読み込みに失敗することがよくあります）。それ以外の場合はファイルにフォールバックし、0600 権限で ~/.402-mcp/encryption.key を作成します。この場合、キーチェーンを利用できなかったことを 402-mcp が起動時に警告します。このファイルを読み取れる人は誰でもストアを復号できます。アカウント、追跡、分析機能はなく、402-mcp 自体のサーバーもありません。ただし、呼び出す API 以外の相手と通信することがあります。

• Nostr リレー。 l402-search は、サービスの告知を受信するために公開リレー（デフォルトでは relay.damus.io、relay.primal.net、nos.lol）を購読し、指定したトピックフィルターのみを送信します。支払い方法のフィルターと検索クエリのテキストはローカルで照合されるため、リレーに伝わることはありません。
• Handshake リゾルバー。 通常の DNS でホスト名を見つけられない場合は、HNS_GATEWAY_URL（デフォルトでは https://query.hdns.io/）で検索されるため、その名前がリゾルバーに伝わります。SOCKS_PROXY の設定中は無効です。
• ウォレットのサービス。 NWC リレー、Cashu ミント、LNURLcash ミントには、それらを通じて行った支払いが伝わります。

支払いには Lightning または ecash を使用します。これらは匿名ではなく、仮名性を備えています。

コードでのモジュールの使用

このパッケージは、9つのサブパスインポートを公開しています。それぞれが build/<path>.js に対応し、その隣に宣言ファイルがあるため、types フィールドがなくても TypeScript が型を認識します。

インポート	内容
402-mcp/tools/*	ツールハンドラーと register*Tool 関数。例：402-mcp/tools/fetch
402-mcp/l402/*	parse、detect、bolt11、challenge-cache
402-mcp/x402/*、402-mcp/xcashu/*、402-mcp/xlnurlcash/*、402-mcp/ietf-payment/*	各レール用のチャレンジパーサーと支払いヘルパー
402-mcp/store/*	認証情報、Cashu トークン、LNURLcash ノート、保留中の支払いのストア
402-mcp/fetch/*	回復力のあるフェッチ、SSRF ガード、トランスポート選択、SOCKS と Handshake の名前解決
402-mcp/spend-tracker	SpendTracker

これらはサーバー独自のモジュールを、そのまま公開したものです。シグネチャについては src/ を参照してください。ライブラリコードからパッケージのルート（402-mcp）をインポートしないでください。main と . のエクスポートはいずれもサーバーのエントリーポイントである build/index.js を指しており、インポートするとすぐに環境から設定を読み込み、トランスポートに接続するためです。

import { SpendTracker } from '402-mcp/spend-tracker'
import { parseL402Challenge } from '402-mcp/l402/parse'

const tracker = new SpendTracker()
console.log(tracker.tryRecord(50, 10_000)) // true: 50 sats fits under a 10,000 sat per-minute cap

const challenge = parseL402Challenge('L402 macaroon="AgEEbG5kcg==", invoice="lnbc10n1pexample"')
console.log(challenge) // { macaroon: 'AgEEbG5kcg==', invoice: 'lnbc10n1pexample' }

ストレージサービスの告知（Wildbloom）

l402-search は、forgesworn-storage-service-v1 プロファイル（kind 31402、402-announce/storage 2.3.0 による検証済み）で告知されたストレージサービスも返します。Wildbloom はそのようなサービスの1つです。有料ストレージと、free shelter と呼ばれる無料枠を提供しています。free shelter は、認可済みミラーからプッシュされたコピーをベストエフォートで保持しますが、削除される場合があり、身元不明のユーザーからの直接アップロードは受け付けません。

これらの検索結果は説明を目的としたものにすぎません。有料ストレージの検索結果には storage.paymentFlow: "wildbloom-checkout-v1" と autoPaySupported: false が設定されており、402-mcp から購入することはできません。このフローを l402-fetch や l402-pay に渡さないでください。どちらも拒否します。また l402-fetch は、ネットワーク、認証情報、ウォレットにアクセスする前に、あらゆる /checkout/v1 パスも拒否します。購入するには、運営者の最新の利用規約（/services/v1 の一覧）を確認し、Wildbloom 独自のチェックアウトを使用してください。チェックアウトでは、NIP-98（Nostr HTTP 認証）で署名された非公開の見積もりと、ユーザー自身による明示的な支払いが求められます。free shelter へのミラーリングも、これらのツールでは行いません。告知に記載された規約は運営者自身による主張であり、推奨や稼働時間の証明ではありません。また、有効な署名が示すのは公開者だけであり、購入を承認するものではありません。

検索結果の選定方法：検索では、指定されたリレー（またはデフォルトのリレー）にのみ問い合わせ、ストレージノードやウォレットには問い合わせません。サービスごとに、期限切れ、取り下げ、クエリの各フィルターを適用する前に、最新の有効な署名付き告知（同じ公開者と d タグを持つもの。同じタイムスタンプの場合はイベント ID が最小のもの）を選択します。古いコピーをリレーが再送しても、取り下げ済みまたは期限切れのオファーが再び有効にならないよう、サービスごとに確認済みの最新レコードをウォーターマークとしてメモリーに保持します。検索ハンドラーごとに最大2,000件を保持し、サーバーの再起動まで呼び出しをまたいで保持します。この上限を超える検索は、いずれのレコードも削除せず、エラーになります。新規起動したサーバーにはウォーターマークがないため、リレーが提示しないレコードについては把握できません。満枠または一時停止中でも現行の一覧は検索結果に残ります。期限切れや取り下げ済みのものはウォーターマークとして残りますが、返されません。サービスの検出では、ディスクへの保存もブラウザーの起動も行いません。

エコシステム

決済ゲート付き API の分散型マーケットプレイス、402.pub で稼働中の L402 サービスを確認できます。

プロジェクト	役割
toll-booth	決済バックエンドに依存しない HTTP 402 ミドルウェア
satgate	トークンごとに課金する AI 推論プロキシ（toll-booth 上に構築）
402-mcp	MCP クライアント：AI エージェントが L402 API を見つけ、支払い、利用できます
402-announce	分散型のサービス発見に向けて、Nostr で L402 サービスを公開

402-mcp は、Lightning Labs の lightning-agent-tools に代わる、ウォレットプロバイダーに依存しない選択肢です。Lightning ノードは不要で、複数のウォレットに対応し、認証情報は暗号化されます。

比較の詳細

	402-mcp	Lightning Labs のエージェントツール
支払い方法	NWC + Cashu + LNURLcash + 人間による代替手段	Lightning のみ
ノードは必要ですか？	いいえ。任意の NWC ウォレットに接続します	はい。LND を実行します
サーバーとの互換性	任意の L402 サーバー	Aperture 向け
支出の安全性	支払いごとの上限、呼び出しごとの最大コスト、ローリング 60 秒間および永続化される 24 時間の利用枠	呼び出しごとの最大コスト（--max-cost）
認証情報の保存	保存時に暗号化（AES-256-GCM）	ファイル権限
プライバシー	個人情報なし、SSRF 保護、エラーのサニタイズ	標準

Lightning Labs の支出安全性に関するセルは、lightning-agent-tools の lnget ドキュメントに基づいています。--max-cost は、lnget が 1 回のリクエストに対して自動で支払う最大額を設定します（docs/l402-and-lnget.md）。このページには、複数のリクエストにまたがる予算についての記載はありません。この列のその他のセルは、ここでは出典を確認できません。

エージェントに独自の Lightning ノードを実行させたい場合は、Lightning Labs のツールを使用してください。インフラを用意せず、任意のウォレットから支払わせたい場合は、402-mcp を使用してください。

開発環境のセットアップとガイドラインについては、CONTRIBUTING.md をご覧ください。

---

@forgesworn が開発しました。

• Lightning のチップ：[email protected]
• Nostr：npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2

---

ForgeSworn Toolkit の一部

ForgeSworn は、Nostr 向けに、暗号学的なアイデンティティ、決済、調整のためのオープンソースツールを開発しています。

ライブラリ	機能
nsec-tree	決定論的なサブアイデンティティの導出
ring-sig	secp256k1 上の SAG/LSAG リング署名
range-proof	Pedersen コミットメントのレンジプルーフ
canary-kit	強制に耐性のある口頭での検証
spoken-token	人が発話できる検証トークン
toll-booth	L402 決済ミドルウェア
geohash-kit	ポリゴンカバレッジ対応の Geohash ツールキット
nostr-attestations	NIP-VA 検証可能な証明
dominion	エポックベースの暗号化アクセス制御
nostr-veil	プライバシーを保護する Web of Trust

ライセンス

MIT