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 <command> --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 <agentId> 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) → Buy with a card
• 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 with a card

Use when the user wants to purchase a product, subscription, domain, or any item from an online store checkout.

Virtual cards are backed by the user's credit card — no USDC or wallet funding needed. This is the fastest payment path.

Step 1: Request a virtual card

lobstercash cards request --amount <amount> --description "<what it's for>" [--period <period>]

Extract the amount, description, and period from context — don't ask if the user already told you (e.g. "buy me a $25 monthly AWS credit" → --amount 25 --description "AWS credits" --period monthly).

The --period flag is optional and sets the billing period for the virtual card mandate. Valid values: weekly, monthly, yearly. When omitted the card is single-use. Only ask the user about period if the purchase is clearly recurring and they haven't specified one.

This command handles everything — if the wallet isn't configured yet, it bundles setup automatically.

Step 2: Get user approval

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

Step 3: Verify and get card credentials

After approval, list cards and get the credentials for checkout:

lobstercash cards list
lobstercash cards reveal --card-id <id> --merchant-name "<store>" --merchant-url "<https://...>" --merchant-country <XX>

The card-id comes from the cards list output. Merchant details must be real — extract from the purchase context, don't invent them.

Product discovery with browser: When the user wants to buy something (e.g. "buy me running socks"), do NOT guess product URLs or category paths from your training data. Instead, discover real URLs first:

1. Web search to find the right page: search for "running socks site:nike.com" or "best running socks to buy online" to get real, current URLs
2. Open the best result: lobstercash browser open "https://nike.com/w/running-socks-7ny3qzy7ok" (use the URL from the search result, not a guess)
3. Extract products from the page: lobstercash browser extract "product names, prices, and links"
4. Present the real results to the user and let them pick

If the user hasn't specified a merchant, web search to find good options first. If no good search results, fall back to opening the merchant's homepage and navigating from there:

lobstercash browser open "https://nike.com"
lobstercash browser act "search for running socks"

Never invent URLs or paths from your training data. Always get URLs from web search results or by navigating the site's own UI. URL structures differ across every site and change frequently.

Once the user picks something (or if they came in already knowing what they want), route to one of the branches below.

Step 4: Complete the purchase

Use the revealed card number, CVC, and expiry to fill in the checkout form. Treat these values as sensitive — don't log them unnecessarily.

See cards request reference for full output format, and cards reference for listing, revealing, and card phases.

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 <needed> --description "<description>" to top up, show the approval URL, wait for user confirmation, then proceed.
• Wallet not configured → run lobstercash crypto request --amount <needed> --description "<description>" (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 <url>

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

Show the approval URL to the user, wait for them to confirm they approved, then list cards to get the card ID. See request card reference for details and cards reference for listing/revealing credentials.

Completing checkout with the browser

After the card is created, use browser commands to complete the purchase. This is the recommended approach — the user can watch the browser session live via the provided URL.

1. Open the merchant site (if not already in a browser session):

   lobstercash browser open "https://merchant.com/checkout"
   

   Share the Live view URL with the user so they can watch along.

2. Navigate to checkout using natural-language actions:

   lobstercash browser act "add the item to cart"
   lobstercash browser act "go to checkout"
   

3. Fill the payment form — card credentials are handled server-side and never reach the agent:

   lobstercash browser fill-card \
     --card-id <id> \
     --merchant-name "<name>" \
     --merchant-url "https://..." \
     --merchant-country US
   

4. Fill shipping/billing details and review order:

   lobstercash browser act "fill in shipping address: ..."
   lobstercash browser screenshot
   

   Show the screenshot or ask the user to check the live view before placing the order.

5. Place the order only after user confirms:

   lobstercash browser act "click place order"
   

6. Close the session when done:

   lobstercash browser close
   

Important: Always share the live view URL with the user so they can watch the checkout. Before clicking "place order" or equivalent, ask the user to confirm — do not submit orders autonomously. Card credentials never leave the server; the fill-card command handles them securely.

See browser reference for all browser commands.

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 <addr> --amount <n> --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 <needed> --description "<description>" to fund it — see crypto request reference.

Quick Reference

lobstercash agents register --name "<name>" --description "<desc>" --image-url "<url>"  # register a new agent
lobstercash agents list                                          # list all agents
lobstercash agents set-active <agentId>                          # set active agent
lobstercash 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 <addr> --amount <n> --token usdc    # send tokens
lobstercash crypto x402 fetch <url>                              # pay for API
lobstercash crypto request --amount <n> --description "<desc>"    # request crypto funding / top up (bundles wallet setup)
lobstercash crypto tx create|approve|status                      # low-level transaction management
lobstercash cards request --amount <n> --description "<desc>" [--period <weekly|monthly|yearly>]  # request virtual card (period optional, omit for single-use)
lobstercash cards list                                           # list cards (includes card-id)
lobstercash cards reveal --card-id <id> --merchant-name "..." --merchant-url "https://..." --merchant-country US  # checkout credentials
lobstercash browser open <url>                                   # start browser session, navigate to URL
lobstercash browser act "<instruction>"                          # perform action (e.g. "click add to cart")
lobstercash browser extract "<query>"                            # extract data (e.g. "product names and prices")
lobstercash browser observe                                      # list actionable elements on current page
lobstercash browser screenshot                                   # take a screenshot
lobstercash browser fill-card --card-id <id> --merchant-name "..." --merchant-url "https://..." --merchant-country US  # fill payment form (server-side)
lobstercash browser close                                        # close browser session

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 cards request if the user wants to request a virtual card for a purchase (Credit Card Path)
• 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 or reveal credentials for an existing virtual card
• Read browser if the user wants to browse a website, complete a checkout, find products, or interact with a web page
• 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. You cannot know the correct path structure for any website — /w/socks, /category/socks, /shop/socks are all guesses. Always browser open the homepage (https://example.com), then use browser act to search or navigate the site's own UI to find products.
• Placing orders without user confirmation: Always ask the user to confirm before clicking "place order" or similar. Show a screenshot or remind them to check the live view URL.
• Revealing card credentials manually when using browser checkout: Use browser fill-card instead of cards reveal. The fill-card command handles credentials server-side so they never reach the agent. Only use cards reveal when the user needs to manually paste credentials into a site you can't browser-automate.
• Forgetting to share the live view URL: When opening a browser session, always tell the user the live view URL so they can watch what's happening.
• Running browser commands without an open session: All browser commands except open require an active session. If no session exists, run browser open first.
• Leaving browser sessions open: Close sessions with browser close when checkout is done. Sessions consume resources on the provider.