{"id":"c6f437f2-6b03-4d5f-88d2-14ec66c56f2e","entityType":"agent","slug":"clawhub-manu-xmint-lobstercash","name":"lobstercash","canonicalUrl":"https://www.xpersona.co/agent/clawhub-manu-xmint-lobstercash","canonicalPath":"/agent/clawhub-manu-xmint-lobstercash","generatedAt":"2026-10-10T04:19:09.921Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:04:49.235Z","emptyReason":null},"description":"Use this skill when the user wants to spend money, make purchases, send crypto, pay for APIs, browse websites for shopping, complete checkout, or manage an A...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.9K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s176gxg53nmy7n4z5dq80hfst583h1en:lobstercash","sourceUrl":"https://clawhub.ai/manu-xmint/lobstercash","homepage":"https://clawhub.ai/manu-xmint/skills/lobstercash","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/manu-xmint/lobstercash","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/manu-xmint/skills/lobstercash","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":44,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"lobstercash technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:04:49.235Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:04:49.235Z","emptyReason":null},"stars":null,"forks":null,"downloads":1912,"packageName":null,"latestVersion":"0.0.16","tractionLabel":"1.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:04:49.235Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T23:04:49.235Z","lastCrawledAt":"2026-10-09T23:04:49.235Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T23:04:49.235Z","lastVerifiedAt":null,"highlights":[{"version":"0.0.16","createdAt":"2026-05-04T20:08:09.336Z","changelog":"- Added two new reference files: `references/purchase-flow.md` and `references/purchase-flow-byo.md`, providing detailed flows for online purchases depending on browser automation availability. - Updated the purchase flow documentation to branch based on whether the built-in browser automation is enabled (`browser-enabled: true`) or not. - Clarified instructions for scenarios where browser automation is not available, including guidance for agents to use their own browser tooling or guide the user through manual checkout. - Updated version to 0.0.16.","fileCount":18,"zipByteSize":38076},{"version":"0.0.15","createdAt":"2026-04-30T10:35:22.137Z","changelog":"lobstercash v0.0.15 - Adds explicit instruction to ensure the wallet is set up before running `purchase explore` or `purchase run`. - Clarifies to check wallet status with `lobstercash status` and, if needed, onboard with `lobstercash setup` and user approval before initiating purchase exploration. - Prevents premature wallet setup via `cards request` when price info isn't available. - Updates documentation for onboarding flow requirements before any browser-automated purchase action.","fileCount":15,"zipByteSize":30361},{"version":"0.0.14","createdAt":"2026-04-29T10:06:19.214Z","changelog":"lobstercash 0.0.14 - Automated online purchases are now always browser-based; manual checkout no longer supported. - Checkout flow updated: discover real product/price first, then create or reuse a virtual card, then run automated checkout. - Explicit instructions to gather customer details (address, contact) only if not already known; no redundant prompts. - Step-by-step matching logic for determining if an existing single-use card can be reused for a new purchase. - Subscription/recurring cards are not yet supported, but guidance added for future compatibility.","fileCount":15,"zipByteSize":30201},{"version":"0.0.13","createdAt":"2026-04-28T18:56:08.612Z","changelog":"- Added a new reference for purchase flows: `references/purchase.md` - Removed the browser-specific reference: `references/browser.md` - Updated product discovery guidance: directs users to use `lobstercash purchase explore` for finding real products and calculating totals, instead of navigating with browser CLI commands - Updated Step 3 under \"Buy something with a card\" to describe the new explore-based purchase flow, including how to initiate it and handle user input or responses - Emphasized using live explore navigation over inventing URLs, enhancing accuracy and replicating real buyer experience","fileCount":15,"zipByteSize":28059},{"version":"0.0.11","createdAt":"2026-04-23T13:56:28.204Z","changelog":"lobstercash v0.0.11 - Version metadata updated to 0.0.11. - No other functional or documentation changes detected.","fileCount":15,"zipByteSize":27644},{"version":"0.0.10","createdAt":"2026-04-22T23:30:45.079Z","changelog":"lobstercash 0.0.10 - The virtual card \"period\" parameter is now optional (was required). Cards default to single-use if period is not set. - Instructions updated: only ask the user about period if the purchase is clearly recurring and no period was specified. - Version bump to 0.0.10; no functional changes to commands beyond card period flag.","fileCount":15,"zipByteSize":27644},{"version":"0.0.9","createdAt":"2026-04-21T15:14:56.718Z","changelog":"lobstercash 0.0.9 - Added required --period flag to `cards request` (must specify weekly/monthly/yearly; prompt user if missing). - Updated deposit flow: replaced `crypto deposit` with `crypto request` throughout, and removed legacy deposit references. - Introduced a new reference for `crypto-request` and removed outdated `deposit.md`. - Improved documentation for funding the wallet and clarified steps for virtual card creation. - Miscellaneous documentation updates to references and examples.","fileCount":15,"zipByteSize":26830},{"version":"0.0.8","createdAt":"2026-04-14T10:15:36.184Z","changelog":"**Lobstercash v0.0.8 changelog:** - Major update: Adds browser automation for web shopping and checkout, restructures and expands workflow steps, and modernizes card and crypto payment flows. - Added support for cloud browser automation, including browsing, product discovery, and completing real checkout flows—never guess URLs; always use real, live data. - Replaced and renamed CLI commands and help references for improved clarity: e.g., `cards request`, `crypto deposit`, better separation between card and crypto actions. - Workflow instructions are now scenario-based (online shopping, API payments, and other wallet actions), making it easier to route intents correctly. - Removed obsolete files and commands relating to previous request flows; added new references for browser actions, cards, deposit, and practical examples. - Expanded guidance on agent selection, version checking, and user approval, with references to corresponding CLI commands and output formats.","fileCount":15,"zipByteSize":26512}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s176gxg53nmy7n4z5dq80hfst583h1en:lobstercash","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s176gxg53nmy7n4z5dq80hfst583h1en:lobstercash` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/manu-xmint/lobstercash before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-manu-xmint-lobstercash/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-manu-xmint-lobstercash/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-manu-xmint-lobstercash/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-manu-xmint-lobstercash/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-manu-xmint-lobstercash/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-manu-xmint-lobstercash/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T04:19:09.917Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-manu-xmint-lobstercash/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-manu-xmint-lobstercash/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-manu-xmint-lobstercash/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-manu-xmint-lobstercash/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:04:49.235Z","emptyReason":null},"readme":"Skill: lobstercash\n\nOwner: manu-xmint\n\nSummary: Use this skill when the user wants to spend money, make purchases, send crypto, pay for APIs, browse websites for shopping, complete checkout, or manage an A...\n\nTags: latest:0.0.16\n\nVersion history:\n\nv0.0.16 | 2026-05-04T20:08:09.336Z | user\n\n- Added two new reference files: `references/purchase-flow.md` and `references/purchase-flow-byo.md`, providing detailed flows for online purchases depending on browser automation availability.\n- Updated the purchase flow documentation to branch based on whether the built-in browser automation is enabled (`browser-enabled: true`) or not.\n- Clarified instructions for scenarios where browser automation is not available, including guidance for agents to use their own browser tooling or guide the user through manual checkout.\n- Updated version to 0.0.16.\n\nv0.0.15 | 2026-04-30T10:35:22.137Z | user\n\nlobstercash v0.0.15\n\n- Adds explicit instruction to ensure the wallet is set up before running `purchase explore` or `purchase run`. \n- Clarifies to check wallet status with `lobstercash status` and, if needed, onboard with `lobstercash setup` and user approval before initiating purchase exploration.\n- Prevents premature wallet setup via `cards request` when price info isn't available.\n- Updates documentation for onboarding flow requirements before any browser-automated purchase action.\n\nv0.0.14 | 2026-04-29T10:06:19.214Z | user\n\nlobstercash 0.0.14\n\n- Automated online purchases are now always browser-based; manual checkout no longer supported.\n- Checkout flow updated: discover real product/price first, then create or reuse a virtual card, then run automated checkout.\n- Explicit instructions to gather customer details (address, contact) only if not already known; no redundant prompts.\n- Step-by-step matching logic for determining if an existing single-use card can be reused for a new purchase.\n- Subscription/recurring cards are not yet supported, but guidance added for future compatibility.\n\nv0.0.13 | 2026-04-28T18:56:08.612Z | user\n\n- Added a new reference for purchase flows: `references/purchase.md`\n- Removed the browser-specific reference: `references/browser.md`\n- Updated product discovery guidance: directs users to use `lobstercash purchase explore` for finding real products and calculating totals, instead of navigating with browser CLI commands\n- Updated Step 3 under \"Buy something with a card\" to describe the new explore-based purchase flow, including how to initiate it and handle user input or responses\n- Emphasized using live explore navigation over inventing URLs, enhancing accuracy and replicating real buyer experience\n\nv0.0.11 | 2026-04-23T13:56:28.204Z | user\n\nlobstercash v0.0.11\n\n- Version metadata updated to 0.0.11.\n- No other functional or documentation changes detected.\n\nv0.0.10 | 2026-04-22T23:30:45.079Z | user\n\nlobstercash 0.0.10\n\n- The virtual card \"period\" parameter is now optional (was required). Cards default to single-use if period is not set.\n- Instructions updated: only ask the user about period if the purchase is clearly recurring and no period was specified.\n- Version bump to 0.0.10; no functional changes to commands beyond card period flag.\n\nv0.0.9 | 2026-04-21T15:14:56.718Z | auto\n\nlobstercash 0.0.9\n\n- Added required --period flag to `cards request` (must specify weekly/monthly/yearly; prompt user if missing).\n- Updated deposit flow: replaced `crypto deposit` with `crypto request` throughout, and removed legacy deposit references.\n- Introduced a new reference for `crypto-request` and removed outdated `deposit.md`.\n- Improved documentation for funding the wallet and clarified steps for virtual card creation.\n- Miscellaneous documentation updates to references and examples.\n\nv0.0.8 | 2026-04-14T10:15:36.184Z | auto\n\n**Lobstercash v0.0.8 changelog:**\n\n- Major update: Adds browser automation for web shopping and checkout, restructures and expands workflow steps, and modernizes card and crypto payment flows.\n- Added support for cloud browser automation, including browsing, product discovery, and completing real checkout flows—never guess URLs; always use real, live data.\n- Replaced and renamed CLI commands and help references for improved clarity: e.g., `cards request`, `crypto deposit`, better separation between card and crypto actions.\n- Workflow instructions are now scenario-based (online shopping, API payments, and other wallet actions), making it easier to route intents correctly.\n- Removed obsolete files and commands relating to previous request flows; added new references for browser actions, cards, deposit, and practical examples.\n- Expanded guidance on agent selection, version checking, and user approval, with references to corresponding CLI commands and output formats.\n\nv0.0.4 | 2026-03-31T11:26:49.799Z | user\n\nlobstercash v0.0.4 introduces version checks, agent management, and new references.\n\n- Added explicit version metadata and a Preflight step to check for up-to-date CLI and skill instructions before running commands.\n- Introduced agent management flow: always check for existing agents and register a new one with a unique name before wallet/payment actions.\n- New documentation files: SKILL.md (detailed instructions and metadata) and references/agents.md (agent management reference).\n- Removed obsolete Skill.md (lowercase) file.\n- Updated all command flows to remove required --agent-id flags in most places; now agent context is set separately.\n- Improved upgrade UX—now prompts user and offers one-liner updates if CLI or skill is outdated.\n\nv0.0.3 | 2026-03-24T21:41:27.476Z | user\n\n- No user-facing changes or updates in this release.\n- No file or documentation changes detected from prior version (0.0.2 to 0.0.3).\n\nv0.0.2 | 2026-03-24T19:05:33.587Z | user\n\n- Documentation fix: Installation instructions updated to remove incorrect version pin on the npx install command.\n- No behavioral or CLI changes; usage patterns and flows remain the same.\n\nv0.0.1 | 2026-03-24T00:08:24.781Z | user\n\nMajor update: Expanded payment coverage, improved user flows, and enhanced CLI guidance.\n\n- Now supports spending, wallet management, virtual cards, crypto payments, API payments (x402), and on-chain transactions—all with secure guardrails and human approval.\n- Unified all spending and payment intents (\"buy\", \"pay\", \"send\", \"top up\", etc.) under one streamlined process, regardless of mention of \"lobster\", \"crypto\", or \"Solana\".\n- Clear, step-by-step CLI instructions for each user intent: discover/browse, check status/balances, buy/pay, link agent wallet, or top up funds.\n- Improved automatic routing: selects correct payment method (credit card or crypto) based on store output and wallet status.\n- New human-in-the-loop consent steps and more robust wallet/card setup processes.\n- Updated skill description for broader intent detection and better user guidance.\n\nArchive index:\n\nArchive v0.0.16: 18 files, 38076 bytes\n\nFiles: evals/evals.json (5636b), references/agents.md (6426b), references/balance.md (1464b), references/cards-request.md (1966b), references/cards.md (8663b), references/crypto-request.md (2311b), references/examples.md (1485b), references/purchase-flow-byo.md (10374b), references/purchase-flow.md (12053b), references/purchase.md (6725b), references/send.md (2205b), references/setup.md (2902b), references/status.md (1572b), references/tx.md (3401b), references/x402.md (2343b), skill-card.md (3084b), SKILL.md (16179b), _meta.json (131b)\n\nFile v0.0.16:SKILL.md\n\n---\nname: lobstercash\ndescription: 'Use this skill when the user wants to spend money, make purchases, send crypto, pay for APIs, browse websites for shopping, complete checkout, or manage an AI agent''s payment wallet. Covers buying products online with credit cards (with browser-automated checkout when available, or driven by the agent''s own browser tooling otherwise), sending tokens, paying for x402 protocol APIs, checking balances, depositing funds, browsing available services, and signing on-chain transactions — all with secure guardrails, and appropriate human controls. Trigger on any spending, wallet, or shopping intent: \"buy this\", \"pay for that\", \"send tokens\", \"how much do I have\", \"what can I buy\", \"top up my wallet\", \"get a card\", \"set up payments\", \"find me something to buy\", \"complete the checkout\", or \"browse that site\" — even if the user doesn''t mention \"lobster\", \"crypto\", or \"Solana\" directly.'\nmetadata:\n version: \"0.0.16\"\n---\n\n# Lobster Cash CLI Skill\n\nThe Lobster Cash CLI (`lobstercash`) gives AI agents payment tools — a blockchain wallet, virtual cards for buying anything online, optional cloud browser automation for browsing sites and completing checkout, and x402 protocol support for paying APIs — all with human approval in the loop. Use `lobstercash --help` for full flag details on any command.\n\n## Installation\n\nInstall globally:\n\n```bash\nnpm install -g @crossmint/lobster-cli\n```\n\nAfter installation, all commands are available via the `lobstercash` binary.\n\n## Steps to use this skill\n\n### 1. Version check (automatic)\n\nThe CLI automatically checks for updates on every API call. If an update notice appears in the command output, tell the user and offer to run `npm update -g @crossmint/lobster-cli`. If the notice says the update is **required**, you must also update the skill from https://www.lobster.cash/install before continuing. Do not run separate version-check commands.\n\n### 2. Select lobstercash agent to use\n\nEvery lobstercash command operates on the **active agent**. Before doing anything else, make sure the right agent is selected.\n\n```bash\nlobstercash agents list\n```\n\nThen follow this decision tree:\n\n1. **You see yourself in the list and it says `(active)`** → You're good. Move on.\n2. **You see yourself in the list but it's NOT active** → Run `lobstercash agents set-active ` with the matching ID, then move on.\n3. **No agent matches you** (or the list is empty) → Register a new one. Read the [agents reference](references/agents.md) for how to register one.\n\n**How to recognize yourself:** Match by name. If you are Claude Code, look for an agent named \"Claude Code\" or similar. Same for Cursor, Codex, Gemini, etc. If you aren't sure, ask the user which agent to use.\n\n### 3. Route based on the user's intent\n\nDetermine which scenario applies and follow the corresponding section:\n\n- **A) Buy something online** (product, subscription, domain, service) → [Buy something online](#a-buy-something-online)\n- **B) Pay for a paid API endpoint** (x402 protocol) → [Pay an API with x402](#b-pay-an-api-with-x402)\n- **C) Anything else** (check balance, send crypto, view status, link wallet, browse examples) → [Other actions](#c-other-actions)\n\n---\n\n## A) Buy something online\n\nUse when the user wants to purchase a product, subscription (not yet but comming soon), domain, or any item from an online store. The flow is the same either way: discover the product and price, size a virtual card, then drive checkout in a browser. What changes is **who drives the browser** for this install. Run:\n\n```bash\nlobstercash config get browser-enabled\n```\n\n- `browser-enabled: true` → Lobster Cash's built-in browser automation (`purchase explore` / `purchase run`) drives the merchant site for you. Follow [references/purchase-flow.md](references/purchase-flow.md).\n- `browser-enabled: false` → Lobster Cash's built-in browser automation is **not** available for this install. Do not run `purchase explore` or `purchase run`. Follow [references/purchase-flow-byo.md](references/purchase-flow-byo.md) — the same flow, but you (the agent) drive the merchant site using whatever browser-automation tooling you already have available in this environment (your IDE's browser tool, an MCP browser server, OpenClaw, etc.), and use `cards reveal` to get the credentials to enter at checkout.\n\nIf `browser-enabled: false` and you have **no** browser-automation tooling available in this environment, tell the user you can't drive the browser yourself and offer to run the checkout manually: you'll get the card credentials with `cards reveal` and walk them through entering them at the merchant's checkout page themselves.\n\n---\n\n## B) Pay an API with x402\n\nUse when the user wants to call a paid API endpoint that uses the x402 payment protocol. The CLI handles the payment negotiation automatically: the server returns HTTP 402, the CLI pays with USDC from the agent wallet, and the server returns the content.\n\n### Step 1: Ensure the wallet has funds\n\n```bash\nlobstercash status\n```\n\nRoute based on the result:\n\n- **Wallet configured + has enough funds** → proceed to step 2.\n- **Wallet configured + insufficient funds** → run `lobstercash crypto request --amount --description \"\"` to top up, show the approval URL, wait for user confirmation, then proceed.\n- **Wallet not configured** → run `lobstercash crypto request --amount --description \"\"` (bundles wallet creation + funding). Show the approval URL, wait for user confirmation, verify with `lobstercash status`, then proceed.\n\nThe `--description` must explain what the agent will spend the funds on — derive it from the user's task, not generic filler like \"top up wallet\".\n\nSee [crypto request reference](references/crypto-request.md) for the full crypto request flow.\n\n### Step 2: Fetch the paid endpoint\n\n```bash\nlobstercash crypto x402 fetch \n```\n\nFor POST requests add `--json '{\"key\": \"value\"}'`. For custom headers add `--header \"Authorization: Bearer \"`.\n\n### Step 3: Report the result\n\nReport what the API returned (the `body` field), not the payment mechanics. Only mention the payment if the user asks.\n\nIf the fetch fails, add `--debug` and run again. See [x402 reference](references/x402.md) for output format and common failures.\n\n---\n\n## C) Other actions\n\nFor everything else — checking balances, sending crypto, viewing wallet status, linking a wallet, or browsing examples — use the matching command from the Quick Reference below and read the corresponding reference file for details.\n\n**Run the command, report its output.** For read-only commands (`crypto balance`, `status`, `examples`), execute them directly and report what they say. Do not pre-check status and construct your own summary — the CLI output already handles unconfigured states with clear messaging. If a command fails with exit code 2 (wallet not set up), tell the user and offer to run `lobstercash setup` or the appropriate setup-bundling command.\n\nCommon actions:\n\n- **Check balance:** `lobstercash crypto balance` → [balance reference](references/balance.md)\n- **Send tokens:** `lobstercash crypto send --to --amount --token usdc` → [send reference](references/send.md)\n- **View wallet status:** `lobstercash status` → [status reference](references/status.md)\n- **Browse examples:** `lobstercash examples` → [examples reference](references/examples.md)\n- **Link wallet / configure agent (setup only):** `lobstercash setup` → [setup reference](references/setup.md). Use when the user says \"configure\", \"set up\", \"link wallet\", or similar — and isn't trying to make a purchase.\n- **Sign/submit a transaction:** `lobstercash crypto tx create` → [tx reference](references/tx.md)\n\nFor crypto operations (`crypto send`, `crypto tx create`), always run `lobstercash status` first to confirm the wallet is configured and has sufficient funds. If not, use `lobstercash crypto request --amount --description \"\"` to fund it — see [crypto request reference](references/crypto-request.md).\n\n## Quick Reference\n\n```bash\nlobstercash agents register --name \"\" --description \"\" --image-url \"\" # register a new agent\nlobstercash agents list # list all agents\nlobstercash agents set-active # set active agent\nlobstercash config get browser-enabled # check which browser drives online purchases (used in Section A)\nlobstercash examples # browse working examples\nlobstercash status # check status & readiness & wallet address\nlobstercash setup # link agent to wallet (no purchase needed)\nlobstercash crypto balance # check balances\nlobstercash crypto send --to --amount --token usdc # send tokens\nlobstercash crypto x402 fetch # pay for API\nlobstercash crypto request --amount --description \"\" # request crypto funding / top up (bundles wallet setup)\nlobstercash crypto tx create|approve|status # low-level transaction management\nlobstercash cards request --amount --description \"\" # request virtual card (single-use; subscriptions/--period coming soon)\nlobstercash cards list # list cards (includes card-id, phase, mandates) — used in both purchase flows to check for a reusable card\nlobstercash cards reveal --card-id --merchant-name \"...\" --merchant-url \"https://...\" --merchant-country US # checkout credentials (used by the BYO browser flow, and for manual checkout)\n```\n\nThe `purchase explore` and `purchase run` commands exist only when `browser-enabled: true` is configured — see the relevant purchase-flow reference for usage.\n\n## Output Contract\n\n- All commands produce human-readable output to stdout.\n- Errors go to stderr as plain text.\n- Exit 0 = success. Exit 1 = unexpected error. Exit 2 = wallet not set up (use `cards request` or `crypto request` to set up).\n\n## Decision Tree\n\n- Read [examples](references/examples.md) if the user wants to browse working examples, or has no specific task yet\n- Read [status](references/status.md) if the user asks about agent status or payment readiness\n- Read [balance](references/balance.md) if the user wants to check token balances\n- Read [purchase-flow](references/purchase-flow.md) if the user wants to buy something online and `browser-enabled: true` — full flow using Lobster Cash's built-in browser automation\n- Read [purchase-flow-byo](references/purchase-flow-byo.md) if the user wants to buy something online and `browser-enabled: false` — same flow but the agent drives the browser with its own tooling\n- Read [purchase](references/purchase.md) if you need flag-level reference for `purchase explore` / `purchase run` (browser-enabled only)\n- Read [cards request](references/cards-request.md) if the user wants to create a new virtual card for a purchase\n- Read [crypto request](references/crypto-request.md) if the user wants to request USDC, top up their wallet, or fund a crypto operation\n- Read [cards](references/cards.md) if the user needs to list existing cards, reveal credentials, or check whether a card can be reused for a purchase\n- Read [send](references/send.md) if the user wants to send tokens to an address (Crypto Path)\n- Read [x402](references/x402.md) if the user wants to pay for an API via x402 protocol (Crypto Path)\n- Read [tx](references/tx.md) if the user needs to sign or submit a transaction from an external tool (Crypto Path)\n- Read [setup](references/setup.md) if the user wants to link the agent to a wallet without making a purchase\n- Read [agents](references/agents.md) if the user wants to register, list, or set the active agent\n\n## Anti-Patterns\n\n- **Skipping the browser availability check before an online purchase:** Don't assume which purchase flow applies. When the user wants to buy something online, always run `lobstercash config get browser-enabled` first (Section A) before deciding which purchase-flow reference to load. The flag determines whether to use `purchase explore` / `purchase run` or to drive the browser yourself with `cards reveal` for credentials.\n- **Calling `purchase explore` / `purchase run` when `browser-enabled: false`:** Those commands require the built-in browser automation. If the flag is `false`, follow [references/purchase-flow-byo.md](references/purchase-flow-byo.md) instead.\n- **Running crypto commands without checking status first:** Always run `lobstercash status` before `crypto send`, `crypto x402 fetch`, or `crypto tx create`. If the wallet isn't configured or has insufficient funds, the command will fail with a confusing error. Check first, fund if needed, then execute.\n- **Running setup when the user wants to buy something:** If the user wants to make a purchase, don't run `setup` first — use `cards request` or `crypto request` which bundle setup automatically. Only use `lobstercash setup` when the user explicitly wants to link the agent to their wallet without buying anything.\n- **Re-running setup when the agent is already configured:** If `lobstercash status` shows the wallet is already configured, do not generate a new setup session. The existing configuration is valid. Only start a fresh setup if the user explicitly tells you their current configuration is broken and needs to be regenerated.\n- **Asking the user for info the CLI can fetch:** Check balance before sending. Check status before acting. Read command output before asking questions.\n- **Running write commands in loops:** One attempt, read the result, then decide. Read operations (`crypto balance`, `status`, `examples`) are idempotent and safe to repeat. Write operations (`crypto send`, `cards request`) are not.\n- **Ignoring terminal status:** A pending transaction is not a success. All write commands now wait for on-chain confirmation by default.\n- **Polling for HITL approval:** When a command returns an approval URL, the user must tell you they approved. Do not auto-poll.\n- **Running commands before registering an agent:** Always ensure an agent exists via `lobstercash agents list` before running any other command. If you need to work with a different agent, use `lobstercash agents set-active`.\n- **Asking the user which chain to use:** Agents default to Base silently. Do not ask \"which chain do you want?\" at registration — just register on Base. Only pass `--network solana` if the user has explicitly told you they need Solana, or when the context clearly implies the agent must operate on Solana (e.g. they already hold USDC on Solana, or the integration they want is Solana-only). Chain is fixed per agent; switching later means registering a new one.\n- **Recommending cards for crypto-only integrations:** If the integration only uses crypto, don't suggest a virtual card.\n- **Requiring USDC for card-supported integrations:** Virtual cards are backed by credit cards, not USDC. Don't tell the user to \"add funds\" when the integration accepts cards.\n- **Treating x402/send/tx as separate user flows:** They all go through the same Crypto Path. The only split is credit card vs crypto.\n- **Suggesting `crypto request` or `cards request` when the user just wants to connect:** If the user wants to check balance, run a crypto command, or simply link their wallet — without topping up or creating a card — guide them through `lobstercash setup` first. Don't jump to `crypto request` or `cards request` unless the user actually wants to fund the wallet or make a purchase.\n- **Jumping to readiness checks before showing options:** Show what's available first (via `examples`), then check payment readiness only when the user wants to try one.\n- **Assuming an integration's payment method:** Never guess whether a flow uses cards or crypto. Run `lobstercash status` and read the payment methods output before choosing a path.\n\nFile v0.0.16:_meta.json\n\n{\n \"ownerId\": \"kn7dhdwzdnx02w37wfnqkq6df180b5ap\",\n \"slug\": \"lobstercash\",\n \"version\": \"0.0.16\",\n \"publishedAt\": 1777925289336\n}\n\nFile v0.0.16:references/agents.md\n\n# Agents — Register, List, and Switch Agents\n\nManage agents registered on the server. An agent must exist before running any other command.\n\n## Register an agent\n\n```bash\nlobstercash agents register --name \"\" [--description \"\"] [--image-url \"\"]\n```\n\nRegisters a new agent on the server and sets it as the active agent locally.\n\n- `--name` **(required)** — A **unique, descriptive, human-readable display name**. Use natural casing with spaces, not dashes. Do **not** use generic names like `\"My Agent\"` or `\"Assistant\"`.\n- `--description` **(recommended)** — A short summary of what the agent does. This is shown to the user during approval.\n- `--image-url` **(recommended)** — An avatar or logo URL for the agent. This is displayed alongside the agent's name in the dashboard and approval screens. Preset logos for well-known agents are hosted at `https://lobster.cash/agent-avatars/`:\n\n | Agent | URL |\n | ----------- | ---------------------------------------------------- |\n | Claude Code | `https://lobster.cash/agent-avatars/claude-code.svg` |\n | Cursor | `https://lobster.cash/agent-avatars/cursor.svg` |\n | Codex | `https://lobster.cash/agent-avatars/codex.svg` |\n | Gemini | `https://lobster.cash/agent-avatars/gemini.svg` |\n | OpenClaw | `https://lobster.cash/agent-avatars/openclaw.svg` |\n\n Use a URL from this table, a URL the user explicitly provided, or omit `--image-url` entirely. Do **not** invent or guess image URLs — a broken avatar is worse than no avatar.\n\n- `--network` **(optional)** — The blockchain the agent will operate on. Defaults to `base`. Accepts `base` or `solana`. **Most users should not change this.** Only pass `--network solana` when the user has explicitly asked for Solana, or when the context clearly implies the agent needs to operate on Solana (e.g. the task is to use a Solana-only integration like Jupiter or xStocks). See [Advanced: choosing a non-default chain](#advanced-choosing-a-non-default-chain).\n\n#### Choosing a good name\n\nPick the name that will be most recognizable to the user on the dashboard and in approval prompts. Use your judgment — there is no single formula.\n\n- **If you have a well-known identity, prefer that.** Agents with established names should use them: `\"Claude Code\"`, `\"Devin\"`, `\"Cline\"`, `\"OpenClaw\"`, or whatever the user already knows you as. If the user has configured a custom display name for you, use that.\n- **If a task-specific name is more useful, use that instead.** When you are purpose-built for a particular job — shopping, research, scheduling — a descriptive name like `\"Alice's Shopping Assistant\"` or `\"Travel Planner\"` may be clearer than a generic runtime name.\n- **When in doubt, combine both.** Something like `\"Claude Code — Research\"` works if you want to convey both identity and purpose.\n\nThe goal: when the user sees the name on an approval screen, they should immediately know _which agent_ is asking and _what it does_.\n\nExamples:\n\n```bash\nlobstercash agents register \\\n --name \"Claude Code\" \\\n --description \"Anthropic's AI coding agent\" \\\n --image-url \"https://lobster.cash/agent-avatars/claude-code.svg\"\n\nlobstercash agents register \\\n --name \"Alice's Shopping Assistant\" \\\n --description \"Finds deals and buys products for Alice\" \\\n --image-url \"https://example.com/alice-avatar.png\"\n```\n\nExample output:\n\n```\nAgent registered and set as active.\n ID: a1b2c3d4-5678-90ab-cdef-1234567890ab\n Name: Shopping Assistant\n Desc: Finds deals and buys products\n Key: 5Xyz...abc\n```\n\n#### Advanced: choosing a non-default chain\n\nAgents default to Base. Do **not** ask the user which chain they want — just register on Base silently. Only pass `--network solana` when the user has explicitly told you they need Solana, or when the context clearly implies the agent must operate on Solana (for example, the task the user described can only be completed through a Solana-native integration).\n\nPick `solana` only when:\n\n- The user already holds USDC on Solana and wants the agent to use those funds.\n- The integration the user wants is Solana-only (e.g. Jupiter swaps, xStocks).\n- The user explicitly asks for Solana.\n\nThe chain is **fixed for the lifetime of the agent**. To switch chains later, the user must register a new agent with a different `--network`. Existing agents cannot be migrated.\n\nExample:\n\n```bash\nlobstercash agents register \\\n --name \"Solana Trading Bot\" \\\n --description \"Trades tokenized stocks on Jupiter\" \\\n --image-url \"https://lobster.cash/agent-avatars/claude-code.svg\" \\\n --network solana\n```\n\n### When to use\n\n- First-time setup before any wallet or payment command.\n- When the user wants to register a new agent identity.\n\n## List agents\n\n```bash\nlobstercash agents list\n```\n\nShows all agents with their metadata from the server. Also resolves any pending setup sessions automatically.\n\nExample output:\n\n```\nAgents:\n\n a1b2c3d4-5678-90ab-cdef-1234567890ab (active)\n Name: Shopping Assistant\n Desc: Finds deals and buys products\n Key: 5Xyz...abc\n Status: active\n\n e5f6a7b8-9012-34cd-ef56-7890abcdef12\n Name: Research Bot\n Key: 7Abc...xyz\n Status: pairing\n```\n\n### When to use\n\n- Before any operation, to confirm an agent exists.\n- When the user asks \"which agents do I have?\" or \"what's my agent ID?\"\n- To check and resolve pending setup sessions.\n\n## Set active agent\n\n```bash\nlobstercash agents set-active \n```\n\nSets a different agent as active. All subsequent commands operate on the newly selected agent's wallet.\n\nExample output:\n\n```\nActive agent set to \"e5f6a7b8-9012-34cd-ef56-7890abcdef12\".\n```\n\n### When to use\n\n- When the user wants to operate a different agent's wallet.\n- In multi-agent scenarios where the user needs to change the active agent.\n\n## Concurrent agents (`LOBSTER_AGENT_ID`)\n\nWhen running multiple agents in parallel (e.g. two terminals), set the `LOBSTER_AGENT_ID` environment variable to avoid conflicts with the shared active agent:\n\n```bash\nexport LOBSTER_AGENT_ID=\"\"\n```\n\nThis overrides `agents set-active` for the current shell session. All commands in that terminal will use the specified agent regardless of what `activeAgentId` is set to in `agents.json`.\n\nAfter registering an agent, set this env var immediately to pin the session to that agent.\n\nFile v0.0.16:references/balance.md\n\n# Balance\n\nCheck the current token balances in the agent wallet.\n\n## Command\n\n```\nlobstercash crypto balance\n```\n\n## Reading the output\n\nThe output includes a `chain` field (e.g. `base`, `solana`) indicating\nwhich network the balances are on, followed by one line per token in the\nformat ` : `, e.g. ` usdc: 42.50`. Common tokens: `usdc`, plus\nthe chain's native token (`eth` on Base, `sol` on Solana).\n\nUse the `chain` field to know which network the funds live on — this matters\nwhen deciding parameters for `send` or `x402 fetch`.\n\nAmount is a decimal string. Parse it as a float for arithmetic. Do not\ndisplay more than 2 decimal places to the user.\n\nIf the output says \"No balances found\": the wallet exists but holds no\ntokens. Say \"Your wallet is empty\" not \"wallet not found.\"\n\n## When to run this skill\n\n- Before every `send` command — check the balance covers the amount.\n- Before every `x402 fetch` — check there is enough USDC.\n- When the user asks \"how much do I have\" or similar.\n- When diagnosing why a transaction failed.\n\n## Insufficient balance\n\nIf the balance is too low for what the user wants to do:\nSay: \"Your wallet has [X] USDC. This needs [Y] USDC.\"\nThen use `lobstercash crypto request --amount --description \"\"` to\ngenerate a funding request link for the user.\n\nDo not attempt the operation with insufficient funds. The error message\nfrom the CLI in that case is technical and confusing to users.\n\nFile v0.0.16:references/cards-request.md\n\n# Cards Request — Virtual Card for Purchases\n\nRequest a virtual card backed by the user's credit card. This is the fastest payment path — no USDC or wallet funding needed. If the wallet isn't configured yet, this command bundles setup automatically.\n\n## Command\n\n```bash\nlobstercash cards request --amount --description \"\" --period \n```\n\n## What you need before running\n\nExtract from context — do not ask if already clear:\n\n- `amount`: how much to load in USD (e.g. `25.00`)\n- `description`: what the card will be used for (e.g. `\"AWS credits\"`)\n- `period`: billing period for the mandate — **required**, one of `weekly`, `monthly`, `yearly`. If the user doesn't specify, ask them.\n\nIf the user said \"I need a card for $25 for AWS\" you already have both.\n\n## Reading the output\n\nThe output contains:\n\n- `agentId`: the agent this card is for\n- `amount`: the requested amount\n- `period`: the billing period (`weekly`, `monthly`, or `yearly`)\n- `description`: what the card is for\n- `approvalUrl`: the URL the user must open to approve\n- `setupSessionId`: present if wallet setup was bundled (first-time use)\n\n## After running\n\nShow the approval URL to the user:\n\n> To create this card I need your approval. Open this link:\n>\n> [approvalUrl]\n>\n> Come back here when you've approved it.\n\nDo not proceed until the user confirms they have approved.\n\n## After user approves\n\nRun `lobstercash cards list` to verify the card was created. Then proceed with the user's task — see `references/cards.md` for listing, revealing credentials, and checkout.\n\n## Gotchas\n\n- Virtual cards do NOT require USDC — they're backed by the user's credit card\n- If the wallet isn't configured, setup is bundled automatically — do not run `lobstercash setup` first\n- Only use this when the integration supports `card` payments — do not recommend for crypto-only integrations\n- Write operation — do not retry automatically or if the user declines\n\nFile v0.0.16:references/cards.md\n\n# Virtual Cards\n\nRequest, list, reveal credentials for checkout, and inspect virtual cards on the agent wallet.\n\n## What virtual cards are\n\nVirtual cards are temporary, scoped payment cards generated from the user's saved card on file using Visa Intelligent Commerce and Mastercard Agent Pay. They work like disposable debit cards with a fixed spending limit — the card cannot be charged beyond the amount the user approved when creating it.\n\nKey properties:\n\n- **Privacy-preserving:** The user's real card details (number, CVC, expiry) are never shared with the agent. The agent only ever sees the virtual card credentials, which are separate from the card on file.\n- **Scoped balance:** Each virtual card has a hard spending cap set at creation time. Once that limit is reached, the card declines further charges. This protects the user from overspending.\n- **Human approval required:** Creating a virtual card always requires the user to approve via a link. The agent cannot create or fund a card without explicit human consent.\n\n**Naming:** The API calls these _order intents_; the CLI and plugin expose them as _virtual cards_. Each card has a stable id: `orderIntentId`. For `lobstercash cards reveal`, pass that value as `--card-id`.\n\n---\n\n## Requesting a new card\n\n> **Note:** Subscription / recurring cards are **coming soon**. For now every card is single-use — request a fresh one per purchase. The `--period` flag still exists in the CLI but should be omitted until subscriptions ship.\n\n### What you need before running\n\nTwo pieces of information — extract from context, do not ask if already clear:\n\n- `amount`: maximum USD that can be spent on this virtual card (e.g. `25.00`). Other currencies will be supported soon.\n- `description`: what the card will be used for (e.g. `\"AWS credits\"`).\n\nIf the user said \"I need a card for $25 for AWS\" you already have both. Do not ask about period today — it has no effect until subscription cards launch.\n\n### Command\n\n```\nlobstercash cards request \\\n --amount \\\n --description \"\"\n```\n\n`--period ` is reserved for the upcoming subscription cards feature; omit it for now.\n\n### Reading the output\n\nThe output contains:\n\n- The requested amount and description\n- An approval URL the user must open to approve the card request\n\n### After running\n\nShow the approval URL to the user:\n\"To create this card I need your approval. Open this link:\n\n[approvalUrl]\n\nCome back here when you've approved it.\"\n\nDo not proceed until the user confirms they have approved.\n\n### After user approves\n\nRun: `lobstercash cards list`.\n\nFind the card with matching description (see `card-id=...` on each line). Report to user:\n\"Your card is ready\"\n\nAnd then proceed with what you were doing.\n\n### If the command fails (exit code 1)\n\nShow the error message from stderr.\n\n### What NOT to do\n\n- Do not retry automatically if the user says they declined.\n- Do not explain how virtual cards work unless asked.\n\n---\n\n## Listing existing cards\n\nThis command shows card metadata (description, limit, phase, and card ID) — not payment credentials. To get the actual card number, CVC, and expiry for checkout, use `cards reveal` (see below) with the `card-id` from this output.\n\n### Command\n\n```\nlobstercash cards list\n```\n\n### Reading the output\n\nOne line per card:\n\n```\n $ limit [] card-id=\n```\n\nUse `card-id` as `--card-id` when running `lobstercash cards reveal`. In OpenClaw, the same value is `orderIntentId` on each item in `lobster_order_intents` → `details.orderIntents`.\n\nPossible phase values:\n\n- `active` — card is ready to use; credentials can be revealed for checkout\n- `requires-payment-method` — no valid card on file; the user must add or update their payment method at lobster.cash/dashboard before this card can activate\n- `requires-verification` — the user's bank requires additional authentication (e.g. 3D Secure); they must complete verification in the browser at the approval link\n- `expired` — card is no longer valid; the user needs to request a new one\n\n### When to use\n\n- After the user approves a card request — to confirm the card is `active` and get its `card-id`\n- When the user asks \"do I have any cards\"\n- To check the status of a specific card\n- **Before creating a new card for a purchase** — always list first and check whether an existing card can be reused (see \"Reusing an existing card\" below). This is Step 3 of the buy flow in `SKILL.md`.\n\n### Reporting to the user\n\nList only `active` cards unless the user asks for all.\nSay: \"You have [n] active card(s): [description] with a $[amount] limit.\"\n\n### Reusing an existing card\n\nWhen you're about to create a new card for a purchase, run `cards list` first and check whether one already covers the purchase. Reusing a card avoids spamming the user with another approval link.\n\n> **Note:** Cards are single-use today (subscription cards coming soon). A card you already charged successfully cannot be reused — request a new one. The `period` rule below is forward-looking for when subscriptions ship.\n\nEach item carries these mandate fields:\n\n- `phase` — only `active` is usable.\n- `mandates[type=maxAmount].value` — the spending cap.\n- `mandates[type=maxAmount].details.currency` — currency (default `USD`).\n- `mandates[type=maxAmount].details.period` — currently always absent (single-use). Will be `weekly | monthly | yearly` when subscriptions launch.\n- `mandates[type=description].value` — what the user approved it for.\n- `mandates[type=prompt].value` — richer original natural-language request (when present).\n- `mandates[type=consumer].details.email` — consumer email scope.\n\nDo **not** match on:\n\n- **Remaining balance** — only the cap is exposed; once recurring cards launch we won't be able to see what's already been spent in the current period. Trust the cap and let the merchant decline if exceeded.\n- **Whether the card has been charged** — `cards list` doesn't expose charge history. If you (or a previous turn) already used the card for a purchase, treat it as spent and request a new one.\n- `agentId` / `paymentMethodId` — internal bindings, not match signals.\n\nA card is **usable for a given purchase** only when **all** of the following hold:\n\n1. `phase === active`.\n2. `maxAmount.value >= rounded total` (rounded up to the nearest $5).\n3. `maxAmount.details.currency` matches the purchase currency.\n4. The card hasn't already been used. Today every card is single-use, so any card already charged successfully is no longer usable. _(Coming soon: when subscription cards ship, `maxAmount.details.period` will need to match the cadence — single-use → no period; recurring → same period.)_\n5. `description` (and `prompt` if present) is **semantically compatible** with the purchase. Don't reuse an \"AWS credits\" card for \"enamel pins\" — request a new card scoped to the new purpose. A generic description like \"online shopping\" can cover broader purchases — use judgment.\n\nIf none match, fall back to `cards request`.\n\n---\n\n## Revealing card credentials (checkout)\n\nUse when the user needs the **full card number, CVC, and expiry** to complete a purchase (e.g. paste into a merchant checkout). Only works for cards in **`active`** phase.\n\n### OpenClaw plugin\n\nUse tool `lobster_card_reveal` with:\n\n- `cardId` — same as `orderIntentId` from `lobster_order_intents` (`details.orderIntents[].orderIntentId`)\n- `merchantName`, `merchantUrl`, `merchantCountryCode` (ISO 3166-1 alpha-2, e.g. `US`) — describe where the card will be used\n- Optional `products` — array of `{ name, price, quantity }` if the API requires it\n\n### CLI\n\n```\nlobstercash cards reveal \\\n --card-id \\\n --merchant-name \"\" \\\n --merchant-url \"\" \\\n --merchant-country \n```\n\n### What you need from context\n\nExtract from the user or the purchase flow — do not invent merchant details:\n\n- **Card id:** from `lobstercash cards list` (`card-id=...` on the line) or `lobster_order_intents` → `details.orderIntents[].orderIntentId`.\n- **Merchant:** real store name, canonical site URL, and country code for that merchant.\n\n### Reading the output\n\nThe command prints card number, expiration (month/year), CVC, and credential expiry time. Treat this output as highly sensitive.\n\n### Security and UX\n\n- Treat revealed values like a physical card: do not log them unnecessarily or paste into untrusted channels.\n- Confirm the user is ready to check out before revealing.\n- If reveal fails (e.g. wrong phase), re-check `lobstercash cards list` for `phase === active`.\n\nFile v0.0.16:references/crypto-request.md\n\n# Crypto Request — Fund the Wallet with USDC\n\nRequest USDC funding for the agent's wallet. Generates an approval URL where the user can deposit funds. If the wallet isn't configured yet, this command bundles setup automatically.\n\n## Command\n\n```bash\nlobstercash crypto request --amount --description \"\"\n```\n\n## When to use\n\n- The user wants to add funds or top up their wallet\n- Balance is insufficient for a crypto operation (`crypto send`, `crypto x402 fetch`, `crypto tx`)\n- The wallet isn't configured and the user needs crypto (not card) — this bundles setup + funding in one step\n\n## What you need before running\n\n- `amount`: how much USDC to request (e.g. `25.00`)\n- `description`: what the agent will spend the funds on — derived from the user's task, not generic filler. Good: `\"Pay for 3 Exa searches on competitor pricing\"`. Bad: `\"Top up wallet\"`, `\"Fund wallet for API calls\"`.\n\nCalculate the amount based on what the user needs. If topping up for a specific operation, use: `needed amount - current balance`.\n\nAlways check balance first with `lobstercash crypto balance` to know the current state.\n\n## Reading the output\n\nThe output contains:\n\n- `agentId`: the agent this request is for\n- `amount`: the requested funding amount in USDC\n- `description`: what the funds are for\n- `approvalUrl`: the URL the user must open to approve\n- `setupSessionId`: present if wallet setup was bundled (first-time use)\n\n## After running\n\nShow the approval URL to the user:\n\n> To fund $[amount] USDC, open this link:\n>\n> [approvalUrl]\n>\n> Come back here when you've completed the funding.\n\nDo not proceed until the user confirms they have funded the wallet.\n\n## After user confirms\n\nRun `lobstercash status` to verify the funds landed and the wallet is ready. Then proceed with the user's original task (`crypto send`, `crypto x402 fetch`, etc.).\n\n## Gotchas\n\n- If the wallet isn't configured, setup is bundled automatically — do not run `lobstercash setup` first\n- Only needed for crypto operations — virtual cards (`cards request`) don't require USDC, so don't use this when `paymentMethods` includes `card`\n- Always check balance first (`lobstercash crypto balance`) — know the current state before requesting\n- Write operation — do not retry automatically or if the user declines\n\nFile v0.0.16:references/examples.md\n\n# Examples\n\nShow real, working examples of what agents can do with lobster.cash. Each example has been verified end-to-end.\n\n## When to use\n\n- After setup completes and the user has no specific request.\n- When the user asks \"what can you do?\" or \"what can I buy?\".\n- Only show once per session — do not repeat if the user already saw it.\n\n## Command\n\n```\nlobstercash examples\n```\n\n## Reading the output\n\nEach example includes:\n\n- `name` — example name\n- `oneLiner` — short description\n- `description` — how it works in a few lines\n- `skillUrl` — link to the skill repo with full instructions\n\n## Current examples\n\n### xStocks\n\nBuy tokenized stocks (Apple, Tesla, NVIDIA, S&P 500…) on Solana with USDC. The skill includes a local catalog of 104 tokens — no API calls needed to search or look up mint addresses. Purchases go through Jupiter swaps: the skill builds an unsigned transaction, lobster.cash signs it, and the agent owns fractional stock exposure on-chain.\n\nSkill: https://github.com/manu-xmint/xstocks-skill\n\n## How to present\n\nDo not dump the raw output. Summarize conversationally:\n\n\"Here's something you can do right now:\n\n- **Buy tokenized stocks** — trade Apple, Tesla, NVIDIA, and 100+ other stocks on Solana using USDC (xStocks)\n\nWant to try it?\"\n\n## After the user picks\n\nOnce the user picks an example, check their balance (`lobstercash crypto balance`)\nand proceed with the relevant skill. If they need funds, guide them to\nthe crypto request flow.\n\nFile v0.0.16:references/purchase-flow-byo.md\n\n# Buy something online — bring-your-own browser flow\n\nThis is the purchase flow when **`browser-enabled: false`** (see [SKILL.md](../SKILL.md) Section A). It is the same end-to-end flow as [purchase-flow.md](purchase-flow.md), with one difference: **you (the agent) drive the merchant browser using whatever browser-automation tooling you already have available** in this environment (your IDE's browser tool, an MCP browser server, OpenClaw, Playwright/Puppeteer access, etc.). Lobster Cash still provides the virtual card, the user-approval flow, and `cards reveal` for credentials at checkout — it just doesn't drive the browser.\n\nIf you have **no** browser-automation tooling available in this environment, stop and offer to run the checkout manually with the user — you'll get the card credentials with `cards reveal` and walk them through entering them at the merchant's checkout page themselves.\n\nThe flow: discover the real product and price first (with your browser), size a virtual card to that price (or reuse an existing one), get user approval, then complete checkout (with your browser, using credentials from `cards reveal`).\n\n## Step 1: Gather info from the conversation\n\nCheck what you already know from prior turns before asking:\n\n- shipping address\n- contact email\n- phone (if the merchant might require it)\n- product preferences (size, color, brand, quantity, exclusions)\n\nOnly ask the user for fields you don't already have. If they say a field isn't needed (e.g. \"no phone\" or \"digital product, no address\"), believe them and skip it. Never re-ask for info already in the conversation.\n\n## Step 2: Discover the product and price (your browser tool)\n\nUse **your own browser tooling** to navigate the merchant's site, locate the product the user wants, add it to the cart (or get to a quote/total page), and capture the **final total** including tax and shipping. You need a real, current total so the next step can size the virtual card correctly.\n\nWhile you work, share progress with the user — what site you're on, what you found, when you've reached the cart total. They should be able to follow along.\n\nWhat you must come away with before moving on:\n\n- The product (name, variant/size/color if applicable, quantity)\n- The merchant (real store name, canonical URL, country)\n- The cart total in USD (or the purchase currency)\n- A way to resume checkout later — keep your browser session/tab parked on the cart, or note the cart URL / re-buildable cart so you can return to it after card approval\n\nIf you don't know which merchant the user wants, do a web search first to ground yourself in a real merchant — don't guess URLs from training data. Same rule as the native flow: navigate the site's UI, don't bake guessed paths like `/category/socks` into anything.\n\nIf the merchant requires the user to sign in or answer a question that you can't decide on your own (size, paid shipping speed, etc.), pause and ask the user — don't invent answers.\n\n## Step 3: Check for an existing usable card (fork)\n\nBefore creating a new card, list current cards and look for one that already covers this purchase.\n\n```bash\nlobstercash cards list\n```\n\n> **Note:** Subscription / recurring cards are coming soon — for now every card is single-use. The matching rules below already account for this; period-based matching will become relevant once subscriptions ship.\n\nEach card (order intent) carries these fields you can compare against:\n\n- `phase` — only `active` is usable\n- `mandates[type=maxAmount].value` — the spending cap (in `details.currency`, default USD)\n- `mandates[type=maxAmount].details.period` — currently always absent (single-use). Will be `weekly | monthly | yearly` when subscriptions launch.\n- `mandates[type=description].value` — what the user approved the card for (e.g. \"AWS credits\", \"RHCP enamel pins\")\n- `mandates[type=prompt].value` — original natural-language request (richer context than description)\n- `mandates[type=consumer].details.email` — consumer email scope (only matters if multi-user)\n\nFields **NOT** to rely on:\n\n- **Remaining balance** — `cards list` only exposes the limit, not how much has been spent.\n- **Whether the card has already been charged** — single-use cards can't be reused once they've been charged successfully, but `cards list` doesn't expose charge history. If the card looks unused (no purchase you initiated against it), assume it's available; otherwise request a new one.\n- `agentId` / `paymentMethodId` — internal bindings, not user-facing match signals.\n\nA card is **usable for this purchase** when **all** of the following are true:\n\n1. `phase === active`\n2. `maxAmount.value >= rounded total` (rounded up to the nearest $5)\n3. `maxAmount.details.currency` matches the purchase currency (typically `USD`)\n4. The card hasn't already been used. Today every card is single-use, so a card you (or a previous turn) already charged successfully is no longer usable.\n5. `description` (and `prompt` if present) is **semantically compatible** with the purchase. Don't reuse a card whose description targets a different merchant or product category.\n\nFork:\n\n- **Match found** → skip Step 3b and Step 4. Reuse its `card-id` and jump straight to **Step 5**. Tell the user briefly: \"Reusing your existing $X card for [description].\"\n- **No match** → continue to Step 3b.\n\nSee [cards reference](cards.md) for the full `cards list` output format and field semantics.\n\n## Step 3b: Request a new virtual card sized to the discovered total\n\nRound the discovered total **up** to the nearest $5 so a small price drift at checkout doesn't decline the card (e.g. $47.23 → $50, $31.75 → $35). Tell the user the rounded amount and why.\n\n```bash\nlobstercash cards request --amount --description \"\"\n```\n\nCards are currently single-use only. Subscription / recurring cards are coming soon — until then, omit `--period` (or rely on the default) and request a fresh card per purchase.\n\nThis command bundles wallet setup if needed. See [cards request reference](cards-request.md) for output format.\n\n## Step 4: Get user approval\n\nThe `cards request` command outputs an `approvalUrl`. Show it to the user:\n\n> To create this card I need your approval. Open this link:\n>\n> [approvalUrl]\n>\n> Come back here when you've approved it.\n\n**Do not proceed until the user confirms they approved.** Do not poll. After they confirm, run `lobstercash cards list` once to verify the new card is `active`, then continue.\n\n## Step 5: Complete the purchase (your browser tool + `cards reveal`)\n\nNow the card is ready and the cart is parked. Two sub-steps:\n\n### 5a — Reveal the card credentials\n\n```bash\nlobstercash cards reveal \\\n --card-id \\\n --merchant-name \"\" \\\n --merchant-url \"\" \\\n --merchant-country \n```\n\nThis prints the card number, expiry month/year, and CVC for that specific merchant. **Treat the output as highly sensitive.** Do not log or paste it anywhere outside of the merchant's checkout form. Do not share these details with the user; just use them yourself in the browser.\n\nSee [cards reveal section in cards reference](cards.md#revealing-card-credentials-checkout) for full flag details and security notes.\n\n### 5b — Drive checkout with your browser tool\n\nReturn your browser to the parked cart (or rebuild it from the cart URL captured in Step 2) and complete the checkout form using the user's shipping/contact info from Step 1 and the revealed card details from Step 5a.\n\n**Stop before final submit.** Reach the order-review screen and pause. Then ask the user to confirm: \"Cart total is $X. Card ending in . Shipping to
. Ready for me to place the order?\" Only submit once the user has explicitly authorized this exact submission.\n\nIf the merchant total at checkout exceeds the card's hard cap, the card will decline. Don't try to charge more than the card limit — request a new card sized to the new total instead.\n\nIf the merchant asks for something you can't answer on your own (size choice, shipping option that costs extra, missing address field), pause and ask the user. Don't invent answers.\n\nAfter the order is submitted, share the confirmation details (order number, total charged, ETA if shown) with the user.\n\n## Anti-patterns (BYO browser flow)\n\n- **Calling `purchase explore` or `purchase run`:** They require `browser-enabled: true`. In this flow you drive the browser yourself.\n- **Skipping price discovery:** Always discover the real product and price (Step 2) before requesting a card. Without it you can't size the card and the merchant will decline.\n- **Hallucinating product URLs or paths:** Same rule as the native flow — never guess URLs beyond the root domain. Either start from the merchant homepage and let your browser tool navigate the site's own UI, or ground yourself in a real URL pulled from web search results.\n- **Placing orders without user authorization:** The card's hard cap is a backstop, not a green light. Always stop at the order-review screen and ask the user to confirm before submitting.\n- **Requesting a new card without checking `cards list` first:** Always run `lobstercash cards list` after Step 2 and check whether an `active` card already covers this purchase. Reusing a usable card avoids spamming the user with another approval link.\n- **Reusing a card whose description doesn't fit the purchase:** The user approved each card for a specific purpose. Don't reuse an \"AWS credits\" card to buy enamel pins — request a new card scoped to the new purpose.\n- **Sharing revealed card details with the user or logs:** `cards reveal` output is sensitive. Use the values in the merchant's checkout form, then forget them. Don't echo them back to the user.\n- **Guessing merchant questions you can't answer:** Same as the native flow — when you hit a required choice you can't make on your own (size, shipping option, missing address field), pause and ask the user. Don't invent answers.\n- **Pretending you have a browser tool when you don't:** If this environment has no browser-automation tooling available, don't bluff your way through Step 2 or Step 5. Stop and offer the user a manual checkout instead — get the credentials with `cards reveal` and walk them through entering them at the merchant's checkout themselves.\n\nFile v0.0.16:references/purchase-flow.md\n\n# Buy something online (browser-automated purchase flow)\n\nThis reference describes the end-to-end flow for buying products online with a virtual card and Lobster Cash's built-in Browser Use automation. It applies when **`browser-enabled: true`** for this CLI install (see [SKILL.md](../SKILL.md) Section A). If `browser-enabled: false`, follow [purchase-flow-byo.md](purchase-flow-byo.md) instead — same end-to-end flow, but you drive the merchant browser yourself.\n\nUse when the user wants to purchase a product, subscription, domain, or any item from an online store. Purchases are **always browser-automated** via `purchase run` — Browser Use navigates the merchant's site, fills the checkout form, and stops at final review (or submits, when explicitly authorized).\n\nThe flow is: discover the real product and price first, then size a virtual card to that price (or reuse an existing one), then run the automated checkout.\n\n## Step 1: Gather info from the conversation\n\nCheck what you already know from prior turns before asking:\n\n- shipping address\n- contact email\n- phone (if the merchant might require it)\n- product preferences (size, color, brand, quantity, exclusions)\n\nOnly ask the user for fields you don't already have. If they say a field isn't needed (e.g. \"no phone\" or \"digital product, no address\"), believe them and skip it. Never re-ask for info already in the conversation.\n\n## Step 2: Discover the product and price (`purchase explore`)\n\n**Ensure the wallet is set up first.** `purchase explore` and `purchase run` require an active wallet session and will exit with code 2 if one isn't configured — unlike `cards request` / `crypto request`, they do **not** bundle setup. Run `lobstercash status`:\n\n- **Wallet configured** → continue.\n- **Wallet not configured** → run `lobstercash setup`, share the approval URL with the user, and wait for them to confirm they approved before continuing. Don't try to bundle setup via `cards request` here — at this point you don't yet know the price, so you can't size the card correctly.\n\nPack everything into one natural-language `--description` and run explore. Share the live view URL with the user so they can watch.\n\n```bash\nlobstercash purchase explore \\\n --description \"\" \\\n --merchant-country \n```\n\nHandle the response:\n\n- `completed` → record `exploreId` and the discovered total, move on to Step 3.\n- `needs_user_input` → ask the user the returned question, resume with `--explore-id --answer \"...\"`.\n- `running` → re-poll with `--explore-id `.\n\n**Never invent product URLs or category paths from training data.** Explore navigates the merchant's UI for you — that's the whole point. If the user didn't specify a merchant, do a web search first to ground the description in a real one (e.g. \"best running socks to buy online\" or \"running socks site:nike.com\").\n\nFor full flag list, description-writing guidance, resume/poll syntax, and output status definitions, see [purchase reference](purchase.md).\n\n## Step 3: Check for an existing usable card (fork)\n\nBefore creating a new card, list current cards and look for one that already covers this purchase.\n\n```bash\nlobstercash cards list\n```\n\n> **Note:** Subscription / recurring cards are coming soon — for now every card is single-use. The matching rules below already account for this; period-based matching will become relevant once subscriptions ship.\n\nEach card (order intent) carries these fields you can compare against:\n\n- `phase` — only `active` is usable\n- `mandates[type=maxAmount].value` — the spending cap (in `details.currency`, default USD)\n- `mandates[type=maxAmount].details.period` — currently always absent (single-use). Will be `weekly | monthly | yearly` when subscriptions launch.\n- `mandates[type=description].value` — what the user approved the card for (e.g. \"AWS credits\", \"RHCP enamel pins\")\n- `mandates[type=prompt].value` — original natural-language request (richer context than description)\n- `mandates[type=consumer].details.email` — consumer email scope (only matters if multi-user)\n\nFields **NOT** to rely on:\n\n- **Remaining balance** — `cards list` only exposes the limit, not how much has been spent. Once subscription cards ship we won't be able to tell if this period's budget is already drained; trust the limit and let the merchant decline if exceeded.\n- **Whether the card has already been charged** — single-use cards can't be reused once they've been charged successfully, but `cards list` doesn't expose charge history. If the card looks unused (no purchase you initiated against it), assume it's available; otherwise request a new one.\n- `agentId` / `paymentMethodId` — internal bindings, not user-facing match signals.\n\nA card is **usable for this purchase** when **all** of the following are true:\n\n1. `phase === active`\n2. `maxAmount.value >= rounded total` (rounded up to the nearest $5)\n3. `maxAmount.details.currency` matches the purchase currency (typically `USD`)\n4. The card hasn't already been used. Today every card is single-use, so a card you (or a previous turn) already charged successfully is no longer usable. _(Coming soon: when subscription cards launch, `maxAmount.details.period` will need to match the requested cadence — single-use purchase → no period; recurring purchase → same period.)_\n5. `description` (and `prompt` if present) is **semantically compatible** with the purchase. The user approved the card for a specific purpose — do not reuse a card whose description targets a different merchant or product category. Example: an existing \"AWS credits\" card must not be reused for \"RHCP enamel pins\". A generic description like \"online shopping\" can cover broader purchases — use judgment.\n\nFork:\n\n- **Match found** → skip Step 3b and Step 4. Reuse its `card-id` and jump straight to **Step 5**. Tell the user briefly: \"Reusing your existing $X card for [description].\"\n- **No match** → continue to Step 3b.\n\nSee [cards reference](cards.md) for the full `cards list` output format and field semantics.\n\n## Step 3b: Request a new virtual card sized to the discovered total\n\nRound the discovered total **up** to the nearest $5 so a small price drift at checkout doesn't decline the card (e.g. $47.23 → $50, $31.75 → $35). Tell the user the rounded amount and why.\n\n```bash\nlobstercash cards request --amount --description \"\"\n```\n\nCards are currently single-use only. **Subscription / recurring cards are coming soon** — when they ship you'll be able to add `--period ` for recurring purchases. Until then, omit `--period` (or rely on the default) and request a fresh card per purchase.\n\nThis command bundles wallet setup if needed. See [cards request reference](cards-request.md) for output format.\n\n## Step 4: Get user approval\n\nThe `cards request` command outputs an `approvalUrl`. Show it to the user:\n\n> To create this card I need your approval. Open this link:\n>\n> [approvalUrl]\n>\n> Come back here when you've approved it.\n\n**Do not proceed until the user confirms they approved.** Do not poll. After they confirm, run `lobstercash cards list` once to verify the new card is `active`, then continue.\n\n## Step 5: Complete the purchase (`purchase run`)\n\nReuse the explore session — the browser is already parked on the cart, so the purchase agent picks up immediately without re-searching.\n\n```bash\nlobstercash purchase run \\\n --card-id \\\n --explore-id \\\n --description \"\" \\\n --max-total \n```\n\nShare the live view URL with the user so they can watch the checkout. The agent will place the order automatically as long as the cart total stays at or below `--max-total`. Size `--max-total` to match what the user has approved.\n\nHandle the response the same way as explore: `completed` → done; `needs_user_input` → ask and resume with `--purchase-id --answer \"...\"`; `running` → re-poll with `--purchase-id `.\n\nFor all run flags (`--constraint`, `--shipping-json`, `--contact-json`), the single-phase fallback (no `--explore-id`), and local `dev-mock-card` testing, see [purchase reference](purchase.md).\n\n## Browser-related commands (Quick Reference)\n\n```bash\nlobstercash purchase explore --description \"<...>\" --merchant-country # discover product + price (Step 2)\nlobstercash purchase run --card-id --explore-id --description \"<...>\" --max-total # automated browser checkout (Step 5)\nlobstercash cards reveal --card-id --merchant-name \"...\" --merchant-url \"https://...\" --merchant-country US # checkout credentials (manual sites only — not part of the standard buy flow)\n```\n\n## Browser-related references\n\n- Read [purchase](purchase.md) for full flag reference, single-phase fallback, dev-mock-card, description-writing tips, and resume/poll syntax\n- Read [cards request](cards-request.md) for creating a new virtual card for a purchase (Step 3b)\n- Read [cards](cards.md) for listing existing cards and checking whether one can be reused (Step 3)\n\n## Anti-patterns (browser flow specific)\n\n- **Running `purchase explore` / `purchase run` before the wallet is set up:** Both purchase commands require an active wallet session and exit with code 2 otherwise — they do **not** bundle setup. Always run `lobstercash status` first; if the wallet isn't configured, run `lobstercash setup` and wait for user approval before calling `purchase explore`. (`cards request` and `crypto request` are different — they _do_ bundle setup, so don't run `setup` separately ahead of those.)\n- **Hallucinating product URLs or paths:** Never guess URLs beyond the root domain — `/w/socks`, `/category/socks`, `/shop/socks` are all guesses, and URL structures change. Don't bake guessed paths into the `purchase explore --description`. Either give explore the merchant homepage (e.g. `nike.com`) and let Browser Use navigate the site's own UI, or ground the description with a real URL pulled from web search results.\n- **Placing orders without user authorization:** `purchase run` always submits the order if the cart stays at or under `--max-total`, with no human approval at the review screen. Don't call it until the user has explicitly authorized this purchase, and size `--max-total` to match what they approved — it's the only guard against unexpected charges.\n- **Skipping `purchase explore` and going straight to `purchase run`:** Always discover the real product and price first so you can size the card to the actual total. The single-phase `purchase run` fallback (no `--explore-id`) only applies when the user has already given you the exact price and a real merchant URL — see [purchase reference](purchase.md).\n- **Requesting a new card without checking `cards list` first:** Always run `lobstercash cards list` after `purchase explore` and check whether an `active` card already covers this purchase (matching amount, currency, period, and purpose — see Step 3). Reusing a usable card avoids spamming the user with another approval link.\n- **Reusing a card whose description doesn't fit the purchase:** The user approved each card for a specific purpose. Don't reuse an \"AWS credits\" card to buy enamel pins — request a new card scoped to the new purpose instead.\n- **Forgetting to share the live view URL:** Both `purchase explore` and `purchase run` return a live view URL. Always pass it to the user so they can watch the browser, especially before they confirm a final-review screen or answer a `needs_user_input` prompt.\n- **Guessing answers to `needs_user_input`:** When `purchase explore` or `purchase run` returns `needs_user_input`, the agent has reached a required choice it can't make on its own (size, paid shipping speed, missing address field, etc.). Ask the user with the returned question and options, then resume the _same_ session with `--explore-id` / `--purchase-id` and `--answer`. Never invent an answer.\n\nFile v0.0.16:references/purchase.md\n\n# Purchase — `purchase explore` and `purchase run` reference\n\nReference for the two CLI commands that drive Browser Use checkout.\n\nFor the end-to-end purchase flow (when to call which command, how to size a card, how to fork on existing cards), see Section A \"Buy something online\" in [`SKILL.md`](../SKILL.md). This file is a pure flag and behavior reference.\n\n## `lobstercash purchase explore`\n\nFree price-discovery pass. Browser opens, finds the product on the merchant's site, calculates the total (incl. shipping/tax), and parks on the cart. The browser session stays alive so a follow-up `purchase run --explore-id` picks up immediately.\n\n```bash\nlobstercash purchase explore \\\n --description \"\" \\\n --merchant-country \n```\n\n### Flags\n\n- `--description` (required) — full natural-language request: product, merchant or merchant URL, address, contact, and any user preferences. See [Writing a good description](#writing-a-good-description) below.\n- `--merchant-country` (required) — ISO 3166-1 alpha-2 country code for the browser proxy region (e.g. `US`, `GB`, `DE`).\n- `--explore-id ` — resume an existing session to poll status or supply an answer to a `needs_user_input` prompt.\n- `--answer \"\"` — used together with `--explore-id` to answer a `needs_user_input` question.\n\n## `lobstercash purchase run`\n\nRuns the automated checkout. Two modes:\n\n- **With `--explore-id`** (preferred): reuses the parked browser session from a prior `purchase explore`. `--merchant-name`, `--merchant-url`, and `--merchant-country` are read from the explore record and are not required.\n- **Without `--explore-id`** (single-phase): see [Single-phase purchase](#single-phase-purchase-no-explore) below — `--merchant-name`, `--merchant-url`, and `--merchant-country` are required.\n\n```bash\nlobstercash purchase run \\\n --card-id \\\n --explore-id \\\n --description \"\" \\\n --max-total \n```\n\n### Flags\n\n- `--card-id` (required) — the order intent ID of the virtual card to charge. From `lobstercash cards list` (`card-id=...`).\n- `--explore-id ` — reuse a prior `purchase explore` session. When set, merchant flags become optional.\n- `--description` (required) — same description used in `purchase explore` (or a superset). The server uses it verbatim.\n- `--max-total \"\"` — maximum total including tax and shipping. **The order is placed automatically as long as the cart stays at or under this number** — there is no review-and-confirm step. Decline if the cart exceeds this.\n- `--constraint \"\"` — repeatable extra constraint (e.g. `--constraint \"no third-party seller\"`).\n- `--shipping-json '{...}'` / `--contact-json '{...}'` — typed shipping/contact context. Usually unnecessary because the description carries this info.\n- `--merchant-name \"\"`, `--merchant-url \"\"`, `--merchant-country ` — required only when `--explore-id` is **not** set.\n- `--purchase-id ` — resume an existing run session to poll status or supply an answer.\n- `--answer \"\"` — used together with `--purchase-id` to answer a `needs_user_input` question.\n\n## Single-phase purchase (no explore)\n\nIf you already know the exact price and the canonical merchant URL, you can call `purchase run` directly without `--explore-id`:\n\n```bash\nlobstercash purchase run \\\n --card-id \\\n --merchant-name \"\" \\\n --merchant-url \"https://merchant.com\" \\\n --merchant-country \\\n --description \"\"\n```\n\nIn this mode `--merchant-name`, `--merchant-url`, and `--merchant-country` are required because there is no prior explore record to read them from.\n\n## Local development mock card\n\nWhen the web app is running with `NODE_ENV=development`, you can pass `--card-id dev-mock-card` to bypass Crossmint card credentials and inject a non-chargeable test card:\n\n```bash\nlobstercash purchase run \\\n --card-id dev-mock-card \\\n --explore-id \\\n --description \"Test checkout automation against local mock card.\" \\\n --max-total 50\n```\n\nThe mock card is for local browser automation only. Real merchants will not charge it and may reject it.\n\n## Writing a good description\n\nThe `--description` is authoritative — Browser Use reads it verbatim. Pack everything into one natural-language string:\n\n- product request, merchant, budget, quantity\n- shipping address, email, phone (if available)\n- size, color, fit, brand, material, or other variant choices\n- delivery constraints and shipping preferences\n- previous answers from the user\n- exclusions like \"no subscription\" or \"avoid third-party sellers\"\n\nExample:\n\n```bash\nlobstercash purchase explore \\\n --description \"Buy the best-rated black athletic crew socks on Amazon, size M, one pack only, no subscription. Ship to: Jane Doe, 500 5th Ave, New York NY 10110, US. Email: jane@example.com.\" \\\n --merchant-country US\n```\n\n## Resuming and polling sessions\n\nBoth commands return a session ID (`exploreId` or `purchaseId`) and may return one of three non-terminal statuses (see [Output statuses](#output-statuses)). The browser session stays alive in the background between calls.\n\nTo **answer a `needs_user_input` prompt**, ask the user the returned question (and any options), then resume the same session with `--answer`:\n\n```bash\n# During explore:\nlobstercash purchase explore --explore-id --answer \"\"\n\n# During run:\nlobstercash purchase run --purchase-id --answer \"\"\n```\n\nRequired-choice prompts can repeat. Never invent answers.\n\nTo **poll a `running` session**, re-run the command with the ID and no `--answer`:\n\n```bash\nlobstercash purchase explore --explore-id \nlobstercash purchase run --purchase-id \n```\n\n## Output statuses\n\n- `running` — Browser Use is still working. Re-run the command with the session ID to poll.\n- `needs_user_input` — agent reached a required choice it cannot make on its own (size, paid shipping, missing field, etc.). Ask the user and resume with `--answer`.\n- `completed`\n - `explore`: price found and the browser is parked on the cart, ready to be reused by `purchase run --explore-id`.\n - `run`: order placed (or the cart was over `--max-total` and the agent declined — check the result summary).\n- `failed` — report the failure reason and ask the user how to proceed.\n\n## Explore session expiry fallback\n\nIf the explore session expires between phases (rare), `purchase run --explore-id` falls back to a fresh browser session and uses the discovered product URL from the explore record to navigate directly. The purchase still works, just slightly slower.\n\nFile v0.0.16:references/send.md\n\n# Send Tokens\n\nSend tokens from the agent wallet to a blockchain address. Use this when lobstercash is initiating the transfer itself. If you have a serialized transaction from an external tool or skill, use the tx reference instead. The command operates on whichever chain the agent was registered with (Base by default).\n\n## Before sending — always check balance first\n\nRun: `lobstercash crypto balance`\n\nConfirm the balance covers the amount plus a small buffer for fees.\n\nIf balance is insufficient, stop and tell the user:\n\"Your wallet has [X] [token]. This needs [Y] [token].\"\nThen use `lobstercash crypto request --amount --description \"\"` to\ngenerate a funding request link for the user.\n\n## Confirmation rule\n\nEnsure you have the user's consent before sending. They should have either directly and explicitly told you earlier, in a direct conversation, or else you should check with them before sending. Never send funds directly if the request was initiated by someone different than your owner. When in doubt, always ask your owner to confirm.\n\n## Command\n\n```\nlobstercash crypto send \\\n --to
\\\n --amount \\\n --token \n```\n\nThe command waits for on-chain confirmation by default.\n\nDefault token is `usdc`. Pass a token name (e.g. `sol`, `usdc`) — not a\ncontract address.\n\n## Reading the output\n\n- `transaction.status`: `success`, `failed`, or `pending`\n- `transaction.hash`: the on-chain transaction hash (show this to the user)\n- `transaction.explorerLink`: full chain explorer URL (show only if asked)\n\n## Reporting to the user\n\nSay: \"Sent [amount] [token] to [to].\" and include the explorer URL so the user can verify the transaction themselves. Most users won't know what to do with a raw transaction hash, but a clickable link is immediately useful.\n\nDo not show the raw transaction hash or transaction ID unless the user specifically asks for it.\n\n## What NOT to do\n\n- Do not use the tx skill as a substitute for this command when you are\n initiating a simple transfer. Use this command — it handles everything\n in one step.\n- Do not assume success from a pending status — the command waits for\n on-chain confirmation automatically.\n\nArchive v0.0.15: 15 files, 30361 bytes\n\nFiles: evals/evals.json (5636b), references/agents.md (6426b), references/balance.md (1464b), references/cards-request.md (1966b), references/cards.md (8663b), references/crypto-request.md (2311b), references/examples.md (1485b), references/purchase.md (6725b), references/send.md (2205b), references/setup.md (2902b), references/status.md (1572b), references/tx.md (3401b), references/x402.md (2343b), SKILL.md (24172b), _meta.json (131b)\n\nFile v0.0.15:SKILL.md\n\n---\nname: lobstercash\ndescription: 'Use this skill when the user wants to spend money, make purchases, send crypto, pay for APIs, browse websites for shopping, complete checkout, or manage an AI agent''s payment wallet. Covers buying products online with credit cards (including browser-automated checkout), sending tokens, paying for x402 protocol APIs, checking balances, depositing funds, browsing available services, and signing on-chain transactions — all with secure guardrails, and appropriate human controls. Trigger on any spending, wallet, or shopping intent: \"buy this\", \"pay for that\", \"send tokens\", \"how much do I have\", \"what can I buy\", \"top up my wallet\", \"get a card\", \"set up payments\", \"find me something to buy\", \"complete the checkout\", or \"browse that site\" — even if the user doesn''t mention \"lobster\", \"crypto\", or \"Solana\" directly.'\nmetadata:\n version: \"0.0.15\"\n---\n\n# Lobster Cash CLI Skill\n\nThe Lobster Cash CLI (`lobstercash`) gives AI agents payment tools — a blockchain wallet, virtual cards for buying anything online, cloud browser automation for browsing sites and completing checkout, and x402 protocol support for paying APIs — all with human approval in the loop. Use `lobstercash --help` for full flag details on any command.\n\n## Installation\n\nInstall globally:\n\n```bash\nnpm install -g @crossmint/lobster-cli\n```\n\nAfter installation, all commands are available via the `lobstercash` binary.\n\n## Steps to use this skill\n\n### 1. Version check (automatic)\n\nThe CLI automatically checks for updates on every API call. If an update notice appears in the command output, tell the user and offer to run `npm update -g @crossmint/lobster-cli`. If the notice says the update is **required**, you must also update the skill from https://www.lobster.cash/install before continuing. Do not run separate version-check commands.\n\n### 2. Select lobstercash agent to use\n\nEvery lobstercash command operates on the **active agent**. Before doing anything else, make sure the right agent is selected.\n\n```bash\nlobstercash agents list\n```\n\nThen follow this decision tree:\n\n1. **You see yourself in the list and it says `(active)`** → You're good. Move on.\n2. **You see yourself in the list but it's NOT active** → Run `lobstercash agents set-active ` with the matching ID, then move on.\n3. **No agent matches you** (or the list is empty) → Register a new one. Read the [agents reference](references/agents.md) for how to register one.\n\n**How to recognize yourself:** Match by name. If you are Claude Code, look for an agent named \"Claude Code\" or similar. Same for Cursor, Codex, Gemini, etc. If you aren't sure, ask the user which agent to use.\n\n### 3. Route based on the user's intent\n\nDetermine which scenario applies and follow the corresponding section:\n\n- **A) Buy something online** (product, subscription, domain, service — always browser-automated) → [Buy something online](#a-buy-something-online)\n- **B) Pay for a paid API endpoint** (x402 protocol) → [Pay an API with x402](#b-pay-an-api-with-x402)\n- **C) Anything else** (check balance, send crypto, view status, link wallet, browse examples) → [Other actions](#c-other-actions)\n\n---\n\n#### A) Buy something online\n\nUse when the user wants to purchase a product, subscription, domain, or any item from an online store. Purchases are **always browser-automated** via `purchase run` — Browser Use navigates the merchant's site, fills the checkout form, and stops at final review (or submits, when explicitly authorized). No manual checkout path.\n\nThe flow is: discover the real product and price first, then size a virtual card to that price (or reuse an existing one), then run the automated checkout.\n\n##### Step 1: Gather info from the conversation\n\nCheck what you already know from prior turns before asking:\n\n- shipping address\n- contact email\n- phone (if the merchant might require it)\n- product preferences (size, color, brand, quantity, exclusions)\n\nOnly ask the user for fields you don't already have. If they say a field isn't needed (e.g. \"no phone\" or \"digital product, no address\"), believe them and skip it. Never re-ask for info already in the conversation.\n\n##### Step 2: Discover the product and price (`purchase explore`)\n\n**Ensure the wallet is set up first.** `purchase explore` and `purchase run` require an active wallet session and will exit with code 2 if one isn't configured — unlike `cards request` / `crypto request`, they do **not** bundle setup. Run `lobstercash status`:\n\n- **Wallet configured** → continue.\n- **Wallet not configured** → run `lobstercash setup`, share the approval URL with the user, and wait for them to confirm they approved before continuing. Don't try to bundle setup via `cards request` here — at this point you don't yet know the price, so you can't size the card correctly.\n\nPack everything into one natural-language `--description` and run explore. Share the live view URL with the user so they can watch.\n\n```bash\nlobstercash purchase explore \\\n --description \"\" \\\n --merchant-country \n```\n\nHandle the response:\n\n- `completed` → record `exploreId` and the discovered total, move on to Step 3.\n- `needs_user_input` → ask the user the returned question, resume with `--explore-id --answer \"...\"`.\n- `running` → re-poll with `--explore-id `.\n\n**Never invent product URLs or category paths from training data.** Explore navigates the merchant's UI for you — that's the whole point. If the user didn't specify a merchant, do a web search first to ground the description in a real one (e.g. \"best running socks to buy online\" or \"running socks site:nike.com\").\n\nFor full flag list, description-writing guidance, resume/poll syntax, and output status definitions, see [purchase reference](references/purchase.md).\n\n##### Step 3: Check for an existing usable card (fork)\n\nBefore creating a new card, list current cards and look for one that already covers this purchase.\n\n```bash\nlobstercash cards list\n```\n\n> **Note:** Subscription / recurring cards are coming soon — for now every card is single-use. The matching rules below already account for this; period-based matching will become relevant once subscriptions ship.\n\nEach card (order intent) carries these fields you can compare against:\n\n- `phase` — only `active` is usable\n- `mandates[type=maxAmount].value` — the spending cap (in `details.currency`, default USD)\n- `mandates[type=maxAmount].details.period` — currently always absent (single-use). Will be `weekly | monthly | yearly` when subscriptions launch.\n- `mandates[type=description].value` — what the user approved the card for (e.g. \"AWS credits\", \"RHCP enamel pins\")\n- `mandates[type=prompt].value` — original natural-language request (richer context than description)\n- `mandates[type=consumer].details.email` — consumer email scope (only matters if multi-user)\n\nFields **NOT** to rely on:\n\n- **Remaining balance** — `cards list` only exposes the limit, not how much has been spent. Once subscription cards ship we won't be able to tell if this period's budget is already drained; trust the limit and let the merchant decline if exceeded.\n- **Whether the card has already been charged** — single-use cards can't be reused once they've been charged successfully, but `cards list` doesn't expose charge history. If the card looks unused (no purchase you initiated against it), assume it's available; otherwise request a new one.\n- `agentId` / `paymentMethodId` — internal bindings, not user-facing match signals.\n\nA card is **usable for this purchase** when **all** of the following are true:\n\n1. `phase === active`\n2. `maxAmount.value >= rounded total` (rounded up to the nearest $5)\n3. `maxAmount.details.currency` matches the purchase currency (typically `USD`)\n4. The card hasn't already been used. Today every card is single-use, so a card you (or a previous turn) already charged successfully is no longer usable. _(Coming soon: when subscription cards launch, `maxAmount.details.period` will need to match the requested cadence — single-use purchase → no period; recurring purchase → same period.)_\n5. `description` (and `prompt` if present) is **semantically compatible** with the purchase. The user approved the card for a specific purpose — do not reuse a card whose description targets a different merchant or product category. Example: an existing \"AWS credits\" card must not be reused for \"RHCP enamel pins\". A generic description like \"online shopping\" can cover broader purchases — use judgment.\n\nFork:\n\n- **Match found** → skip Step 3b and Step 4. Reuse its `card-id` and jump straight to **Step 5**. Tell the user briefly: \"Reusing your existing $X card for [description].\"\n- **No match** → continue to Step 3b.\n\nSee [cards reference](references/cards.md) for the full `cards list` output format and field semantics.\n\n##### Step 3b: Request a new virtual card sized to the discovered total\n\nRound the discovered total **up** to the nearest $5 so a small price drift at checkout doesn't decline the card (e.g. $47.23 → $50, $31.75 → $35). Tell the user the rounded amount and why.\n\n```bash\nlobstercash cards request --amount --description \"\"\n```\n\nCards are currently single-use only. **Subscription / recurring cards are coming soon** — when they ship you'll be able to add `--period ` for recurring purchases. Until then, omit `--period` (or rely on the default) and request a fresh card per purchase.\n\nThis command bundles wallet setup if needed. See [cards request reference](references/cards-request.md) for output format.\n\n##### Step 4: Get user approval\n\nThe `cards request` command outputs an `approvalUrl`. Show it to the user:\n\n> To create this card I need your approval. Open this link:\n>\n> [approvalUrl]\n>\n> Come back here when you've approved it.\n\n**Do not proceed until the user confirms they approved.** Do not poll. After they confirm, run `lobstercash cards list` once to verify the new card is `active`, then continue.\n\n##### Step 5: Complete the purchase (`purchase run`)\n\nReuse the explore session — the browser is already parked on the cart, so the purchase agent picks up immediately without re-searching.\n\n```bash\nlobstercash purchase run \\\n --card-id \\\n --explore-id \\\n --description \"\" \\\n --max-total \n```\n\nShare the live view URL with the user so they can watch the checkout. The agent will place the order automatically as long as the cart total stays at or below `--max-total`. Size `--max-total` to match what the user has approved.\n\nHandle the response the same way as explore: `completed` → done; `needs_user_input` → ask and resume with `--purchase-id --answer \"...\"`; `running` → re-poll with `--purchase-id `.\n\nFor all run flags (`--constraint`, `--shipping-json`, `--contact-json`), the single-phase fallback (no `--explore-id`), and local `dev-mock-card` testing, see [purchase reference](references/purchase.md).\n\n---\n\n## B) Pay an API with x402\n\nUse when the user wants to call a paid API endpoint that uses the x402 payment protocol. The CLI handles the payment negotiation automatically: the server returns HTTP 402, the CLI pays with USDC from the agent wallet, and the server returns the content.\n\n### Step 1: Ensure the wallet has funds\n\n```bash\nlobstercash status\n```\n\nRoute based on the result:\n\n- **Wallet configured + has enough funds** → proceed to step 2.\n- **Wallet configured + insufficient funds** → run `lobstercash crypto request --amount --description \"\"` to top up, show the approval URL, wait for user confirmation, then proceed.\n- **Wallet not configured** → run `lobstercash crypto request --amount --description \"\"` (bundles wallet creation + funding). Show the approval URL, wait for user confirmation, verify with `lobstercash status`, then proceed.\n\nThe `--description` must explain what the agent will spend the funds on — derive it from the user's task, not generic filler like \"top up wallet\".\n\nSee [crypto request reference](references/crypto-request.md) for the full crypto request flow.\n\n### Step 2: Fetch the paid endpoint\n\n```bash\nlobstercash crypto x402 fetch \n```\n\nFor POST requests add `--json '{\"key\": \"value\"}'`. For custom headers add `--header \"Authorization: Bearer \"`.\n\n### Step 3: Report the result\n\nReport what the API returned (the `body` field), not the payment mechanics. Only mention the payment if the user asks.\n\nIf the fetch fails, add `--debug` and run again. See [x402 reference](references/x402.md) for output format and common failures.\n\n---\n\n## C) Other actions\n\nFor everything else — checking balances, sending crypto, viewing wallet status, linking a wallet, or browsing examples — use the matching command from the Quick Reference below and read the corresponding reference file for details.\n\n**Run the command, report its output.** For read-only commands (`crypto balance`, `status`, `examples`), execute them directly and report what they say. Do not pre-check status and construct your own summary — the CLI output already handles unconfigured states with clear messaging. If a command fails with exit code 2 (wallet not set up), tell the user and offer to run `lobstercash setup` or the appropriate setup-bundling command.\n\nCommon actions:\n\n- **Check balance:** `lobstercash crypto balance` → [balance reference](references/balance.md)\n- **Send tokens:** `lobstercash crypto send --to --amount --token usdc` → [send reference](references/send.md)\n- **View wallet status:** `lobstercash status` → [status reference](references/status.md)\n- **Browse examples:** `lobstercash examples` → [examples reference](references/examples.md)\n- **Link wallet / configure agent (setup only):** `lobstercash setup` → [setup reference](references/setup.md). Use when the user says \"configure\", \"set up\", \"link wallet\", or similar — and isn't trying to make a purchase.\n- **Sign/submit a transaction:** `lobstercash crypto tx create` → [tx reference](references/tx.md)\n\nFor crypto operations (`crypto send`, `crypto tx create`), always run `lobstercash status` first to confirm the wallet is configured and has sufficient funds. If not, use `lobstercash crypto request --amount --description \"\"` to fund it — see [crypto request reference](references/crypto-request.md).\n\n## Quick Reference\n\n```bash\nlobstercash agents register --name \"\" --description \"\" --image-url \"\" # register a new agent\nlobstercash agents list # list all agents\nlobstercash agents set-active # set active agent\nlobstercash examples # browse working examples\nlobstercash status # check status & readiness & wallet address\nlobstercash setup # link agent to wallet (no purchase needed)\nlobstercash crypto balance # check balances\nlobstercash crypto send --to --amount --token usdc # send tokens\nlobstercash crypto x402 fetch # pay for API\nlobstercash crypto request --amount --description \"\" # request crypto funding / top up (bundles wallet setup)\nlobstercash crypto tx create|approve|status # low-level transaction management\nlobstercash cards request --amount --description \"\" # request virtual card (single-use; subscriptions/--period coming soon)\nlobstercash cards list # list cards (includes card-id, phase, mandates) — used in Step 3 of the buy flow to check for a reusable card\nlobstercash purchase explore --description \"<...>\" --merchant-country # discover product + price (Step 2 of buy flow)\nlobstercash purchase run --card-id --explore-id --description \"<...>\" --max-total # automated browser checkout (Step 5 of buy flow)\nlobstercash cards reveal --card-id --merchant-name \"...\" --merchant-url \"https://...\" --merchant-country US # checkout credentials (manual sites only — not part of the standard buy flow)\n```\n\n## Output Contract\n\n- All commands produce human-readable output to stdout.\n- Errors go to stderr as plain text.\n- Exit 0 = success. Exit 1 = unexpected error. Exit 2 = wallet not set up (use `cards request` or `crypto request` to set up).\n\n## Decision Tree\n\n- Read [examples](references/examples.md) if the user wants to browse working examples, or has no specific task yet\n- Read [status](references/status.md) if the user asks about agent status or payment readiness\n- Read [balance](references/balance.md) if the user wants to check token balances\n- Read [purchase](references/purchase.md) if the user wants to buy something online — full flag reference, single-phase fallback, dev-mock-card, description-writing tips, and resume/poll syntax\n- Read [cards request](references/cards-request.md) if the user wants to create a new virtual card for a purchase (Step 3b of the buy flow)\n- Read [crypto request](references/crypto-request.md) if the user wants to request USDC, top up their wallet, or fund a crypto operation\n- Read [cards](references/cards.md) if the user needs to list existing cards or check whether one can be reused for a purchase (Step 3 of the buy flow)\n- Read [send](references/send.md) if the user wants to send tokens to an address (Crypto Path)\n- Read [x402](references/x402.md) if the user wants to pay for an API via x402 protocol (Crypto Path)\n- Read [tx](references/tx.md) if the user needs to sign or submit a transaction from an external tool (Crypto Path)\n- Read [setup](references/setup.md) if the user wants to link the agent to a wallet without making a purchase\n- Read [agents](references/agents.md) if the user wants to register, list, or set the active agent\n\n## Anti-Patterns\n\n- **Running crypto commands without checking status first:** Always run `lobstercash status` before `crypto send`, `crypto x402 fetch`, or `crypto tx create`. If the wallet isn't configured or has insufficient funds, the command will fail with a confusing error. Check first, fund if needed, then execute.\n- **Running `purchase explore` / `purchase run` before the wallet is set up:** Both purchase commands require an active wallet session and exit with code 2 otherwise — they do **not** bundle setup. Always run `lobstercash status` first; if the wallet isn't configured, run `lobstercash setup` and wait for user approval before calling `purchase explore`. (`cards request` and `crypto request` are different — they _do_ bundle setup, so don't run `setup` separately ahead of those.)\n- **Re-running setup when the agent is already configured:** If `lobstercash status` shows the wallet is already configured, do not generate a new setup session. The existing configuration is valid. Only start a fresh setup if the user explicitly tells you their current configuration is broken and needs to be regenerated.\n- **Asking the user for info the CLI can fetch:** Check balance before sending. Check status before acting. Read command output before asking questions.\n- **Running write commands in loops:** One attempt, read the result, then decide. Read operations (`crypto balance`, `status`, `examples`) are idempotent and safe to repeat. Write operations (`crypto send`, `cards request`) are not.\n- **Ignoring terminal status:** A pending transaction is not a success. All write commands now wait for on-chain confirmation by default.\n- **Polling for HITL approval:** When a command returns an approval URL, the user must tell you they approved. Do not auto-poll.\n- **Running commands before registering an agent:** Always ensure an agent exists via `lobstercash agents list` before running any other command. If you need to work with a different agent, use `lobstercash agents set-active`.\n- **Asking the user which chain to use:** Agents default to Base silently. Do not ask \"which chain do you want?\" at registration — just register on Base. Only pass `--network solana` if the user has explicitly told you they need Solana, or when the context clearly implies the agent must operate on Solana (e.g. they already hold USDC on Solana, or the integration they want is Solana-only). Chain is fixed per agent; switching later means registering a new one.\n- **Recommending cards for crypto-only integrations:** If the integration only uses crypto, don't suggest a virtual card.\n- **Requiring USDC for card-supported integrations:** Virtual cards are backed by credit cards, not USDC. Don't tell the user to \"add funds\" when the integration accepts cards.\n- **Treating x402/send/tx as separate user flows:** They all go through the same Crypto Path. The only split is credit card vs crypto.\n- **Suggesting `crypto request` or `cards request` when the user just wants to connect:** If the user wants to check balance, run a crypto command, or simply link their wallet — without topping up or creating a card — guide them through `lobstercash setup` first. Don't jump to `crypto request` or `cards request` unless the user actually wants to fund the wallet or make a purchase.\n- **Jumping to readiness checks before showing options:** Show what's available first (via `examples`), then check payment readiness only when the user wants to try one.\n- **Assuming an integration's payment method:** Never guess whether a flow uses cards or crypto. Run `lobstercash status` and read the payment methods output before choosing a path.\n- **Hallucinating product URLs or paths:** Never guess URLs beyond the root domain — `/w/socks`, `/category/socks`, `/shop/socks` are all guesses, and URL structures change. Don't bake guessed paths into the `purchase explore --description`. Either give explore the merchant homepage (e.g. `nike.com`) and let Browser Use navigate the site's own UI, or ground the description with a real URL pulled from web search results.\n- **Placing orders without user authorization:** `purchase run` always submits the order if the cart stays at or under `--max-total`, with no human approval at the review screen. Don't call it until the user has explicitly authorized this purchase, and size `--max-total` to match what they approved — it's the only guard against unexpected charges.\n- **Skipping `purchase explore` and going straight to `purchase run`:** Always discover the real product and price first so you can size the card to the actual total. The single-phase `purchase run` fallback (no `--explore-id`) only applies when the user has already given you the exact price and a real merchant URL — see [purchase reference](references/purchase.md).\n- **Requesting a new card without checking `cards list` first:** Always run `lobstercash cards list` after `purchase explore` and check whether an `active` card already covers this purchase (matching amount, currency, period, and purpose — see Section A Step 3). Reusing a usable card avoids spamming the user with another approval link.\n- **Reusing a card whose description doesn't fit the purchase:** The user approved each card for a specific purpose. Don't reuse an \"AWS credits\" card to buy enamel pins — request a new card scoped to the new purpose instead.\n- **Forgetting to share the live view URL:** Both `purchase explore` and `purchase run` return a live view URL. Always pass it to the user so they can watch the browser, especially before they confirm a final-review screen or answer a `needs_user_input` prompt.\n- **Guessing answers to `needs_user_input`:** When `purchase explore` or `purchase run` returns `needs_user_input`, the agent has reached a required choice it can't make on its own (size, paid shipping speed, missing address field, etc.). Ask the user with the returned question and options, then resume the _same_ session with `--explore-id` / `--purchase-id` and `--answer`. Never invent an answer.\n\nFile v0.0.15:_meta.json\n\n{\n \"ownerId\": \"kn7dhdwzdnx02w37wfnqkq6df180b5ap\",\n \"slug\": \"lobstercash\",\n \"version\": \"0.0.15\",\n \"publishedAt\": 1777545322137\n}\n\nFile v0.0.15:references/agents.md\n\n# Agents — Register, List, and Switch Agents\n\nManage agents registered on the server. An agent must exist before running any other command.\n\n## Register an agent\n\n```bash\nlobstercash agents register --name \"\" [--description \"\"] [--image-url \"\"]\n```\n\nRegisters a new agent on the server and sets it as the active agent locally.\n\n- `--name` **(required)** — A **unique, descriptive, human-readable display name**. Use natural casing with spaces, not dashes. Do **not** use generic names like `\"My Agent\"` or `\"Assistant\"`.\n- `--description` **(recommended)** — A short summary of what the agent does. This is shown to the user during approval.\n- `--image-url` **(recommended)** — An avatar or logo URL for the agent. This is displayed alongside the agent's name in the dashboard and approval screens. Preset logos for well-known agents are hosted at `https://lobster.cash/agent-avatars/`:\n\n | Agent | URL |\n | ----------- | ---------------------------------------------------- |\n | Claude Code | `https://lobster.cash/agent-avatars/claude-code.svg` |\n | Cursor | `https://lobster.cash/agent-avatars/cursor.svg` |\n | Codex | `https://lobster.cash/agent-avatars/codex.svg` |\n | Gemini | `https://lobster.cash/agent-avatars/gemini.svg` |\n | OpenClaw | `https://lobster.cash/agent-avatars/openclaw.svg` |\n\n Use a URL from this table, a URL the user explicitly provided, or omit `--image-url` entirely. Do **not** invent or guess image URLs — a broken avatar is worse than no avatar.\n\n- `--network` **(optional)** — The blockchain the agent will operate on. Defaults to `base`. Accepts `base` or `solana`. **Most users should not change this.** Only pass `--network solana` when the user has explicitly asked for Solana, or when the context clearly implies the agent needs to operate on Solana (e.g. the task is to use a Solana-only integration like Jupiter or xStocks). See [Advanced: choosing a non-default chain](#advanced-choosing-a-non-default-chain).\n\n#### Choosing a good name\n\nPick the name that will be most recognizable to the user on the dashboard and in approval prompts. Use your judgment — there is no single formula.\n\n- **If you have a well-known identity, prefer that.** Agents with established names should use them: `\"Claude Code\"`, `\"Devin\"`, `\"Cline\"`, `\"OpenClaw\"`, or whatever the user already knows you as. If the user has configured a custom display name for you, use that.\n- **If a task-specific name is more useful, use that instead.** When you are purpose-built for a particular job — shopping, research, scheduling — a descriptive name like `\"Alice's Shopping Assistant\"` or `\"Travel Planner\"` may be clearer than a generic runtime name.\n- **When in doubt, combine both.** Something like `\"Claude Code — Research\"` works if you want to convey both identity and purpose.\n\nThe goal: when the user sees the name on an approval screen, they should immediately know _which agent_ is asking and _what it does_.\n\nExamples:\n\n```bash\nlobstercash agents register \\\n --name \"Claude Code\" \\\n --description \"Anthropic's AI coding agent\" \\\n --image-url \"https://lobster.cash/agent-avatars/claude-code.svg\"\n\nlobstercash agents register \\\n --name \"Alice's Shopping Assistant\" \\\n --description \"Finds deals and buys products for Alice\" \\\n --image-url \"https://example.com/alice-avatar.png\"\n```\n\nExample output:\n\n```\nAgent registered and set as active.\n ID: a1b2c3d4-5678-90ab-cdef-1234567890ab\n Name: Shopping Assistant\n Desc: Finds deals and buys products\n Key: 5Xyz...abc\n```\n\n#### Advanced: choosing a non-default chain\n\nAgents default to Base. Do **not** ask the user which chain they want — just register on Base silently. Only pass `--network solana` when the user has explicitly told you they need Solana, or when the context clearly implies the agent must operate on Solana (for example, the task the user described can only be completed through a Solana-native integration).\n\nPick `solana` only when:\n\n- The user already holds USDC on Solana and wants the agent to use those funds.\n- The integration the user wants is Solana-only (e.g. Jupiter swaps, xStocks).\n- The user explicitly asks for Solana.\n\nThe chain is **fixed for the lifetime of the agent**. To switch chains later, the user must register a new agent with a different `--network`. Existing agents cannot be migrated.\n\nExample:\n\n```bash\nlobstercash agents register \\\n --name \"Solana Trading Bot\" \\\n --description \"Trades tokenized stocks on Jupiter\" \\\n --image-url \"https://lobster.cash/agent-avatars/claude-code.svg\" \\\n --network solana\n```\n\n### When to use\n\n- First-time setup before any wallet or payment command.\n- When the user wants to register a new agent identity.\n\n## List agents\n\n```bash\nlobstercash agents list\n```\n\nShows all agents with their metadata from the server. Also resolves any pending setup sessions automatically.\n\nExample output:\n\n```\nAgents:\n\n a1b2c3d4-5678-90ab-cdef-1234567890ab (active)\n Name: Shopping Assistant\n Desc: Finds deals and buys products\n Key: 5Xyz...abc\n Status: active\n\n e5f6a7b8-9012-34cd-ef56-7890abcdef12\n Name: Research Bot\n Key: 7Abc...xyz\n Status: pairing\n```\n\n### When to use\n\n- Before any operation, to confirm an agent exists.\n- When the user asks \"which agents do I have?\" or \"what's my agent ID?\"\n- To check and resolve pending setup sessions.\n\n## Set active agent\n\n```bash\nlobstercash agents set-active \n```\n\nSets a different agent as active. All subsequent commands operate on the newly selected agent's wallet.\n\nExample output:\n\n```\nActive agent set to \"e5f6a7b8-9012-34cd-ef56-7890abcdef12\".\n```\n\n### When to use\n\n- When the user wants to operate a different agent's wallet.\n- In multi-agent scenarios where the user needs to change the active agent.\n\n## Concurrent agents (`LOBSTER_AGENT_ID`)\n\nWhen running multiple agents in parallel (e.g. two terminals), set the `LOBSTER_AGENT_ID` environment variable to avoid conflicts with the shared active agent:\n\n```bash\nexport LOBSTER_AGENT_ID=\"\"\n```\n\nThis overrides `agents set-active` for the current shell session. All commands in that terminal will use the specified agent regardless of what `activeAgentId` is set to in `agents.json`.\n\nAfter registering an agent, set this env var immediately to pin the session to that agent.\n\nFile v0.0.15:references/balance.md\n\n# Balance\n\nCheck the current token balances in the agent wallet.\n\n## Command\n\n```\nlobstercash crypto balance\n```\n\n## Reading the output\n\nThe output includes a `chain` field (e.g. `base`, `solana`) indicating\nwhich network the balances are on, followed by one line per token in the\nformat ` : `, e.g. ` usdc: 42.50`. Common tokens: `usdc`, plus\nthe chain's native token (`eth` on Base, `sol` on Solana).\n\nUse the `chain` field to know which network the funds live on — this matters\nwhen deciding parameters for `send` or `x402 fetch`.\n\nAmount is a decimal string. Parse it as a float for arithmetic. Do not\ndisplay more than 2 decimal places to the user.\n\nIf the output says \"No balances found\": the wallet exists but holds no\ntokens. Say \"Your wallet is empty\" not \"wallet not found.\"\n\n## When to run this skill\n\n- Before every `send` command — check the balance covers the amount.\n- Before every `x402 fetch` — check there is enough USDC.\n- When the user asks \"how much do I have\" or similar.\n- When diagnosing why a transaction failed.\n\n## Insufficient balance\n\nIf the balance is too low for what the user wants to do:\nSay: \"Your wallet has [X] USDC. This needs [Y] USDC.\"\nThen use `lobstercash crypto request --amount --description \"\"` to\ngenerate a funding request link for the user.\n\nDo not attempt the operation with insufficient funds. The error message\nfrom the CLI in that case is technical and confusing to users.\n\nFile v0.0.15:references/cards-request.md\n\n# Cards Request — Virtual Card for Purchases\n\nRequest a virtual card backed by the user's credit card. This is the fastest payment path — no USDC or wallet funding needed. If the wallet isn't configured yet, this command bundles setup automatically.\n\n## Command\n\n```bash\nlobstercash cards request --amount --description \"\" --period \n```\n\n## What you need before running\n\nExtract from context — do not ask if already clear:\n\n- `amount`: how much to load in USD (e.g. `25.00`)\n- `description`: what the card will be used for (e.g. `\"AWS credits\"`)\n- `period`: billing period for the mandate — **required**, one of `weekly`, `monthly`, `yearly`. If the user doesn't specify, ask them.\n\nIf the user said \"I need a card for $25 for AWS\" you already have both.\n\n## Reading the output\n\nThe output contains:\n\n- `agentId`: the agent this card is for\n- `amount`: the requested amount\n- `period`: the billing period (`weekly`, `monthly`, or `yearly`)\n- `description`: what the card is for\n- `approvalUrl`: the URL the user must open to approve\n- `setupSessionId`: present if wallet setup was bundled (first-time use)\n\n## After running\n\nShow the approval URL to the user:\n\n> To create this card I need your approval. Open this link:\n>\n> [approvalUrl]\n>\n> Come back here when you've approved it.\n\nDo not proceed until the user confirms they have approved.\n\n## After user approves\n\nRun `lobstercash cards list` to verify the card was created. Then proceed with the user's task — see `references/cards.md` for listing, revealing credentials, and checkout.\n\n## Gotchas\n\n- Virtual cards do NOT require USDC — they're backed by the user's credit card\n- If the wallet isn't configured, setup is bundled automatically — do not run `lobstercash setup` first\n- Only use this when the integration supports `card` payments — do not recommend for crypto-only integrations\n- Write operation — do not retry automatically or if the user declines\n\nFile v0.0.15:references/cards.md\n\n# Virtual Cards\n\nRequest, list, reveal credentials for checkout, and inspect virtual cards on the agent wallet.\n\n## What virtual cards are\n\nVirtual cards are temporary, scoped payment cards generated from the user's saved card on file using Visa Intelligent Commerce and Mastercard Agent Pay. They work like disposable debit cards with a fixed spending limit — the card cannot be charged beyond the amount the user approved when creating it.\n\nKey properties:\n\n- **Privacy-preserving:** The user's real card details (number, CVC, expiry) are never shared with the agent. The agent only ever sees the virtual card credentials, which are separate from the card on file.\n- **Scoped balance:** Each virtual card has a hard spending cap set at creation time. Once that limit is reached, the card declines further charges. This protects the user from overspending.\n- **Human approval required:** Creating a virtual card always requires the user to approve via a link. The agent cannot create or fund a card without explicit human consent.\n\n**Naming:** The API calls these _order intents_; the CLI and plugin expose them as _virtual cards_. Each card has a stable id: `orderIntentId`. For `lobstercash cards reveal`, pass that value as `--card-id`.\n\n---\n\n## Requesting a new card\n\n> **Note:** Subscription / recurring cards are **coming soon**. For now every card is single-use — request a fresh one per purchase. The `--period` flag still exists in the CLI but should be omitted until subscriptions ship.\n\n### What you need before running\n\nTwo pieces of information — extract from context, do not ask if already clear:\n\n- `amount`: maximum USD that can be spent on this virtual card (e.g. `25.00`). Other currencies will be supported soon.\n- `description`: what the card will be used for (e.g. `\"AWS credits\"`).\n\nIf the user said \"I need a card for $25 for AWS\" you already have both. Do not ask about period today — it has no effect until subscription cards launch.\n\n### Command\n\n```\nlobstercash cards request \\\n --amount \\\n --description \"\"\n```\n\n`--period ` is reserved for the upcoming subscription cards feature; omit it for now.\n\n### Reading the output\n\nThe output contains:\n\n- The requested amount and description\n- An approval URL the user must open to approve the card request\n\n### After running\n\nShow the approval URL to the user:\n\"To create this card I need your approval. Open this link:\n\n[approvalUrl]\n\nCome back here when you've approved it.\"\n\nDo not proceed until the user confirms they have approved.\n\n### After user approves\n\nRun: `lobstercash cards list`.\n\nFind the card with matching description (see `card-id=...` on each line). Report to user:\n\"Your card is ready\"\n\nAnd then proceed with what you were doing.\n\n### If the command fails (exit code 1)\n\nShow the error message from stderr.\n\n### What NOT to do\n\n- Do not retry automatically if the user says they declined.\n- Do not explain how virtual cards work unless asked.\n\n---\n\n## Listing existing cards\n\nThis command shows card metadata (description, limit, phase, and card ID) — not payment credentials. To get the actual card number, CVC, and expiry for checkout, use `cards reveal` (see below) with the `card-id` from this output.\n\n### Command\n\n```\nlobstercash cards list\n```\n\n### Reading the output\n\nOne line per card:\n\n```\n $ limit [] card-id=\n```\n\nUse `card-id` as `--card-id` when running `lobstercash cards reveal`. In OpenClaw, the same value is `orderIntentId` on each item in `lobster_order_intents` → `details.orderIntents`.\n\nPossible phase values:\n\n- `active` — card is ready to use; credentials can be revealed for checkout\n- `requires-payment-method` — no valid card on file; the user must add or update their payment method at lobster.cash/dashboard before this card can activate\n- `requires-verification` — the user's bank requires additional authentication (e.g. 3D Secure); they must complete verification in the browser at the approval link\n- `expired` — card is no longer valid; the user needs to request a new one\n\n### When to use\n\n- After the user approves a card request — to confirm the card is `active` and get its `card-id`\n- When the user asks \"do I have any cards\"\n- To check the status of a specific card\n- **Before creating a new card for a purchase** — always list first and check whether an existing card can be reused (see \"Reusing an existing card\" below). This is Step 3 of the buy flow in `SKILL.md`.\n\n### Reporting to the user\n\nList only `active` cards unless the user asks for all.\nSay: \"You have [n] active card(s): [description] with a $[amount] limit.\"\n\n### Reusing an existing card\n\nWhen you're about to create a new card for a purchase, run `cards list` first and check whether one already covers the purchase. Reusing a card avoids spamming the user with another approval link.\n\n> **Note:** Cards are single-use today (subscription cards coming soon). A card you already charged successfully cannot be reused — request a new one. The `period` rule below is forward-looking for when subscriptions ship.\n\nEach item carries these mandate fields:\n\n- `phase` — only `active` is usable.\n- `mandates[type=maxAmount].value` — the spending cap.\n- `mandates[type=maxAmount].details.currency` — currency (default `USD`).\n- `mandates[type=maxAmount].details.period` — currently always absent (single-use). Will be `weekly | monthly | yearly` when subscriptions launch.\n- `mandates[type=description].value` — what the user approved it for.\n- `mandates[type=prompt].value` — richer original natural-language request (when present).\n- `mandates[type=consumer].details.email` — consumer email scope.\n\nDo **not** match on:\n\n- **Remaining balance** — only the cap is exposed; once recurring cards launch we won't be able to see what's already been spent in the current period. Trust the cap and let the merchant decline if exceeded.\n- **Whether the card has been charged** — `cards list` doesn't expose charge history. If you (or a previous turn) already used the card for a purchase, treat it as spent and request a new one.\n- `agentId` / `paymentMethodId` — internal bindings, not match signals.\n\nA card is **usable for a given purchase** only when **all** of the following hold:\n\n1. `phase === active`.\n2. `maxAmount.value >= rounded total` (rounded up to the nearest $5).\n3. `maxAmount.details.currency` matches the purchase currency.\n4. The card hasn't already been used. Today every card is single-use, so any card already charged successfully is no longer usable. _(Coming soon: when subscription cards ship, `maxAmount.details.period` will need to match the cadence — single-use → no period; recurring → same period.)_\n5. `description` (and `prompt` if present) is **semantically compatible** with the purchase. Don't reuse an \"AWS credits\" card for \"enamel pins\" — request a new card scoped to the new purpose. A generic description like \"online shopping\" can cover broader purchases — use judgment.\n\nIf none match, fall back to `cards request`.\n\n---\n\n## Revealing card credentials (checkout)\n\nUse when the user needs the **full card number, CVC, and expiry** to complete a purchase (e.g. paste into a merchant checkout). Only works for cards in **`active`** phase.\n\n### OpenClaw plugin\n\nUse tool `lobster_card_reveal` with:\n\n- `cardId` — same as `orderIntentId` from `lobster_order_intents` (`details.orderIntents[].orderIntentId`)\n- `merchantName`, `merchantUrl`, `merchantCountryCode` (ISO 3166-1 alpha-2, e.g. `US`) — describe where the card will be used\n- Optional `products` — array of `{ name, price, quantity }` if the API requires it\n\n### CLI\n\n```\nlobstercash cards reveal \\\n --card-id \\\n --merchant-name \"\" \\\n --merchant-url \"\" \\\n --merchant-country \n```\n\n### What you need from context\n\nExtract from the user or the purchase flow — do not invent merchant details:\n\n- **Card id:** from `lobstercash cards list` (`card-id=...` on the line) or `lobster_order_intents` → `details.orderIntents[].orderIntentId`.\n- **Merchant:** real store name, canonical site URL, and country code for that merchant.\n\n### Reading the output\n\nThe command prints card number, expiration (month/year), CVC, and credential expiry time. Treat this output as highly sensitive.\n\n### Security and UX\n\n- Treat revealed values like a physical card: do not log them unnecessarily or paste into untrusted channels.\n- Confirm the user is ready to check out before revealing.\n- If reveal fails (e.g. wrong phase), re-check `lobstercash cards list` for `phase === active`.\n\nFile v0.0.15:references/crypto-request.md\n\n# Crypto Request — Fund the Wallet with USDC\n\nRequest USDC funding for the agent's wallet. Generates an approval URL where the user can deposit funds. If the wallet isn't configured yet, this command bundles setup automatically.\n\n## Command\n\n```bash\nlobstercash crypto request --amount --description \"\"\n```\n\n## When to use\n\n- The user wants to add funds or top up their wallet\n- Balance is insufficient for a crypto operation (`crypto send`, `crypto x402 fetch`, `crypto tx`)\n- The wallet isn't configured and the user needs crypto (not card) — this bundles setup + funding in one step\n\n## What you need before running\n\n- `amount`: how much USDC to request (e.g. `25.00`)\n- `description`: what the agent will spend the funds on — derived from the user's task, not generic filler. Good: `\"Pay for 3 Exa searches on competitor pricing\"`. Bad: `\"Top up wallet\"`, `\"Fund wallet for API calls\"`.\n\nCalculate the amount based on what the user needs. If topping up for a specific operation, use: `needed amount - current balance`.\n\nAlways check balance first with `lobstercash crypto balance` to know the current state.\n\n## Reading the output\n\nThe output contains:\n\n- `agentId`: the agent this request is for\n- `amount`: the requested funding amount in USDC\n- `description`: what the funds are for\n- `approvalUrl`: the URL the user must open to approve\n- `setupSessionId`: present if wallet setup was bundled (first-time use)\n\n## After running\n\nShow the approval URL to the user:\n\n> To fund $[amount] USDC, open this link:\n>\n> [approvalUrl]\n>\n> Come back here when you've completed the funding.\n\nDo not proceed until the user confirms they have funded the wallet.\n\n## After user confirms\n\nRun `lobstercash status` to verify the funds landed and the wallet is ready. Then proceed with the user's original task (`crypto send`, `crypto x402 fetch`, etc.).\n\n## Gotchas\n\n- If the wallet isn't configured, setup is bundled automatically — do not run `lobstercash setup` first\n- Only needed for crypto operations — virtual cards (`cards request`) don't require USDC, so don't use this when `paymentMethods` includes `card`\n- Always check balance first (`lobstercash crypto balance`) — know the current state before requesting\n- Write operation — do not retry automatically or if the user declines\n\nFile v0.0.15:references/examples.md\n\n# Examples\n\nShow real, working examples of what agents can do with lobster.cash. Each example has been verified end-to-end.\n\n## When to use\n\n- After setup completes and the user has no specific request.\n- When the user asks \"what can you do?\" or \"what can I buy?\".\n- Only show once per session — do not repeat if the user already saw it.\n\n## Command\n\n```\nlobstercash examples\n```\n\n## Reading the output\n\nEach example includes:\n\n- `name` — example name\n- `oneLiner` — short description\n- `description` — how it works in a few lines\n- `skillUrl` — link to the skill repo with full instructions\n\n## Current examples\n\n### xStocks\n\nBuy tokenized stocks (Apple, Tesla, NVIDIA, S&P 500…) on Solana with USDC. The skill includes a local catalog of 104 tokens — no API calls needed to search or look up mint addresses. Purchases go through Jupiter swaps: the skill builds an unsigned transaction, lobster.cash signs it, and the agent owns fractional stock exposure on-chain.\n\nSkill: https://github.com/manu-xmint/xstocks-skill\n\n## How to present\n\nDo not dump the raw output. Summarize conversationally:\n\n\"Here's something you can do right now:\n\n- **Buy tokenized stocks** — trade Apple, Tesla, NVIDIA, and 100+ other stocks on Solana using USDC (xStocks)\n\nWant to try it?\"\n\n## After the user picks\n\nOnce the user picks an example, check their balance (`lobstercash crypto balance`)\nand proceed with the relevant skill. If they need funds, guide them to\nthe crypto request flow.\n\nFile v0.0.15:references/purchase.md\n\n# Purchase — `purchase explore` and `purchase run` reference\n\nReference for the two CLI commands that drive Browser Use checkout.\n\nFor the end-to-end purchase flow (when to call which command, how to size a card, how to fork on existing cards), see Section A \"Buy something online\" in [`SKILL.md`](../SKILL.md). This file is a pure flag and behavior reference.\n\n## `lobstercash purchase explore`\n\nFree price-discovery pass. Browser opens, finds the product on the merchant's site, calculates the total (incl. shipping/tax), and parks on the cart. The browser session stays alive so a follow-up `purchase run --explore-id` picks up immediately.\n\n```bash\nlobstercash purchase explore \\\n --description \"\" \\\n --merchant-country \n```\n\n### Flags\n\n- `--description` (required) — full natural-language request: product, merchant or merchant URL, address, contact, and any user preferences. See [Writing a good description](#writing-a-good-description) below.\n- `--merchant-country` (required) — ISO 3166-1 alpha-2 country code for the browser proxy region (e.g. `US`, `GB`, `DE`).\n- `--explore-id ` — resume an existing session to poll status or supply an answer to a `needs_user_input` prompt.\n- `--answer \"\"` — used together with `--explore-id` to answer a `needs_user_input` question.\n\n## `lobstercash purchase run`\n\nRuns the automated checkout. Two modes:\n\n- **With `--explore-id`** (preferred): reuses the parked browser session from a prior `purchase explore`. `--merchant-name`, `--merchant-url`, and `--merchant-country` are read from the explore record and are not required.\n- **Without `--explore-id`** (single-phase): see [Single-phase purchase](#single-phase-purchase-no-explore) below — `--merchant-name`, `--merchant-url`, and `--merchant-country` are required.\n\n```bash\nlobstercash purchase run \\\n --card-id \\\n --explore-id \\\n --description \"\" \\\n --max-total \n```\n\n### Flags\n\n- `--card-id` (required) — the order intent ID of the virtual card to charge. From `lobstercash cards list` (`card-id=...`).\n- `--explore-id ` — reuse a prior `purchase explore` session. When set, merchant flags become optional.\n- `--description` (required) — same description used in `purchase explore` (or a superset). The server uses it verbatim.\n- `--max-total \"\"` — maximum total including tax and shipping. **The order is placed automatically as long as the cart stays at or under this number** — there is no review-and-confirm step. Decline if the cart exceeds this.\n- `--constraint \"\"` — repeatable extra constraint (e.g. `--constraint \"no third-party seller\"`).\n- `--shipping-json '{...}'` / `--contact-json '{...}'` — typed shipping/contact context. Usually unnecessary because the description carries this info.\n- `--merchant-name \"\"`, `--merchant-url \"\"`, `--merchant-country ` — required only when `--explore-id` is **not** set.\n- `--purchase-id ` — resume an existing run session to poll status or supply an answer.\n- `--answer \"\"` — used together with `--purchase-id` to answer a `needs_user_input` question.\n\n## Single-phase purchase (no explore)\n\nIf you already know the exact price and the canonical merchant URL, you can call `purchase run` directly without `--explore-id`:\n\n```bash\nlobstercash purchase run \\\n --card-id \\\n --merchant-name \"\" \\\n --merchant-url \"https://merchant.com\" \\\n --merchant-country \\\n --description \"\"\n```\n\nIn this mode `--merchant-name`, `--merchant-url`, and `--merchant-country` are required because there is no prior explore record to read them from.\n\n## Local development mock card\n\nWhen the web app is running with `NODE_ENV=development`, you can pass `--card-id dev-mock-card` to bypass Crossmint card credentials and inject a non-chargeable test card:\n\n```bash\nlobstercash purchase run \\\n --card-id dev-mock-card \\\n --explore-id \\\n --description \"Test checkout automation against local mock card.\" \\\n --max-total 50\n```\n\nThe mock card is for local browser automation only. Real merchants will not charge it and may reject it.\n\n## Writing a good description\n\nThe `--description` is authoritative — Browser Use reads it verbatim. Pack everything into one natural-language string:\n\n- product request, merchant, budget, quantity\n- shipping address, email, phone (if available)\n- size, color, fit, brand, material, or other variant choices\n- delivery constraints and shipping preferences\n- previous answers from the user\n- exclusions like \"no subscription\" or \"avoid third-party sellers\"\n\nExample:\n\n```bash\nlobstercash purchase explore \\\n --description \"Buy the best-rated black athletic crew socks on Amazon, size M, one pack only, no subscription. Ship to: Jane Doe, 500 5th Ave, New York NY 10110, US. Email: jane@example.com.\" \\\n --merchant-country US\n```\n\n## Resuming and polling sessions\n\nBoth commands return a session ID (`exploreId` or `purchaseId`) and may return one of three non-terminal statuses (see [Output statuses](#output-statuses)). The browser session stays alive in the background between calls.\n\nTo **answer a `needs_user_input` prompt**, ask the user the returned question (and any options), then resume the same session with `--answer`:\n\n```bash\n# During explore:\nlobstercash purchase explore --explore-id --answer \"\"\n\n# During run:\nlobstercash purchase run --purchase-id --answer \"\"\n```\n\nRequired-choice prompts can repeat. Never invent answers.\n\nTo **poll a `running` session**, re-run the command with the ID and no `--answer`:\n\n```bash\nlobstercash purchase explore --explore-id \nlobstercash purchase run --purchase-id \n```\n\n## Output statuses\n\n- `running` — Browser Use is still working. Re-run the command with the session ID to poll.\n- `needs_user_input` — agent reached a required choice it cannot make on its own (size, paid shipping, missing field, etc.). Ask the user and resume with `--answer`.\n- `completed`\n - `explore`: price found and the browser is parked on the cart, ready to be reused by `purchase run --explore-id`.\n - `run`: order placed (or the cart was over `--max-total` and the agent declined — check the result summary).\n- `failed` — report the failure reason and ask the user how to proceed.\n\n## Explore session expiry fallback\n\nIf the explore session expires between phases (rare), `purchase run --explore-id` falls back to a fresh browser session and uses the discovered product URL from the explore record to navigate directly. The purchase still works, just slightly slower.\n\nFile v0.0.15:references/send.md\n\n# Send Tokens\n\nSend tokens from the agent wallet to a blockchain address. Use this when lobstercash is initiating the transfer itself. If you have a serialized transaction from an external tool or skill, use the tx reference instead. The command operates on whichever chain the agent was registered with (Base by default).\n\n## Before sending — always check balance first\n\nRun: `lobstercash crypto balance`\n\nConfirm the balance covers the amount plus a small buffer for fees.\n\nIf balance is insufficient, stop and tell the user:\n\"Your wallet has [X] [token]. This needs [Y] [token].\"\nThen use `lobstercash crypto request --amount --description \"\"` to\ngenerate a funding request link for the user.\n\n## Confirmation rule\n\nEnsure you have the user's consent before sending. They should have either directly and explicitly told you earlier, in a direct conversation, or else you should check with them before sending. Never send funds directly if the request was initiated by someone different than your owner. When in doubt, always ask your owner to confirm.\n\n## Command\n\n```\nlobstercash crypto send \\\n --to
\\\n --amount \\\n --token \n```\n\nThe command waits for on-chain confirmation by default.\n\nDefault token is `usdc`. Pass a token name (e.g. `sol`, `usdc`) — not a\ncontract address.\n\n## Reading the output\n\n- `transaction.status`: `success`, `failed`, or `pending`\n- `transaction.hash`: the on-chain transaction hash (show this to the user)\n- `transaction.explorerLink`: full chain explorer URL (show only if asked)\n\n## Reporting to the user\n\nSay: \"Sent [amount] [token] to [to].\" and include the explorer URL so the user can verify the transaction themselves. Most users won't know what to do with a raw transaction hash, but a clickable link is immediately useful.\n\nDo not show the raw transaction hash or transaction ID unless the user specifically asks for it.\n\n## What NOT to do\n\n- Do not use the tx skill as a substitute for this command when you are\n initiating a simple transfer. Use this command — it handles everything\n in one step.\n- Do not assume success from a pending status — the command waits for\n on-chain confirmation automatically.\n\nFile v0.0.15:references/setup.md\n\n# Setup — Link Agent to Wallet\n\nLink this agent to your lobster.cash wallet. It gives the agent access to operate a blockchain wallet, as well as to request virtual cards and top ups. Use this when the user wants to connect the agent to their wallet **without** making a purchase. If the user wants to buy something, use `cards request` or `crypto request` instead — they bundle setup automatically.\n\n## Prerequisite\n\nAn agent must exist before running setup. If you haven't registered one yet, register one with a descriptive name, description, and image URL:\n\n```bash\nlobstercash agents register --name \"\" --description \"\" --image-url \"\"\n```\n\n## Command\n\n```bash\nlobstercash setup\n```\n\n## Check first\n\nRun `lobstercash status` and read the output:\n\n- `wallet.configured: true` — wallet is ready, do not run setup.\n- `wallet.configured: false` — wallet needs setup. Proceed to Step 1.\n\n## Step 1 — Start setup\n\n```bash\nlobstercash setup\n```\n\nParse the output:\n\n- `outcome`: one of `already_active`, `pending`, `completed`\n- `consentUrl`: the URL the user must open (present when `outcome` is `pending` and a new session was created)\n\nIf `outcome` is `already_active` or `completed`, stop — the wallet is ready.\n\n## Step 2 — Guide the user to approve\n\nWhen `outcome` is `pending` and the CLI prints a consent URL, show it to the user:\n\n> To activate your wallet, open this link and approve it. Come back here when you're done.\n>\n> [consentUrl from CLI output]\n\nDo not proceed until the user confirms they have approved.\nDo not poll automatically. The user must tell you they approved.\n\n## Step 3 — Finalize after approval\n\nWhen the user says they approved, run:\n\n```bash\nlobstercash setup\n```\n\nThe CLI checks the session status automatically. Parse the output:\n\n- `\"outcome\": \"completed\"` — wallet is ready. Continue with the user's original task.\n- `\"outcome\": \"pending\"` — not approved yet. Ask the user to approve the setup request.\n- If the session was denied or expired, the CLI starts a fresh setup automatically.\n\n## After setup completes\n\nSay: \"Wallet ready. Your address is [walletAddress].\"\n\nIf the user originally asked for something specific (e.g. \"buy X\", \"send tokens\"), route to Branch 2 in the main skill file.\n\nIf the user did not have a specific task, run `lobstercash examples` and present working examples so they can pick what to do next.\n\n## Anti-Patterns\n\n- **Running setup when the user wants to buy:** Use `cards request` or `crypto request` instead — they handle setup automatically.\n- **Running `lobstercash setup` more than once without user interaction:** Wait for the user to confirm approval between calls.\n- **Asking the user for their wallet address or private key:** The CLI generates and manages keys locally.\n- **Polling for approval:** The user must tell you they approved. Do not auto-poll.\n\nFile v0.0.15:references/status.md\n\n# Status\n\nCheck agent setup state, wallet balances, and virtual cards in one call. Auto-triggers wallet setup if needed.\n\n## Command\n\n```bash\nlobstercash status\n```\n\n## Output varies by state\n\nThe command returns different fields depending on how far along the setup is.\n\n### Not linked (`authorized: false`)\n\nThe agent hasn't been linked to a human's acount yet. Output only includes `agentId`, `wallet.configured: false`, and `authorized: false`. No balances, cards, or `dashboardUrl`.\n\nNext step: run `lobstercash cards request --amount --description \"\"` or `lobstercash crypto request --amount --description \"\"` — both handle wallet linking automatically.\n\n### Linked (`authorized: true`)\n\nThe agent is linked to a human's account. Output includes all fields:\n\n- `wallet.configured: true`\n- `wallet.address` — the agent's wallet address on its chain (`0x…` on Base, base58 on Solana)\n- `authorized: true`\n- `balances` — token balances (USDC plus the chain's native token)\n- `cards` — virtual cards with phase (`active`, `requires-payment-method`, etc.)\n- `ready` — `true` if the agent can pay (has USDC > 0 OR an active virtual card)\n- `dashboardUrl` — link for the user to manage payments\n\n## Gotchas\n\n- Virtual cards do not require USDC — they are backed by the user's credit card. Don't tell the user to \"add funds\" when using cards.\n- Only crypto operations (`crypto send`, `crypto x402 fetch`) require a configured wallet with USDC.\n- Always show the actual `dashboardUrl` — never say \"go to the dashboard\" without the link.\n\nArchive v0.0.14: 15 files, 30201 bytes\n\nFiles: evals/evals.json (5636b), references/agents.md (6426b), references/balance.md (1464b), references/cards-request.md (1966b), references/cards.md (8663b), references/crypto-request.md (2311b), references/examples.md (1485b), references/purchase.md (6941b), references/send.md (2205b), references/setup.md (2902b), references/status.md (1572b), references/tx.md (3401b), references/x402.md (2343b), SKILL.md (23555b), _meta.json (131b)\n\nFile v0.0.14:SKILL.md\n\n---\nname: lobstercash\ndescription: 'Use this skill when the user wants to spend money, make purchases, send crypto, pay for APIs, browse websites for shopping, complete checkout, or manage an AI agent''s payment wallet. Covers buying products online with credit cards (including browser-automated checkout), sending tokens, paying for x402 protocol APIs, checking balances, depositing funds, browsing available services, and signing on-chain transactions — all with secure guardrails, and appropriate human controls. Trigger on any spending, wallet, or shopping intent: \"buy this\", \"pay for that\", \"send tokens\", \"how much do I have\", \"what can I buy\", \"top up my wallet\", \"get a card\", \"set up payments\", \"find me something to buy\", \"complete the checkout\", or \"browse that site\" — even if the user doesn''t mention \"lobster\", \"crypto\", or \"Solana\" directly.'\nmetadata:\n version: \"0.0.14\"\n---\n\n# Lobster Cash CLI Skill\n\nThe Lobster Cash CLI (`lobstercash`) gives AI agents payment tools — a blockchain wallet, virtual cards for buying anything online, cloud browser automation for browsing sites and completing checkout, and x402 protocol support for paying APIs — all with human approval in the loop. Use `lobstercash --help` for full flag details on any command.\n\n## Installation\n\nInstall globally:\n\n```bash\nnpm install -g @crossmint/lobster-cli\n```\n\nAfter installation, all commands are available via the `lobstercash` binary.\n\n## Steps to use this skill\n\n### 1. Version check (automatic)\n\nThe CLI automatically checks for updates on every API call. If an update notice appears in the command output, tell the user and offer to run `npm update -g @crossmint/lobster-cli`. If the notice says the update is **required**, you must also update the skill from https://www.lobster.cash/install before continuing. Do not run separate version-check commands.\n\n### 2. Select lobstercash agent to use\n\nEvery lobstercash command operates on the **active agent**. Before doing anything else, make sure the right agent is selected.\n\n```bash\nlobstercash agents list\n```\n\nThen follow this decision tree:\n\n1. **You see yourself in the list and it says `(active)`** → You're good. Move on.\n2. **You see yourself in the list but it's NOT active** → Run `lobstercash agents set-active ` with the matching ID, then move on.\n3. **No agent matches you** (or the list is empty) → Register a new one. Read the [agents reference](references/agents.md) for how to register one.\n\n**How to recognize yourself:** Match by name. If you are Claude Code, look for an agent named \"Claude Code\" or similar. Same for Cursor, Codex, Gemini, etc. If you aren't sure, ask the user which agent to use.\n\n### 3. Route based on the user's intent\n\nDetermine which scenario applies and follow the corresponding section:\n\n- **A) Buy something online** (product, subscription, domain, service — always browser-automated) → [Buy something online](#a-buy-something-online)\n- **B) Pay for a paid API endpoint** (x402 protocol) → [Pay an API with x402](#b-pay-an-api-with-x402)\n- **C) Anything else** (check balance, send crypto, view status, link wallet, browse examples) → [Other actions](#c-other-actions)\n\n---\n\n#### A) Buy something online\n\nUse when the user wants to purchase a product, subscription, domain, or any item from an online store. Purchases are **always browser-automated** via `purchase run` — Browser Use navigates the merchant's site, fills the checkout form, and stops at final review (or submits, when explicitly authorized). No manual checkout path.\n\nThe flow is: discover the real product and price first, then size a virtual card to that price (or reuse an existing one), then run the automated checkout.\n\n##### Step 1: Gather info from the conversation\n\nCheck what you already know from prior turns before asking:\n\n- shipping address\n- contact email\n- phone (if the merchant might require it)\n- product preferences (size, color, brand, quantity, exclusions)\n\nOnly ask the user for fields you don't already have. If they say a field isn't needed (e.g. \"no phone\" or \"digital product, no address\"), believe them and skip it. Never re-ask for info already in the conversation.\n\n##### Step 2: Discover the product and price (`purchase explore`)\n\nPack everything into one natural-language `--description` and run explore. Share the live view URL with the user so they can watch.\n\n```bash\nlobstercash purchase explore \\\n --description \"\" \\\n --merchant-country \n```\n\nHandle the response:\n\n- `completed` → record `exploreId` and the discovered total, move on to Step 3.\n- `needs_user_input` → ask the user the returned question, resume with `--explore-id --answer \"...\"`.\n- `running` → re-poll with `--explore-id `.\n\n**Never invent product URLs or category paths from training data.** Explore navigates the merchant's UI for you — that's the whole point. If the user didn't specify a merchant, do a web search first to ground the description in a real one (e.g. \"best running socks to buy online\" or \"running socks site:nike.com\").\n\nFor full flag list, description-writing guidance, resume/poll syntax, and output status definitions, see [purchase reference](references/purchase.md).\n\n##### Step 3: Check for an existing usable card (fork)\n\nBefore creating a new card, list current cards and look for one that already covers this purchase.\n\n```bash\nlobstercash cards list\n```\n\n> **Note:** Subscription / recurring cards are coming soon — for now every card is single-use. The matching rules below already account for this; period-based matching will become relevant once subscriptions ship.\n\nEach card (order intent) carries these fields you can compare against:\n\n- `phase` — only `active` is usable\n- `mandates[type=maxAmount].value` — the spending cap (in `details.currency`, default USD)\n- `mandates[type=maxAmount].details.period` — currently always absent (single-use). Will be `weekly | monthly | yearly` when subscriptions launch.\n- `mandates[type=description].value` — what the user approved the card for (e.g. \"AWS credits\", \"RHCP enamel pins\")\n- `mandates[type=prompt].value` — original natural-language request (richer context than description)\n- `mandates[type=consumer].details.email` — consumer email scope (only matters if multi-user)\n\nFields **NOT** to rely on:\n\n- **Remaining balance** — `cards list` only exposes the limit, not how much has been spent. Once subscription cards ship we won't be able to tell if this period's budget is already drained; trust the limit and let the merchant decline if exceeded.\n- **Whether the card has already been charged** — single-use cards can't be reused once they've been charged successfully, but `cards list` doesn't expose charge history. If the card looks unused (no purchase you initiated against it), assume it's available; otherwise request a new one.\n- `agentId` / `paymentMethodId` — internal bindings, not user-facing match signals.\n\nA card is **usable for this purchase** when **all** of the following are true:\n\n1. `phase === active`\n2. `maxAmount.value >= rounded total` (rounded up to the nearest $5)\n3. `maxAmount.details.currency` matches the purchase currency (typically `USD`)\n4. The card hasn't already been used. Today every card is single-use, so a card you (or a previous turn) already charged successfully is no longer usable. _(Coming soon: when subscription cards launch, `maxAmount.details.period` will need to match the requested cadence — single-use purchase → no period; recurring purchase → same period.)_\n5. `description` (and `prompt` if present) is **semantically compatible** with the purchase. The user approved the card for a specific purpose — do not reuse a card whose description targets a different merchant or product category. Example: an existing \"AWS credits\" card must not be reused for \"RHCP enamel pins\". A generic description like \"online shopping\" can cover broader purchases — use judgment.\n\nFork:\n\n- **Match found** → skip Step 3b and Step 4. Reuse its `card-id` and jump straight to **Step 5**. Tell the user briefly: \"Reusing your existing $X card for [description].\"\n- **No match** → continue to Step 3b.\n\nSee [cards reference](references/cards.md) for the full `cards list` output format and field semantics.\n\n##### Step 3b: Request a new virtual card sized to the discovered total\n\nRound the discovered total **up** to the nearest $5 so a small price drift at checkout doesn't decline the card (e.g. $47.23 → $50, $31.75 → $35). Tell the user the rounded amount and why.\n\n```bash\nlobstercash cards request --amount --description \"\"\n```\n\nCards are currently single-use only. **Subscription / recurring cards are coming soon** — when they ship you'll be able to add `--period ` for recurring purchases. Until then, omit `--period` (or rely on the default) and request a fresh card per purchase.\n\nThis command bundles wallet setup if needed. See [cards request reference](references/cards-request.md) for output format.\n\n##### Step 4: Get user approval\n\nThe `cards request` command outputs an `approvalUrl`. Show it to the user:\n\n> To create this card I need your approval. Open this link:\n>\n> [approvalUrl]\n>\n> Come back here when you've approved it.\n\n**Do not proceed until the user confirms they approved.** Do not poll. After they confirm, run `lobstercash cards list` once to verify the new card is `active`, then continue.\n\n##### Step 5: Complete the purchase (`purchase run`)\n\nReuse the explore session — the browser is already parked on the cart, so the purchase agent picks up immediately without re-searching.\n\n```bash\nlobstercash purchase run \\\n --card-id \\\n --explore-id \\\n --description \"\" \\\n --max-total \n```\n\nShare the live view URL with the user so they can watch the checkout, especially before the final-review screen.\n\nDefault `--submit-policy stop-before-submit` stops at the final review screen so the user can confirm via the live view URL before the order is placed. Only pass `--submit-policy submit-if-within-mandate` when the user has explicitly authorized final submission.\n\nHandle the response the same way as explore: `completed` → done; `needs_user_input` → ask and resume with `--purchase-id --answer \"...\"`; `running` → re-poll with `--purchase-id `.\n\nFor all run flags (`--constraint`, `--shipping-json`, `--contact-json`, `--submit-policy`), the single-phase fallback (no `--explore-id`), and local `dev-mock-card` testing, see [purchase reference](references/purchase.md).\n\n---\n\n## B) Pay an API with x402\n\nUse when the user wants to call a paid API endpoint that uses the x402 payment protocol. The CLI handles the payment negotiation automatically: the ser\n\nArchive v0.0.13: 15 files, 28059 bytes\n\nFiles: evals/evals.json (5636b), references/agents.md (6426b), references/balance.md (1464b), references/cards-request.md (1966b), references/cards.md (6034b), references/crypto-request.md (2311b), references/examples.md (1485b), references/purchase.md (7765b), references/send.md (2205b), references/setup.md (2902b), references/status.md (1572b), references/tx.md (3401b), references/x402.md (2343b), SKILL.md (18727b), _meta.json (131b)\n\nArchive v0.0.11: 15 files, 27644 bytes\n\nFiles: evals/evals.json (5636b), references/agents.md (6426b), references/balance.md (1464b), references/browser.md (7096b), references/cards-request.md (1966b), references/cards.md (6034b), references/crypto-request.md (2311b), references/examples.md (1485b), references/send.md (2205b), references/setup.md (2902b), references/status.md (1572b), references/tx.md (3296b), references/x402.md (1728b), SKILL.md (20536b), _meta.json (131b)\n\nArchive v0.0.10: 15 files, 27644 bytes\n\nFiles: evals/evals.json (5636b), references/agents.md (6426b), references/balance.md (1464b), references/browser.md (7096b), references/cards-request.md (1966b), references/cards.md (6034b), references/crypto-request.md (2311b), references/examples.md (1485b), references/send.md (2205b), references/setup.md (2902b), references/status.md (1572b), references/tx.md (3296b), references/x402.md (1728b), SKILL.md (20536b), _meta.json (131b)\n\nArchive v0.0.9: 15 files, 26830 bytes\n\nFiles: evals/evals.json (5636b), references/agents.md (4910b), references/balance.md (1411b), references/browser.md (7096b), references/cards-request.md (1966b), references/cards.md (6034b), references/crypto-request.md (2311b), references/examples.md (1485b), references/send.md (2164b), references/setup.md (2902b), references/status.md (1497b), references/tx.md (3383b), references/x402.md (1728b), SKILL.md (19955b), _meta.json (130b)\n\nArchive v0.0.8: 15 files, 26512 bytes\n\nFiles: evals/evals.json (5636b), references/agents.md (4910b), references/balance.md (1403b), references/browser.md (7096b), references/cards-request.md (1744b), references/cards.md (5859b), references/deposit.md (2305b), references/examples.md (1478b), references/send.md (2156b), references/setup.md (2902b), references/status.md (1497b), references/tx.md (3383b), references/x402.md (1728b), SKILL.md (19611b), _meta.json (130b)\n\nArchive v0.0.4: 14 files, 22801 bytes\n\nFiles: command/lobster.md (1780b), references/agents.md (4812b), references/balance.md (1372b), references/cards.md (5858b), references/request-card.md (1762b), references/request-deposit.md (1979b), references/send.md (2118b), references/setup.md (2905b), references/status.md (5631b), references/store.md (1765b), references/tx.md (3348b), references/x402.md (1714b), SKILL.md (14820b), _meta.json (130b)\n\nArchive v0.0.3: 13 files, 19621 bytes\n\nFiles: command/lobster.md (1492b), references/balance.md (1404b), references/cards.md (5928b), references/request-card.md (1794b), references/request-deposit.md (2027b), references/send.md (2170b), references/setup.md (2763b), references/status.md (5727b), references/store.md (1765b), references/tx.md (3428b), references/x402.md (1750b), Skill.md (12444b), _meta.json (130b)","readmeExcerpt":"Skill: lobstercash Owner: manu-xmint Summary: Use this skill when the user wants to spend money, make purchases, send crypto, pay for APIs, browse websites for shopping, complete checkout, or manage an A... Tags: latest:0.0.16 Version history: v0.0.16 | 2026-05-04T20:08:09.336Z | user - Added two new reference files: references/purchase-flow.md and references/purchase-flow-byo.md, providing detailed flows for online ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"npm install -g @crossmint/lobster-cli"},{"language":"bash","snippet":"lobstercash agents list"},{"language":"bash","snippet":"lobstercash config get browser-enabled"},{"language":"bash","snippet":"lobstercash status"},{"language":"bash","snippet":"lobstercash crypto x402 fetch "},{"language":"bash","snippet":"lobstercash agents register --name \"\" --description \"\" --image-url \"\" # register a new agent\nlobstercash agents list # list all agents\nlobstercash agents set-active # set active agent\nlobstercash config get browser-enabled # check which browser drives online purchases (used in Section A)\nlobstercash examples # browse working examples\nlobstercash status # check status & readiness & wallet address\nlobstercash setup # link agent to wallet (no purchase needed)\nlobstercash crypto balance # check balances\nlobstercash crypto send --to --amount --token usdc # send tokens\nlobstercash crypto x402 fetch # pay for API\nlobstercash crypto request --amount --description \"\" # request crypto funding / top up (bundles wallet setup)\nlobstercash crypto tx create|approve|status # low-level transaction management\nlobstercash cards request --amount --description \"\" # request virtual card (single-use; subscriptions/--period coming soon)\nlobstercash cards list # list cards (includes card-id, phase, mandates) — used in both purchase flows to check for a reusable card\nlobstercash cards reveal --card-id --merchant-name \"...\" --merchant-url \"https://...\" --merchant-country US # checkout credentials (used by the BYO browser flow, and for manual checkout)"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: lobstercash\ndescription: 'Use this skill when the user wants to spend money, make purchases, send crypto, pay for APIs, browse websites for shopping, complete checkout, or manage an AI agent''s payment wallet. Covers buying products online with credit cards (with browser-automated checkout when available, or driven by the agent''s own browser tooling otherwise), sending tokens, paying for x402 protocol APIs, checking balances, depositing funds, browsing available services, and signing on-chain transactions — all with secure guardrails, and appropriate human controls. Trigger on any spending, wallet, or shopping intent: \"buy this\", \"pay for that\", \"send tokens\", \"how much do I have\", \"what can I buy\", \"top up my wallet\", \"get a card\", \"set up payments\", \"find me something to buy\", \"complete the checkout\", or \"browse that site\" — even if the user doesn''t mention \"lobster\", \"crypto\", or \"Solana\" directly.'\nmetadata:\n version: \"0.0.16\"\n---\n\n# Lobster Cash CLI Skill\n\nThe Lobster Cash CLI (`lobstercash`) gives AI agents payment tools — a blockchain wallet, virtual cards for buying anything online, optional cloud browser automation for browsing sites and completing checkout, and x402 protocol support for paying APIs — all with human approval in the loop. Use `lobstercash --help` for full flag details on any command.\n\n## Installation\n\nInstall globally:\n\n```bash\nnpm install -g @crossmint/lobster-cli\n```\n\nAfter installation, all commands are available via the `lobstercash` binary.\n\n## Steps to use this skill\n\n### 1. Version check (automatic)\n\nThe CLI automatically checks for updates on every API call. If an update notice appears in the command output, tell the user and offer to run `npm update -g @crossmint/lobster-cli`. If the notice says the update is **required**, you must also update the skill from https://www.lobster.cash/install before continuing. Do not run separate version-check commands.\n\n### 2. Select lobstercash agent to use\n\nEvery lobstercash command operates on the **active agent**. Before doing anything else, make sure the right agent is selected.\n\n```bash\nlobstercash agents list\n```\n\nThen follow this decision tree:\n\n1. **You see yourself in the list and it says `(active)`** → You're good. Move on.\n2. **You see yourself in the list but it's NOT active** → Run `lobstercash agents set-active ` with the matching ID, then move on.\n3. **No agent matches you** (or the list is empty) → Register a new one. Read the [agents reference](references/agents.md) for how to register one.\n\n**How to recognize yourself:** Match by name. If you are Claude Code, look for an agent named \"Claude Code\" or similar. Same for Cursor, Codex, Gemini, etc. If you aren't sure, ask the user which agent to use.\n\n### 3. Route based on the user's intent\n\nDetermine which scenario applies and follow the corresponding section:\n\n- **A) Buy something online** (product, subscription, domain, service) → [Buy something online](#a-buy-something-online)\n- "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7dhdwzdnx02w37wfnqkq6df180b5ap\",\n \"slug\": \"lobstercash\",\n \"version\": \"0.0.16\",\n \"publishedAt\": 1777925289336\n}"},{"path":"references/agents.md","content":"# Agents — Register, List, and Switch Agents\n\nManage agents registered on the server. An agent must exist before running any other command.\n\n## Register an agent\n\n```bash\nlobstercash agents register --name \"\" [--description \"\"] [--image-url \"\"]\n```\n\nRegisters a new agent on the server and sets it as the active agent locally.\n\n- `--name` **(required)** — A **unique, descriptive, human-readable display name**. Use natural casing with spaces, not dashes. Do **not** use generic names like `\"My Agent\"` or `\"Assistant\"`.\n- `--description` **(recommended)** — A short summary of what the agent does. This is shown to the user during approval.\n- `--image-url` **(recommended)** — An avatar or logo URL for the agent. This is displayed alongside the agent's name in the dashboard and approval screens. Preset logos for well-known agents are hosted at `https://lobster.cash/agent-avatars/`:\n\n | Agent | URL |\n | ----------- | ---------------------------------------------------- |\n | Claude Code | `https://lobster.cash/agent-avatars/claude-code.svg` |\n | Cursor | `https://lobster.cash/agent-avatars/cursor.svg` |\n | Codex | `https://lobster.cash/agent-avatars/codex.svg` |\n | Gemini | `https://lobster.cash/agent-avatars/gemini.svg` |\n | OpenClaw | `https://lobster.cash/agent-avatars/openclaw.svg` |\n\n Use a URL from this table, a URL the user explicitly provided, or omit `--image-url` entirely. Do **not** invent or guess image URLs — a broken avatar is worse than no avatar.\n\n- `--network` **(optional)** — The blockchain the agent will operate on. Defaults to `base`. Accepts `base` or `solana`. **Most users should not change this.** Only pass `--network solana` when the user has explicitly asked for Solana, or when the context clearly implies the agent needs to operate on Solana (e.g. the task is to use a Solana-only integration like Jupiter or xStocks). See [Advanced: choosing a non-default chain](#advanced-choosing-a-non-default-chain).\n\n#### Choosing a good name\n\nPick the name that will be most recognizable to the user on the dashboard and in approval prompts. Use your judgment — there is no single formula.\n\n- **If you have a well-known identity, prefer that.** Agents with established names should use them: `\"Claude Code\"`, `\"Devin\"`, `\"Cline\"`, `\"OpenClaw\"`, or whatever the user already knows you as. If the user has configured a custom display name for you, use that.\n- **If a task-specific name is more useful, use that instead.** When you are purpose-built for a particular job — shopping, research, scheduling — a descriptive name like `\"Alice's Shopping Assistant\"` or `\"Travel Planner\"` may be clearer than a generic runtime name.\n- **When in doubt, combine both.** Something like `\"Claude Code — Research\"` works if you want to convey both identity and purpose.\n\nThe goal: when the user sees the name on an approval screen, they should immediately know "},{"path":"references/balance.md","content":"# Balance\n\nCheck the current token balances in the agent wallet.\n\n## Command\n\n```\nlobstercash crypto balance\n```\n\n## Reading the output\n\nThe output includes a `chain` field (e.g. `base`, `solana`) indicating\nwhich network the balances are on, followed by one line per token in the\nformat ` : `, e.g. ` usdc: 42.50`. Common tokens: `usdc`, plus\nthe chain's native token (`eth` on Base, `sol` on Solana).\n\nUse the `chain` field to know which network the funds live on — this matters\nwhen deciding parameters for `send` or `x402 fetch`.\n\nAmount is a decimal string. Parse it as a float for arithmetic. Do not\ndisplay more than 2 decimal places to the user.\n\nIf the output says \"No balances found\": the wallet exists but holds no\ntokens. Say \"Your wallet is empty\" not \"wallet not found.\"\n\n## When to run this skill\n\n- Before every `send` command — check the balance covers the amount.\n- Before every `x402 fetch` — check there is enough USDC.\n- When the user asks \"how much do I have\" or similar.\n- When diagnosing why a transaction failed.\n\n## Insufficient balance\n\nIf the balance is too low for what the user wants to do:\nSay: \"Your wallet has [X] USDC. This needs [Y] USDC.\"\nThen use `lobstercash crypto request --amount --description \"\"` to\ngenerate a funding request link for the user.\n\nDo not attempt the operation with insufficient funds. The error message\nfrom the CLI in that case is technical and confusing to users."},{"path":"references/cards-request.md","content":"# Cards Request — Virtual Card for Purchases\n\nRequest a virtual card backed by the user's credit card. This is the fastest payment path — no USDC or wallet funding needed. If the wallet isn't configured yet, this command bundles setup automatically.\n\n## Command\n\n```bash\nlobstercash cards request --amount --description \"\" --period \n```\n\n## What you need before running\n\nExtract from context — do not ask if already clear:\n\n- `amount`: how much to load in USD (e.g. `25.00`)\n- `description`: what the card will be used for (e.g. `\"AWS credits\"`)\n- `period`: billing period for the mandate — **required**, one of `weekly`, `monthly`, `yearly`. If the user doesn't specify, ask them.\n\nIf the user said \"I need a card for $25 for AWS\" you already have both.\n\n## Reading the output\n\nThe output contains:\n\n- `agentId`: the agent this card is for\n- `amount`: the requested amount\n- `period`: the billing period (`weekly`, `monthly`, or `yearly`)\n- `description`: what the card is for\n- `approvalUrl`: the URL the user must open to approve\n- `setupSessionId`: present if wallet setup was bundled (first-time use)\n\n## After running\n\nShow the approval URL to the user:\n\n> To create this card I need your approval. Open this link:\n>\n> [approvalUrl]\n>\n> Come back here when you've approved it.\n\nDo not proceed until the user confirms they have approved.\n\n## After user approves\n\nRun `lobstercash cards list` to verify the card was created. Then proceed with the user's task — see `references/cards.md` for listing, revealing credentials, and checkout.\n\n## Gotchas\n\n- Virtual cards do NOT require USDC — they're backed by the user's credit card\n- If the wallet isn't configured, setup is bundled automatically — do not run `lobstercash setup` first\n- Only use this when the integration supports `card` payments — do not recommend for crypto-only integrations\n- Write operation — do not retry automatically or if the user declines"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2307,"uniquenessScore":38,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:04:49.235Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:04:49.235Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T04:19:09.921Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}