lobstercash

What this skill does

# Lobster Cash CLI Skill

The Lobster Cash CLI (`lobstercash`) gives AI agents payment tools — a blockchain wallet, card permissions 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 <command> --help` for full flag details on any command.

## Installation

Install globally:

```bash
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.

```bash
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](references/agents.md) 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 something online](#a-buy-something-online)
- **B) Pay for a paid API endpoint** (x402 protocol) → [Pay an API with x402](#b-pay-an-api-with-x402)
- **C) Anything else** (check balance, send crypto, view status, link wallet) → [Other actions](#c-other-actions)

---

## A) Buy something online

Use 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 card permission, then drive checkout in a browser. What changes is **who drives the browser** for this install. Run:

```bash
lobstercash config get browser-enabled
```

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

If `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 permission credentials with `cards reveal` and walk them through entering them at the merchant's checkout page themselves.

---

## 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

```bash
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](references/crypto-request.md) for the full crypto request flow.

### Step 2: Fetch the paid endpoint

```bash
lobstercash crypto x402 fetch <url>
```

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

### 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](references/x402.md) for output format and common failures.

---

## C) Other actions

For everything else — checking balances, sending crypto, viewing wallet status, or linking a wallet — 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`), 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](references/balance.md)
- **Send tokens:** `lobstercash crypto send --to <addr> --amount <n> --token usdc` → [send reference](references/send.md)
- **View wallet status:** `lobstercash status` → [status reference](references/status.md)
- **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.
- **Sign/submit a transaction:** `lobstercash crypto tx create` → [tx reference](references/tx.md)

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](references/crypto-request.md).

## Quick Reference

```bash
lobstercash agents register --name "<name>" --description "<desc>" --image-url "<url>"  # register a new agent
lobstercash agents list                                          # list all agents
lobstercash agents set-active <agentId>                          # set active agent
lobstercash config get browser-enabled                           # check which browser drives online purchases (used in Section A)
lobstercash status                                               # check status & readiness & wallet address
lobstercash setup                                                # link agent to wallet (no purchase needed)
lobstercash crypto balance                                       # check balances
lobstercash crypto send --to <addr> --amount <n> --token usdc    # send tokens
lobstercash crypto x402 fetch <url>                              # pay for API
lobstercash crypto request --amount <n> --description "<desc>"    # request crypto funding / top up (bu