Lobster Cash CLI 技能

Lobster Cash CLI（lobstercash）为 AI 代理提供支付能力——包括区块链钱包、用于在线购物的虚拟卡、可选的云端浏览器自动化功能（用于浏览网站并完成结账流程），以及对 x402 协议的支持（用于向 API 支付费用）——所有操作均在人工审批闭环内执行。使用 lobstercash --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. 你在列表中看到自己，但未标注为 active → 运行 lobstercash agents set-active （使用匹配的 ID），然后继续。
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 --description "" 补充资金，展示审批 URL，等待用户确认后继续。
• 钱包未配置 → 运行 lobstercash crypto request --amount --description ""（该命令将同时完成钱包创建与资金充值）。展示审批 URL，等待用户确认，再通过 lobstercash status 验证后继续。

--description 必须明确说明 agent 将用这笔资金做什么——应从用户任务中推导得出，而非使用“充值钱包”等泛泛而谈的描述。

详见 crypto request 参考文档中完整的资金申请流程。

步骤 2：调用付费接口

lobstercash crypto x402 fetch 

对于 POST 请求，请添加 --json '{"key": "value"}'；对于自定义请求头，请添加 --header "Authorization: Bearer "。

步骤 3：报告结果

报告 API 返回的内容（即 body 字段），而非支付机制细节。仅当用户主动询问时，才提及支付相关信息。

若请求失败，请添加 --debug 参数重试。详见 x402 参考文档中关于输出格式及常见错误的说明。

C) 其他操作

对于其余所有操作——查询余额、发送加密货币、查看钱包状态、绑定钱包或浏览示例——请使用下方快速参考中的对应命令，并查阅相应参考文档获取详细说明。

执行命令，并如实报告其输出。 对于只读命令（如 crypto balance、status、examples），可直接执行并报告其输出内容。请勿预先检查状态并自行构造摘要——CLI 输出本身已针对未配置状态提供了清晰提示。若某命令因退出码 2（钱包未设置）而失败，请告知用户并主动提供运行 lobstercash setup 或对应的一体化设置命令的选项。

常用操作：

• 查询余额： lobstercash crypto balance → balance 参考文档
• 发送代币： lobstercash crypto send --to --amount --token usdc → send 参考文档
• 查看钱包状态： lobstercash status → status 参考文档
• 浏览示例： lobstercash examples → examples 参考文档
• 绑定钱包 / 配置 agent（仅限设置阶段）： lobstercash setup → setup 参考文档。当用户提出“配置”、“设置”、“绑定钱包”等类似需求（且不涉及购买行为）时使用。
• 签名/提交交易： lobstercash crypto tx create → tx 参考文档

对于加密货币操作（crypto send、crypto tx create），请始终先运行 lobstercash status 确认钱包已配置且资金充足。否则，请使用 lobstercash crypto request --amount --description "" 进行充值——详见 crypto request 参考文档。

快速参考

lobstercash agents register --name "" --description "" --image-url ""  # 注册新 agent
lobstercash agents list                                          # 列出全部 agent
lobstercash agents set-active                           # 设置活跃 agent
lobstercash config get browser-enabled                           # 检查在线购买时由哪个浏览器驱动（见 A 节）
lobstercash examples                                             # 浏览可用示例
lobstercash status                                               # 检查状态、就绪情况与钱包地址
lobstercash setup                                                # 将 agent 绑定至钱包（无需购买）
lobstercash crypto balance                                       # 查询余额
lobstercash crypto send --to  --amount  --token usdc    # 发送代币
lobstercash crypto x402 fetch                               # 为 API 付款
lobstercash crypto request --amount  --description ""    # 申请加密货币资金 / 充值（含钱包设置）
lobstercash crypto tx create|approve|status                      # 底层交易管理
lobstercash cards request --amount  --description ""     # 申请虚拟卡（单次使用；订阅/--period 功能即将上线）
lobstercash cards list                                           # 列出卡片（含 card-id、phase、mandates）——在两种购买流程中均用于检查是否存在可复用的卡片
lobstercash cards reveal --card-id  --merchant-name "..." --merchant-url "https://..." --merchant-country US  # 结账凭证（供 BYO 浏览器流程及手动结账使用）

purchase explore 和 purchase run 命令仅在配置了 browser-enabled: true 时存在——详见相关 purchase-flow 参考文档中的用法说明。

输出契约

• 所有命令均向 stdout 输出人类可读的结果。
• 错误信息以纯文本形式输出至 stderr。
• 退出码 0 = 成功；退出码 1 = 意外错误；退出码 2 = 钱包未设置（请使用 cards request 或 crypto request 进行设置）。

决策树

• 若用户希望浏览可用示例，或尚无明确任务 → 查阅 examples
• 若用户询问 agent 状态或支付就绪情况 → 查阅 status
• 若用户希望查询代币余额 → 查阅 balance
• 若用户希望在线购买商品且 browser-enabled: true → 查阅 purchase-flow（使用 Lobster Cash 内置浏览器自动化功能的完整流程）
• 若用户希望在线购买商品且 browser-enabled: false → 查阅 purchase-flow-byo（流程相同，但由 agent 使用自有工具驱动浏览器）
• 若需 purchase explore / purchase run 的参数级参考（仅限 browser-enabled 场景）→ 查阅 purchase
• 若用户希望为购买创建新虚拟卡 → 查阅 cards request
• 若用户希望申请 USDC、为钱包充值或为加密货币操作筹资 → 查阅 crypto request
• 若用户需要列出已有卡片、揭示凭证或检查某张卡是否可用于重复购买 → 查阅 cards
• 若用户希望向地址发送代币（Crypto Path）→ 查阅 send
• 若用户希望通过 x402 协议为 API 付款（Crypto Path）→ 查阅 x402
• 若用户需要从外部工具签名或提交交易（Crypto Path）→ 查阅 tx
• 若用户希望在不进行购买的前提下将 agent 绑定至钱包 → 查阅 setup
• 若用户希望注册、列出或设置活跃 agent → 查阅 agents

反模式

• 在线购买前跳过浏览器可用性检查： 不要假设适用哪种购买流程。当用户希望在线购买时，务必首先运行 lobstercash config get browser-enabled（见 A 节），再决定加载哪份 purchase-flow 参考文档。该配置项决定了是使用 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： 若用户意在购买，请勿先行运行 setup —— 应使用 cards request 或 crypto request，它们会自动集成设置流程。仅当用户明确表示希望在不购买的前提下将 agent 绑定至钱包时，才使用 lobstercash setup。
• agent 已配置时重复运行 setup： 若 lobstercash status 显示钱包已配置，请勿生成新的 setup 会话。现有配置有效。仅当用户明确告知当前配置损坏并需重建时，才启动全新 setup。
• 向用户索取 CLI 可自行获取的信息： 发送前先查余额；操作前先查状态；阅读命令输出后再提问。
• 循环执行写入类命令： 一次尝试，读取结果，再做决策。读取类操作（crypto balance、status、examples）具有幂等性，可安全重复；写入类操作（crypto send、cards request）则不可。
• 忽略终端状态： 交易处于 pending 状态 ≠ 成功。所有写入类命令默认等待链上确认。
• 轮询 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 Path。唯一分支在于信用卡 vs 加密货币。
• 用户仅希望连接时即推荐 crypto request 或 cards request： 若用户仅想查询余额、运行加密货币命令或简单绑定钱包（无需充值或创建卡片），请先引导其完成 lobstercash setup。除非用户确实希望为钱包充值或进行购买，否则不要直接跳转到 crypto request 或 cards request。
• 在展示选项前急于执行就绪检查： 首先展示可用选项（通过 examples），仅当用户希望尝试某项时，再检查支付就绪情况。
• 主观臆断集成的支付方式： 切勿猜测某流程使用信用卡还是加密货币。请运行 lobstercash status 并阅读输出中的支付方式列表，再选择对应路径。