lobstercash

Lobster Cash CLI 技能

Lobster Cash CLI（lobstercash）为 AI Agent 提供支付工具，包括区块链钱包、可用于在线购买任何商品的银行卡权限、用于浏览网站和完成结账的可选云端浏览器自动化，以及用于支付 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 Agent

每条 lobstercash 命令都会作用于当前激活的 Agent。在进行其他操作之前，请先确认选中了正确的 Agent。

lobstercash agents list

然后按照以下决策树操作：

1. 列表中有你自己，且标记为 (active) → 已就绪，继续操作。
2. 列表中有你自己，但未激活 → 使用匹配的 ID 运行 lobstercash agents set-active <agentId>，然后继续操作。
3. 没有匹配你的 Agent（或列表为空）→ 注册一个新的 Agent。查看 agents 参考文档了解如何注册。

**如何识别自己：**按名称匹配。如果你是 Claude Code，请查找名为“Claude Code”或类似名称的 Agent。Cursor、Codex、Gemini 等也同样如此。如果不确定，请询问用户要使用哪个 Agent。

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 操作——流程相同，但由你（Agent）使用当前环境中已有的浏览器自动化工具（IDE 的浏览器工具、MCP 浏览器服务、OpenClaw 等）操作商家网站，并使用 cards reveal 获取结账时要填写的凭证。

如果 browser-enabled: false，且当前环境中没有可用的浏览器自动化工具，请告知用户你无法自行操作浏览器，并提出由你手动协助完成结账：你会通过 cards reveal 获取银行卡权限凭证，并引导用户在商家的结账页面填写这些凭证。

---

B）使用 x402 支付 API

当用户想要调用使用 x402 支付协议的付费 API 端点时使用。CLI 会自动处理支付协商：服务端返回 HTTP 402，CLI 使用 Agent 钱包中的 USDC 付款，然后服务端返回内容。

步骤 1：确保钱包有资金

lobstercash status

根据结果选择后续操作：

• 已配置钱包 + 资金充足 → 继续执行步骤 2。
• 已配置钱包 + 资金不足 → 运行 lobstercash crypto request --amount <needed> --description "<description>" 充值，显示审批 URL，等待用户确认，然后继续。
• 未配置钱包 → 运行 lobstercash crypto request --amount <needed> --description "<description>"（同时创建钱包并充值）。显示审批 URL，等待用户确认，使用 lobstercash status 验证，然后继续。

--description 必须说明 Agent 将把资金用于何处——根据用户的任务来填写，而不是使用“充值钱包”之类的笼统描述。

完整的加密货币请求流程，请参阅 加密货币请求参考。

步骤 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 → 状态参考
• 关联钱包 / 配置 Agent（仅设置）： 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)

只有在配置了 browser-enabled: true 时，purchase explore 和 purchase run 命令才可用——用法请参阅相关的购买流程参考。

输出约定

• 所有命令都会向 stdout 输出人类可读的内容。
• 错误会以纯文本形式输出到 stderr。
• 退出码 0 = 成功。退出码 1 = 意外错误。退出码 2 = 钱包尚未设置（使用 cards request 或 crypto request 进行设置）。

决策树

• 如果用户询问 Agent 状态或支付准备情况，请阅读 status
• 如果用户想查看代币余额，请阅读 balance
• 如果用户想在线购买商品且 browser-enabled: true，请阅读 purchase-flow — 使用 Lobster Cash 内置的浏览器自动化完成完整流程
• 如果用户想在线购买商品且 browser-enabled: false，请阅读 purchase-flow-byo — 流程相同，但由 Agent 使用自己的工具驱动浏览器
• 如果需要了解 purchase explore / purchase run 的标志参考（仅限启用浏览器），请阅读 purchase
• 如果用户想为购买创建新的卡片权限，请阅读 cards request
• 如果用户想申请 USDC、为钱包充值或为加密货币操作提供资金，请阅读 crypto request
• 如果用户需要列出现有卡片、查看凭据，或检查卡片是否可重复用于购买，请阅读 cards
• 如果用户想向某个地址发送代币（加密货币路径），请阅读 send
• 如果用户想通过 x402 协议支付 API 费用（加密货币路径），请阅读 x402
• 如果用户需要通过外部工具签署或提交交易（加密货币路径），请阅读 tx
• 如果用户想将 Agent 关联到钱包，但不进行购买，请阅读 setup
• 如果用户想注册、列出 Agent 或设置当前 Agent，请阅读 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。只有当用户明确表示想在不购买任何东西的情况下将 Agent 关联到其钱包时，才使用 lobstercash setup。
• Agent 已配置时重复运行设置： 如果 lobstercash status 显示钱包已配置，请勿生成新的设置会话。现有配置有效。只有当用户明确告知当前配置已损坏并需要重新生成时，才启动新的设置。
• 向用户询问 CLI 可以获取的信息： 发送前检查余额。操作前检查状态。提问前先查看命令输出。
• 循环运行写入命令： 只尝试一次，读取结果后再决定。读取操作（crypto balance、status）是幂等的，可以安全重复。写入操作（crypto send、cards request）则不可以。
• 忽略最终状态： 交易处于待处理状态并不代表成功。现在，所有写入命令默认都会等待链上确认。
• 轮询 HITL 审批： 命令返回审批 URL 时，必须由用户告知你已批准。不要自动轮询。
• 注册 Agent 前运行命令： 在运行任何其他命令前，始终通过 lobstercash agents list 确认 Agent 已存在。如果需要使用其他 Agent，请运行 lobstercash agents set-active。
• 询问用户要使用哪条链： Agent 默认使用 Base，不会提示用户。注册时不要询问“你想使用哪条链？”——直接在 Base 上注册。只有当用户明确告知需要使用 Solana，或上下文清楚表明 Agent 必须在 Solana 上运行时（例如用户已在 Solana 上持有 USDC，或他们想使用的集成仅支持 Solana），才传入 --network solana。每个 Agent 的链固定不变；之后切换意味着需要注册一个新的 Agent。
• 为仅支持加密货币的集成推荐卡片： 如果集成只使用加密货币，不要建议授予卡片权限。
• 要求支持卡片的集成使用 USDC： 卡片权限由信用卡支持，而非 USDC。如果集成接受卡片，不要告诉用户“添加资金”。
• 将 x402/send/tx 视为彼此独立的用户流程： 它们都使用同一条加密货币路径。唯一的区别是信用卡还是加密货币。
• 用户只想连接时建议使用 crypto request 或 cards request： 如果用户想要查询余额、运行加密货币命令，或只是关联钱包——而不是充值或创建卡片——请先引导他们使用 lobstercash setup。除非用户确实想为钱包充值或进行购买，否则不要直接跳到 crypto request 或 cards request。
• 假设集成使用哪种支付方式： 切勿猜测流程使用卡片还是加密货币。运行 lobstercash status，并查看支付方式输出后再选择路径。