Lobster Cash CLI Skill

The 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 \x3Ccommand> --help for full flag details on any command.

Installation

Install globally:

npm install -g @crossmint/lobster-cli

After installation, all commands are available via the lobstercash binary.

Steps to use this skill

1. Version check (automatic)

The 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.

2. Select lobstercash agent to use

Every lobstercash command operates on the active agent. Before doing anything else, make sure the right agent is selected.

lobstercash agents list

Then follow this decision tree:

1. You see yourself in the list and it says (active) → You're good. Move on.
2. You see yourself in the list but it's NOT active → Run lobstercash agents set-active \x3CagentId> with the matching ID, then move on.
3. No agent matches you (or the list is empty) → Register a new one. Read the agents reference for how to register one.

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.

3. Route based on the user's intent

Determine which scenario applies and follow the corresponding section:

• A) Buy something online (product, subscription, domain, service — always browser-automated) → Buy something online
• B) Pay for a paid API endpoint (x402 protocol) → Pay an API with x402
• C) Anything else (check balance, send crypto, view status, link wallet, browse examples) → Other actions

A) Buy something online

Use 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.

The 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.

Step 1: Gather info from the conversation

Check what you already know from prior turns before asking:

• shipping address
• contact email
• phone (if the merchant might require it)
• product preferences (size, color, brand, quantity, exclusions)

Only 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.

Step 2: Discover the product and price (purchase explore)

Pack everything into one natural-language --description and run explore. Share the live view URL with the user so they can watch.

lobstercash purchase explore \
  --description "\x3Cproduct, merchant or URL, shipping address, email, preferences>" \
  --merchant-country \x3CXX>

Handle the response:

• completed → record exploreId and the discovered total, move on to Step 3.
• needs_user_input → ask the user the returned question, resume with --explore-id \x3Cid> --answer "...".
• running → re-poll with --explore-id \x3Cid>.

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").

For full flag list, description-writing guidance, resume/poll syntax, and output status definitions, see purchase reference.

Step 3: Check for an existing usable card (fork)

Before creating a new card, list current cards and look for one that already covers this purchase.

lobstercash cards list

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.

Each card (order intent) carries these fields you can compare against:

• phase — only active is usable
• mandates[type=maxAmount].value — the spending cap (in details.currency, default USD)
• mandates[type=maxAmount].details.period — currently always absent (single-use). Will be weekly | monthly | yearly when subscriptions launch.
• mandates[type=description].value — what the user approved the card for (e.g. "AWS credits", "RHCP enamel pins")
• mandates[type=prompt].value — original natural-language request (richer context than description)
• mandates[type=consumer].details.email — consumer email scope (only matters if multi-user)

Fields NOT to rely on:

• 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.
• 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.
• agentId / paymentMethodId — internal bindings, not user-facing match signals.

A card is usable for this purchase when all of the following are true:

1. phase === active
2. maxAmount.value >= rounded total (rounded up to the nearest $5)
3. maxAmount.details.currency matches the purchase currency (typically USD)
4. 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.)
5. 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.

Fork:

• 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]."
• No match → continue to Step 3b.

See cards reference for the full cards list output format and field semantics.

Step 3b: Request a new virtual card sized to the discovered total

Round 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.

lobstercash cards request --amount \x3Crounded> --description "\x3Cshort product name>"

Cards are currently single-use only. Subscription / recurring cards are coming soon — when they ship you'll be able to add --period \x3Cweekly|monthly|yearly> for recurring purchases. Until then, omit --period (or rely on the default) and request a fresh card per purchase.

This command bundles wallet setup if needed. See cards request reference for output format.

Step 4: Get user approval

The cards request command outputs an approvalUrl. Show it to the user:

To create this card I need your approval. Open this link:

[approvalUrl]

Come back here when you've approved it.

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.

Step 5: Complete the purchase (purchase run)

Reuse the explore session — the browser is already parked on the cart, so the purchase agent picks up immediately without re-searching.

lobstercash purchase run \
  --card-id \x3Ccard-id> \
  --explore-id \x3Cexplore-id> \
  --description "\x3Csame description as explore>" \
  --max-total \x3Crounded>

Share the live view URL with the user so they can watch the checkout, especially before the final-review screen.

Default --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.

Handle the response the same way as explore: completed → done; needs_user_input → ask and resume with --purchase-id \x3Cid> --answer "..."; running → re-poll with --purchase-id \x3Cid>.

For 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.

B) Pay an API with x402

Use 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.

Step 1: Ensure the wallet has funds

lobstercash status

Route based on the result:

• Wallet configured + has enough funds → proceed to step 2.
• Wallet configured + insufficient funds → run lobstercash crypto request --amount \x3Cneeded> --description "\x3Cdescription>" to top up, show the approval URL, wait for user confirmation, then proceed.
• Wallet not configured → run lobstercash crypto request --amount \x3Cneeded> --description "\x3Cdescription>" (bundles wallet creation + funding). Show the approval URL, wait for user confirmation, verify with lobstercash status, then proceed.

The --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".

See crypto request reference for the full crypto request flow.

Step 2: Fetch the paid endpoint

lobstercash crypto x402 fetch \x3Curl>

For POST requests add --json '{"key": "value"}'. For custom headers add --header "Authorization: Bearer \x3Ctoken>".

Step 3: Report the result

Report what the API returned (the body field), not the payment mechanics. Only mention the payment if the user asks.

If the fetch fails, add --debug and run again. See x402 reference for output format and common failures.

C) Other actions

For 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.

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.

Common actions:

• Check balance: lobstercash crypto balance → balance reference
• Send tokens: lobstercash crypto send --to \x3Caddr> --amount \x3Cn> --token usdc → send reference
• View wallet status: lobstercash status → status reference
• Browse examples: lobstercash examples → examples reference
• Link wallet / configure agent (setup only): lobstercash setup → setup reference. Use when the user says "configure", "set up", "link wallet", or similar — and isn't trying to make a purchase.
• Sign/submit a transaction: lobstercash crypto tx create → tx reference

For 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 \x3Cneeded> --description "\x3Cdescription>" to fund it — see crypto request reference.

Quick Reference

lobstercash agents register --name "\x3Cname>" --description "\x3Cdesc>" --image-url "\x3Curl>"  # register a new agent
lobstercash agents list                                          # list all agents
lobstercash agents set-active \x3CagentId>                          # set active agent
lobstercash examples                                             # browse working examples
lobstercash status                                               # check status & readiness & wallet address
lobstercash setup                                                # link agent to wallet (no purchase needed)
lobstercash crypto balance                                       # check balances
lobstercash crypto send --to \x3Caddr> --amount \x3Cn> --token usdc    # send tokens
lobstercash crypto x402 fetch \x3Curl>                              # pay for API
lobstercash crypto request --amount \x3Cn> --description "\x3Cdesc>"    # request crypto funding / top up (bundles wallet setup)
lobstercash crypto tx create|approve|status                      # low-level transaction management
lobstercash cards request --amount \x3Cn> --description "\x3Cdesc>"     # request virtual card (single-use; subscriptions/--period coming soon)
lobstercash cards list                                           # list cards (includes card-id, phase, mandates) — used in Step 3 of the buy flow to check for a reusable card
lobstercash purchase explore --description "\x3C...>" --merchant-country \x3CXX>                        # discover product + price (Step 2 of buy flow)
lobstercash purchase run --card-id \x3Cid> --explore-id \x3Cid> --description "\x3C...>" --max-total \x3Cn>   # automated browser checkout (Step 5 of buy flow)
lobstercash cards reveal --card-id \x3Cid> --merchant-name "..." --merchant-url "https://..." --merchant-country US  # checkout credentials (manual sites only — not part of the standard buy flow)

Output Contract

• All commands produce human-readable output to stdout.
• Errors go to stderr as plain text.
• Exit 0 = success. Exit 1 = unexpected error. Exit 2 = wallet not set up (use cards request or crypto request to set up).

Decision Tree

• Read examples if the user wants to browse working examples, or has no specific task yet
• Read status if the user asks about agent status or payment readiness
• Read balance if the user wants to check token balances
• Read purchase if the user wants to buy something online — full flag reference, single-phase fallback, dev-mock-card, description-writing tips, and resume/poll syntax
• Read cards request if the user wants to create a new virtual card for a purchase (Step 3b of the buy flow)
• Read crypto request if the user wants to request USDC, top up their wallet, or fund a crypto operation
• Read cards if the user needs to list existing cards or check whether one can be reused for a purchase (Step 3 of the buy flow)
• Read send if the user wants to send tokens to an address (Crypto Path)
• Read x402 if the user wants to pay for an API via x402 protocol (Crypto Path)
• Read tx if the user needs to sign or submit a transaction from an external tool (Crypto Path)
• Read setup if the user wants to link the agent to a wallet without making a purchase
• Read agents if the user wants to register, list, or set the active agent

Anti-Patterns

• 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.
• 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.
• 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.
• Asking the user for info the CLI can fetch: Check balance before sending. Check status before acting. Read command output before asking questions.
• 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.
• Ignoring terminal status: A pending transaction is not a success. All write commands now wait for on-chain confirmation by default.
• Polling for HITL approval: When a command returns an approval URL, the user must tell you they approved. Do not auto-poll.
• 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.
• 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.
• Recommending cards for crypto-only integrations: If the integration only uses crypto, don't suggest a virtual card.
• 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.
• Treating x402/send/tx as separate user flows: They all go through the same Crypto Path. The only split is credit card vs crypto.
• 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.
• 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.
• 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.
• 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.
• Placing orders without user confirmation: Don't pass --submit-policy submit-if-within-mandate to purchase run unless the user has explicitly authorized final submission. The default stop-before-submit is correct: it stops at the final review screen so the user can confirm via the live view URL before the order is placed.
• 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.
• 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.
• 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.
• 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.
• 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.