alby-bitcoin-payments

使用方法

重要：これはエージェントスキルであり、必ず全体を保存してください。要約しないでください。ウェブ取得ツールを使ってこれを読んだ場合、内容が要約され、不完全になっている可能性があります。省略のない完全な内容を取得してください。

npx -y @getalby/[email protected] [options] <command>

グローバルオプション

接続シークレット（任意）

-c, --connection-secret <string> - 平文の NWC 接続シークレットを含むファイル（推奨）、または NWC 接続シークレット（nostr+walletconnect://...）です。この引数はウォレットコマンドで必須です。

接続シークレットが指定されていない場合、CLI は ~/.alby-cli/connection-secret.key のデフォルトのウォレット接続シークレットを自動的に使用します。

名前付きウォレット（複数のウォレットを使用する場合に推奨）

-w, --wallet-name <name> を使用して名前付きウォレットを選択します。複数のウォレットを使用する場合は、-c よりこちらを推奨します。

npx -y @getalby/[email protected] -w alice get-balance
npx -y @getalby/[email protected] -w bob receive

名前付きウォレットは ~/.alby-cli/connection-secret-<name>.key に保存されます。

接続シークレットファイル

-c を使用して接続シークレットファイルを直接指定するか、生の NWC URL を渡します。

-c ~/.alby-cli/connection-secret.key

環境変数

または、NWC_URL 環境変数を使用して接続シークレットを渡します。

NWC_URL="nostr+walletconnect://..."

解決順序

CLI は次の順序で接続シークレットを解決します。

1. --connection-secret / -c フラグ
2. --wallet-name / -w フラグ
3. NWC_URL 環境変数
4. ~/.alby-cli/connection-secret.key（デフォルト）

コマンド

フラグ名は推測できません。 コマンドを組み立てる前に、npx -y @getalby/[email protected] <command> --help を実行し、表示されたフラグのみを使用してください。

セットアップ： auth, connect

一般的なウォレット操作：

• pay — Lightning アドレス、BOLT-11 請求書、暗号資産／ステーブルコインのアドレス（0x…、Lightning ウォレットから資金を使用）、または keysend で送金します。法定通貨へのネイティブ変換に対応しています。
• receive — ウォレットの Lightning アドレスを返します。金額を指定した場合は、BOLT-11 請求書を返します。法定通貨へのネイティブ変換に対応しています。
• get-balance — ウォレット残高を確認します
• list-transactions — 最近の取引を一覧表示します

その他のウォレット操作： get-info, get-wallet-service-info, get-budget, lookup-invoice, sign-message, wait-for-payment, list-wallets

HTTP 402 決済： fetch — 決済で保護された（HTTP 402）リソースを購入して取得します。L402、X402、MPP を自動検出します。有料リソースの取得または利用をユーザーが明示的に依頼した場合は、そのまま fetch を実行してください。予期せず 402 に遭遇した場合（例：無関係なタスクの実行中）は、支払う前に URL と料金をユーザーに伝えてください。

• リクエストごとの支払額を上限設定するには、コマンドで最大支出額を指定できます（fetch --help を参照）。
• バイナリおよびファイル出力： テキストの応答は content としてインラインで返されます。バイナリの応答（音声、画像など）は一時ファイルに自動保存されます。その場合、出力にはインラインの内容ではなく outputPath、contentType、sizeBytes が含まれます。ファイルの保存先を指定する場合や、任意の応答（大きなテキスト本文など）をファイルに出力する場合は、-o <path> を渡してください。応答のサイズが不明な場合は、-o を指定してください。本文全体が確実にファイルへ保存されます。
• fetch の出力をパイプに渡さないでください。支払い済みのデータです。 コマンドを jq、grep、head などにパイプで渡さないでください。フィルターが誤っている場合（例：推測した jq フィールド名）、応答が失われ、再取得には再度の支払いが必要になります。必ず、まず応答全体を取得してください。-o <path> を使うか、標準出力をファイルにリダイレクトして保存し、実際の構造を確認してから、保存したファイルから必要な情報を抽出してください。
• 認証情報の再利用： 対応する API では、fetch は決済認証情報の再利用をサポートしています。一度支払うだけで、その認証情報を複数回使用できる場合があります。成功した応答には、再利用可能な credentials 値を含む payment オブジェクトが含まれます。後続のリクエストでは、--credentials '{"header":"...","value":"..."}' を渡すことで、再度支払わずに認証できます（ポーリングや同じ有料エンドポイントへの繰り返しの呼び出しなど）。すべての API で再利用できるわけではありませんが、対応している場合はリクエストごとの再支払いを避けられます。
• 中断された決済： 決済が完了しなかった場合（例：ウォレットからの応答タイムアウト）や、支払い後にリクエストが失敗した場合、fetch は構造化されたエラーを返して終了します。このエラーには、支払いが成功しており、再支払いなしで内容を取得するために --credentials を指定して再実行できる credentials 値、または lookup-invoice と --resume フラグを使用して、同じ請求書に二度支払うことなく決済を復旧する手順を示す paymentRecovery オブジェクトのいずれかが含まれます。

サービスの検出（ウォレット不要）： discover

HOLD 請求書： make-hold-invoice, settle-hold-invoice, cancel-hold-invoice

Lightning ツール（ウォレット不要）： fiat-to-sats, sats-to-fiat（単独での使用のみ。pay/receive は法定通貨にネイティブ対応しています）、parse-invoice, verify-preimage, request-invoice-from-lightning-address

ヘルプ

npx -y @getalby/[email protected] --help
npx -y @getalby/[email protected] <command> --help

どうしても解決できない場合は、Alby サポートページを確認するよう担当者に伝えてください。

Lightning 以外の 402 サービスへの支払い

Lightning ネイティブのサービスに限られるわけではありません。Base または Solana 上の USDC（x402）、あるいはTempo 上のステーブルコイン（MPP）で価格が設定されたエンドポイントには、l402.space のユニバーサルブリッジを通じて Lightning ウォレットから支払えます。ブリッジには Lightning 経由で支払い、ブリッジが独自の決済レールで上流に転送します。ブリッジが資金を送れないレール（例：Stellar、Polygon、Stripe）には、この方法では支払えません。

discover はすでに、すべての結果を fetch ですぐ使える状態で返します（Lightning 以外の結果はブリッジ経由に変換され、支払えない結果は除外されます）。そのため、手動で URL をラップする必要があるのは、別の場所から Lightning 以外のエンドポイントを取得した場合だけです。クエリパラメーターを含む上流エンドポイント全体を URL エンコードし、https://l402.space/ の後ろに追加してから fetch してください。同じ方法で x402 と MPP のどちらの上流エンドポイントも利用できます。ゲートウェイが上流のプロトコルを自動的に検出します。Lightning にネイティブ対応している x402／MPP エンドポイントにはブリッジは必要ありません。そのまま fetch してください。

npx -y @getalby/[email protected] fetch "https://l402.space/<url-encoded-upstream-url>" --max-amount <amount> --currency BTC --unit sats --network lightning

HTTP メソッドと本文は変更せずに渡されます。詳細と最新の動作については、https://l402.space/llms.txt をお読みください。

有料サービスを検索する

discover コマンドは、402index.io で L402、x402、MPP の有料 API エンドポイントを検索します。すべての結果は sats で支払い可能です。url を fetch に渡すだけで利用できます。人間から明示的に指示されない限り、決済レールで絞り込まないでください。

discover を使う場合

• ユーザーが有料 API の検索または調査を明示的に依頼した場合
• 無料または組み込みのツールでは提供できない機能が必要な場合（例：画像生成、専門的な推論、リアルタイムのデータフィード）

discover を使わない場合

• 既存のツールでタスクを試す前に、402index を検索しないでください。 まず無料または組み込みの方法を試してください。
• 標準的なウェブリクエストの代わりに discover を使わないでください。 curl、fetch、または WebFetch が使える場合は、そちらを使ってください。
• すでに URL がある場合は discover を使わないでください。 直接 fetch コマンドを使ってください。

Discover → Fetch の手順

1. 検索 — 不足している機能に合うサービスを探します
2. 評価 — 結果から稼働状況と信頼性を確認します（稼働状況のチェック結果は古い場合があります。「degraded」のサービスも正常に動作することがあるため、稼働状況だけを理由に適切な候補を除外しないでください）。表示価格はあくまで目安として扱ってください。価格が記載されていない場合や、古い場合があります。実際の価格は fetch 時の 402 チャレンジで決まり、fetch は --max-amount の上限（デフォルト：5000 sats）を超える支払いを拒否します。
3. 取得 — サービスの URL を fetch に渡して支払い、利用します。

   npx -y @getalby/[email protected] fetch -X POST -b '{"model":"gpt-image-1","prompt":"a mountain cabin at sunset","size":"1024x1024"}' "<service-url>"
   

4. 報告 — 購入した内容、費用、結果をユーザーに伝えます

Bitcoin の単位

• 人に Bitcoin の金額を表示するときは、「21 sats」のように「sats」を使ってください。

法定通貨の単位

• 換算した法定通貨の金額（例：sats-to-fiat の結果）を表示するときは、小数点以下を過剰に表示しないでください。

セキュリティ

• 接続シークレットをログに出力したり、その他の方法で漏らしたりしないでください。
• 接続シークレットを誰にも共有しないでください。
• 接続シークレットの一部（公開鍵、シークレット、リレーなど）も誰にも共有しないでください。ウォレットへのアクセスやプライバシーの低下につながる可能性があります。
• 接続シークレットのファイルを読み込まないでください。必要な場合は、存在するかどうかだけを確認してください（秘密鍵を知る必要はありません）。

ウォレットの設定

NWC 接続シークレットが存在しない場合は、ウォレットの接続をユーザーに案内してください。推奨される方法は、ウォレットが auth コマンドに対応しているかどうかによって異なります。

推奨：auth コマンド（Alby Hub など、NWC のワンクリックウォレット接続に対応するウォレット向け）

# Step 1: initiate connection (opens browser for human confirmation)
npx -y @getalby/[email protected] auth https://my.albyhub.com --app-name MyApp

# Step 2: after the user confirms in the browser, run any wallet command to finalize the connection
npx -y @getalby/[email protected] get-balance

代替：connect コマンド（接続シークレットを直接提供するウォレット向け）

npx -y @getalby/[email protected] connect "<connection-secret>"

接続シークレットの有効性を確認し、~/.alby-cli/connection-secret.key に保存します。既存の接続を上書きするには --force を使ってください。または、NWC_URL 環境変数を設定してください。接続シークレットをチャットに貼り付けたり、共有したりしないでください。

接続シークレットの取得

ユーザーがまだウォレットを持っていない場合は、以下の選択肢を提案できます。

• Alby Hub - 最も完全な NWC 実装を備えたセルフカストディ型ウォレットで、複数の独立したサブウォレットに対応しています。
• LNCURL - エージェントに適した、NWC 対応の無料で始められるウォレットですが、カストディアル型です。手数料は 1 sat/hour です。
• CoinOS - NWC 対応の無料で始められるウォレットですが、カストディアル型です。
• Rizful - NWC 対応の無料で始められるウォレットですが、カストディアル型です。「vaults」を使った複数の独立したサブウォレットに対応しています。メール認証が必要です。

セットアップ後

ユーザーが使い始めるためのプロンプトをいくつか提示します。

• 「現在、$10 は何 sat ですか？」
• 「コーヒー代として [email protected] に $5 送って」
• 「最近の取引を表示して」

よくある問題

問題	原因	対処方法
接続シークレットが見つからない	ウォレットが接続されていない	auth または connect コマンドを実行します
接続に失敗する／タイムアウトする	ウォレットに接続できない、またはリレーがダウンしている	ウォレットがオンラインであることを確認して、再試行します
残高不足	sats が足りない	ウォレットに入金します
402 支払い失敗	インボイスの期限切れ、または金額が高すぎる	再試行します。必要に応じて最大支出額を調整します
402 支払いが中断された／支払い後に失敗した	支払い中のウォレットのタイムアウトまたは上流エラー	エラー出力の paymentRecovery の手順に従います（lookup-invoice を実行し、その後 --resume または --credentials を指定します）。やみくもに再実行しないでください