lobstercash

Lobster Cash CLI スキル

Lobster Cash CLI（lobstercash）は、AI エージェントに決済ツールを提供します。ブロックチェーンウォレット、オンラインであらゆるものを購入するためのカード権限、サイトの閲覧やチェックアウト完了に使用できるオプションのクラウドブラウザー自動化、API の支払いに対応する x402 プロトコルを利用でき、すべての操作に人間の承認が介在します。任意のコマンドのフラグの詳細は、lobstercash <command> --help で確認してください。

インストール

グローバルにインストールします。

npm install -g @crossmint/lobster-cli

インストール後は、すべてのコマンドを lobstercash バイナリから利用できます。

このスキルの使い方

1. バージョン確認（自動）

CLI は API 呼び出しのたびに更新を自動で確認します。コマンドの出力に更新通知が表示された場合は、ユーザーに伝え、npm update -g @crossmint/lobster-cli の実行を提案してください。通知に更新が必須と記載されている場合は、続行する前に https://www.lobster.cash/install からスキルも更新する必要があります。バージョン確認専用のコマンドは実行しないでください。

2. 使用する lobstercash エージェントを選択

すべての lobstercash コマンドはアクティブなエージェントに対して実行されます。他の操作を行う前に、適切なエージェントが選択されていることを確認してください。

lobstercash agents list

次に、以下の判断フローに従ってください。

1. 一覧に自分が表示され、(active) と書かれている → 問題ありません。次に進んでください。
2. 一覧に自分が表示されているが、アクティブではない → 該当する ID を指定して lobstercash agents set-active <agentId> を実行し、次に進んでください。
3. 自分に該当するエージェントがない（または一覧が空） → 新しいエージェントを登録してください。登録方法についてはエージェントのリファレンスを参照してください。

自分を特定する方法： 名前で照合してください。Claude Code の場合は、「Claude Code」または類似する名前のエージェントを探します。Cursor、Codex、Gemini なども同様です。判断できない場合は、どのエージェントを使うかユーザーに尋ねてください。

3. ユーザーの意図に応じて振り分ける

該当するシナリオを判断し、対応するセクションに従ってください。

• A）オンラインで何かを購入する（商品、サブスクリプション、ドメイン、サービス） → オンラインで何かを購入する
• B）有料 API エンドポイントの料金を支払う（x402 プロトコル） → x402 で API の料金を支払う
• C）その他（残高確認、暗号資産の送金、ステータスの表示、ウォレットのリンク） → その他の操作

---

A）オンラインで何かを購入する

ユーザーが商品、サブスクリプション（現時点ではまだ利用できませんが、近日対応予定です）、ドメイン、またはオンラインストアの商品を購入したい場合に使用します。商品と価格を確認し、カード権限を適切な金額に設定してから、ブラウザーでチェックアウトを進める流れはどの場合も同じです。このインストールで異なるのは、誰がブラウザーを操作するかです。次を実行してください。

lobstercash config get browser-enabled

• browser-enabled: true → Lobster Cash に組み込まれたブラウザー自動化（purchase explore / purchase run）が、販売サイトを操作します。references/purchase-flow.md に従ってください。
• browser-enabled: false → このインストールでは Lobster Cash に組み込まれたブラウザー自動化を利用できません。purchase explore または purchase run は実行しないでください。references/purchase-flow-byo.md に従ってください。流れは同じですが、利用環境で使用できるブラウザー自動化ツール（IDE のブラウザーツール、MCP ブラウザーサーバー、OpenClaw など）を使って、あなた（エージェント）が販売サイトを操作し、チェックアウト時に入力する認証情報は cards reveal で取得します。

browser-enabled: false で、利用環境にブラウザー自動化ツールがない場合は、自分ではブラウザーを操作できないことをユーザーに伝え、チェックアウトを手動で進めることを提案してください。cards reveal でカード権限の認証情報を取得し、販売サイトのチェックアウトページでユーザー自身が入力できるよう案内します。

---

B）x402 で API の料金を支払う

ユーザーが x402 決済プロトコルを使用する有料 API エンドポイントを呼び出したい場合に使用します。CLI は決済のネゴシエーションを自動で処理します。サーバーが HTTP 402 を返すと、CLI はエージェントのウォレットから USDC で支払い、サーバーはコンテンツを返します。

ステップ 1：ウォレットに資金があることを確認する

lobstercash status

結果に応じて、次のように進めます。

• ウォレットが設定済みで、十分な資金がある → ステップ 2 に進みます。
• ウォレットが設定済みだが、資金が不足している → lobstercash crypto request --amount <needed> --description "<description>" を実行してチャージし、承認 URL を表示してユーザーの確認を待ってから、次に進みます。
• ウォレットが設定されていない → lobstercash crypto request --amount <needed> --description "<description>" を実行します（ウォレットの作成と入金をまとめて行います）。承認 URL を表示してユーザーの確認を待ち、lobstercash status で確認してから、次に進みます。

--description には、エージェントが資金を何に使うのかを記載する必要があります。「ウォレットにチャージ」のような一般的な文言ではなく、ユーザーのタスクをもとに内容を決めてください。

暗号資産のリクエストフローの詳細については、暗号資産リクエストのリファレンスを参照してください。

ステップ 2：有料エンドポイントを取得する

lobstercash crypto x402 fetch <url>

POST リクエストには --json '{"key": "value"}' を追加してください。カスタムヘッダーには --header "Authorization: Bearer <token>" を追加してください。

ステップ 3：結果を報告する

決済の仕組みではなく、API が返した内容（body フィールド）を報告してください。ユーザーから尋ねられた場合に限り、決済について説明してください。

取得に失敗した場合は、--debug を追加して再実行してください。出力形式とよくある失敗については、x402 のリファレンスを参照してください。

---

C）その他の操作

残高の確認、暗号資産の送金、ウォレットの状態の確認、ウォレットのリンクなど、その他の操作には、以下のクイックリファレンスから該当するコマンドを使用し、詳細については対応するリファレンスファイルを読んでください。

コマンドを実行し、その出力を報告してください。 読み取り専用コマンド（crypto balance、status）は直接実行し、出力内容を報告してください。事前に状態を確認して独自の要約を作成しないでください。CLI の出力には、未設定の場合の状態も明確に表示されます。コマンドが終了コード 2（ウォレット未設定）で失敗した場合は、その旨をユーザーに伝え、lobstercash setup または該当するセットアップをまとめて行うコマンドの実行を提案してください。

よくある操作：

• 残高を確認する： lobstercash crypto balance → 残高のリファレンス
• トークンを送金する： lobstercash crypto send --to <addr> --amount <n> --token usdc → 送金のリファレンス
• ウォレットの状態を確認する： lobstercash status → 状態のリファレンス
• ウォレットをリンクする／エージェントを設定する（セットアップのみ）： lobstercash setup → セットアップのリファレンス。ユーザーが購入をしようとしているのではなく、「設定」「セットアップ」「ウォレットをリンク」などと言った場合に使用してください。
• トランザクションに署名する／送信する： lobstercash crypto tx create → トランザクションのリファレンス

暗号資産の操作（crypto send、crypto tx create）では、必ず最初に lobstercash status を実行し、ウォレットが設定済みで十分な資金があることを確認してください。そうでない場合は、資金を入れるために lobstercash crypto request --amount <needed> --description "<description>" を使用してください。詳細は暗号資産リクエストのリファレンスを参照してください。

クイックリファレンス

lobstercash agents register --name "<name>" --description "<desc>" --image-url "<url>"  # register a new agent
lobstercash agents list                                          # list all agents
lobstercash agents set-active <agentId>                          # set active agent
lobstercash config get browser-enabled                           # check which browser drives online purchases (used in Section A)
lobstercash status                                               # check status & readiness & wallet address
lobstercash setup                                                # link agent to wallet (no purchase needed)
lobstercash crypto balance                                       # check balances
lobstercash crypto send --to <addr> --amount <n> --token usdc    # send tokens
lobstercash crypto x402 fetch <url>                              # pay for API
lobstercash crypto request --amount <n> --description "<desc>"    # request crypto funding / top up (bundles wallet setup)
lobstercash crypto tx create|approve|status                      # low-level transaction management
lobstercash cards request --amount <n> --description "<desc>"     # request card permission (single-use; subscriptions/--period coming soon)
lobstercash cards list                                           # list cards (includes card-id, phase, mandates) — used in both purchase flows to check for a reusable card
lobstercash cards reveal --card-id <id> --merchant-name "..." --merchant-url "https://..." --merchant-country US  # checkout credentials (used by the BYO browser flow, and for manual checkout)

purchase explore および purchase run コマンドは、browser-enabled: true が設定されている場合にのみ使用できます。使い方については、該当する購入フローのリファレンスを参照してください。

出力の仕様

• すべてのコマンドは、人が読みやすい形式の出力を stdout に返します。
• エラーはプレーンテキストで stderr に出力されます。
• 終了コード 0 = 成功。終了コード 1 = 想定外のエラー。終了コード 2 = ウォレット未設定（セットアップには cards request または crypto request を使用してください）。

意思決定ツリー

• エージェントのステータスや支払い準備状況についてユーザーから尋ねられた場合は、statusを読みます
• トークン残高を確認したい場合は、balanceを読みます
• browser-enabled: trueで、オンラインで何かを購入したい場合は、purchase-flowを読みます。Lobster Cashに組み込まれたブラウザー自動化を使った一連のフローです
• browser-enabled: falseで、オンラインで何かを購入したい場合は、purchase-flow-byoを読みます。同じフローですが、エージェントが独自のツールでブラウザーを操作します
• purchase explore／purchase runのフラグレベルのリファレンスが必要な場合は、purchaseを読みます（ブラウザー有効時のみ）
• 購入用の新しいカード権限を作成したい場合は、cards requestを読みます
• USDCのリクエスト、ウォレットへの入金、または暗号資産関連の操作への資金提供をしたい場合は、crypto requestを読みます
• 既存のカードの一覧表示、認証情報の表示、または購入にカードを再利用できるかの確認が必要な場合は、cardsを読みます
• アドレスにトークンを送信したい場合は、sendを読みます（暗号資産パス）
• x402プロトコル経由でAPIの支払いをしたい場合は、x402を読みます（暗号資産パス）
• 外部ツールからトランザクションに署名または送信する必要がある場合は、txを読みます（暗号資産パス）
• 購入せずにエージェントをウォレットにリンクしたい場合は、setupを読みます
• エージェントを登録、一覧表示、またはアクティブなエージェントに設定したい場合は、agentsを読みます

アンチパターン

• オンライン購入の前にブラウザーの利用可否を確認しないこと： どの購入フローが適用されるかを決めつけないでください。ユーザーがオンラインで何かを購入したい場合は、どの購入フローのリファレンスを読み込むか決める前に、必ず最初に lobstercash config get browser-enabled を実行してください（セクション A）。このフラグによって、purchase explore / purchase run を使うか、認証情報を取得するために cards reveal を使ってブラウザーを自分で操作するかが決まります。
• browser-enabled: false のときに purchase explore / purchase run を実行すること： これらのコマンドには組み込みのブラウザー自動化が必要です。フラグが false の場合は、代わりに references/purchase-flow-byo.md に従ってください。
• 最初にステータスを確認せずに暗号資産コマンドを実行すること： crypto send、crypto x402 fetch、または crypto tx create の前に、必ず lobstercash status を実行してください。ウォレットが設定されていない場合や残高が不足している場合、コマンドは分かりにくいエラーで失敗します。最初に確認し、必要に応じて入金してから実行してください。
• ユーザーが購入したいときにセットアップを実行すること： ユーザーが購入を希望している場合、最初に setup を実行しないでください。セットアップが自動的に含まれる cards request または crypto request を使ってください。lobstercash setup を使うのは、ユーザーが購入せずにエージェントをウォレットにリンクしたいと明示した場合だけです。
• エージェントの設定がすでに完了しているのに、セットアップを再実行すること： lobstercash status でウォレットがすでに設定済みと表示された場合、新しいセットアップセッションを生成しないでください。既存の設定は有効です。ユーザーが現在の設定は壊れており再生成が必要だと明示した場合に限り、新しいセットアップを開始してください。
• CLI で取得できる情報をユーザーに尋ねること： 送信する前に残高を確認してください。操作する前にステータスを確認してください。質問する前にコマンドの出力を読んでください。
• 書き込みコマンドをループで実行すること： 1 回試し、結果を読み、その後で判断してください。読み取り操作（crypto balance、status）はべき等であり、繰り返しても安全です。書き込み操作（crypto send、cards request）はそうではありません。
• 最終ステータスを無視すること： トランザクションが保留中であれば、成功ではありません。すべての書き込みコマンドは、デフォルトでオンチェーンの確認を待つようになりました。
• HITL 承認をポーリングすること： コマンドが承認 URL を返した場合、ユーザーが承認したと伝える必要があります。自動でポーリングしないでください。
• エージェントを登録する前にコマンドを実行すること： ほかのコマンドを実行する前に、lobstercash agents list でエージェントが存在することを必ず確認してください。別のエージェントを使用する必要がある場合は、lobstercash agents set-active を使ってください。
• 使用するチェーンをユーザーに尋ねること： エージェントは、通知なしに Base をデフォルトで使用します。登録時に「どのチェーンを使いますか？」と尋ねず、そのまま Base に登録してください。ユーザーが Solana を必要としていると明示した場合、または状況からエージェントが Solana 上で動作する必要があることが明らかな場合（例：ユーザーがすでに Solana 上に USDC を保有している場合や、希望する連携が Solana 専用の場合）に限り、--network solana を渡してください。チェーンはエージェントごとに固定されており、後から切り替えるには新しいエージェントを登録する必要があります。
• 暗号資産のみを使う連携にカードを勧めること： 連携が暗号資産のみを使う場合、カードの権限を提案しないでください。
• カードに対応する連携で USDC を必須とすること： カードの権限は USDC ではなく、クレジットカードによって裏付けられています。連携がカードに対応している場合、ユーザーに「資金を追加」するよう伝えないでください。
• x402/send/tx を別々のユーザーフローとして扱うこと： これらはすべて同じ Crypto Path を通ります。異なるのはクレジットカードか暗号資産かだけです。
• ユーザーが接続だけを希望しているのに crypto request または cards request を提案すること： ユーザーが残高の確認、暗号資産コマンドの実行、またはウォレットのリンクだけを希望しており、チャージやカードの作成を希望していない場合は、まず lobstercash setup の手順を案内してください。ユーザーが実際にウォレットへの入金または購入を希望している場合を除き、crypto request または cards request に飛びつかないでください。
• 連携の決済方法を決めつけること： フローがカードと暗号資産のどちらを使うか推測しないでください。lobstercash status を実行し、支払い方法の出力を読んでから、手順を選んでください。