Lobster.Cash Wallet Plugin

Give your OpenClaw agent a wallet that can hold virtual credit cards, and stablecoins in Solana.

Overview

This plugin enables OpenClaw agents to:

• Generate and manage local Solana signing keys
• Pair with a user wallet using consent-based setup (/api/claw/setup/*)
• Check wallet balances
• Create, approve, and track wallet transactions
• Send tokens (backward-compatible convenience wrapper)

Installation

openclaw plugins install @crossmint/lobster.cash

Configuration

Enable the plugin in ~/.openclaw/.openclaw.json5:

{
  plugins: {
    entries: {
      "lobster.cash": {
        enabled: true,
        config: {
          serverBaseUrl: "https://www.lobster.cash",
          requestTimeoutMs: 15000,
        },
      },
    },
  },
}

If you previously installed an older build that used the openclaw-wallet id, remove that entry and extension to avoid duplicate plugin warnings.

Setup Workflow

Step 1: Start setup

Ask the agent: "Set up my lobster.cash wallet"

The plugin will:

1. Generate (or reuse) a local signer keypair
2. Call POST /api/agent/setup/sessions
3. Sign pairingNonce locally
4. Call POST /api/agent/setup/sessions/{setupSessionId}/verify
5. Return a consent URL for the user to open

Step 2: User approves consent URL

Open the URL in browser and approve.

Step 3: Finalize setup

Run lobster_setup again.

The plugin will:

1. Poll GET /api/agent/setup/sessions/{setupSessionId}
2. Read retrievalNonce when approved
3. Sign retrievalNonce
4. Call POST /api/agent/setup/sessions/{setupSessionId}/retrieve
5. Store walletAddress, accessToken, refreshToken, and expiry locally

Authentication Model

• Protected calls use Authorization: Bearer <accessToken>
• On expiry, plugin refreshes automatically via:
  • POST /api/agent/token/refresh/init
  • POST /api/agent/token/refresh
• Refresh is proof-of-possession gated (signed nonce)

Tools

| Tool | Description | | --------------------- | --------------------------------------------- | | lobster_setup | Start/finalize server-based setup flow | | lobster_balance | Check wallet balances | | lobster_tx_create | Create transaction and return message to sign | | lobster_tx_approve | Approve/broadcast transaction with signature | | lobster_wallet_info | Get wallet/setup session info | | lobster_tx_status | Check transaction status | | lobster_send | Convenience wrapper: transfer create+approve |

Recommended Integration Flow

For cross-skill interoperability (e.g. external checkout/orchestration skills), use the atomic transaction flow:

1. lobster_tx_create (type: transfer, serialized, or calls)
2. lobster_tx_approve (provide signature or let lobster sign messageToSign)
3. lobster_tx_status (optionally with wait: true)

lobster_send remains available for simple transfer UX and backward compatibility.

Local Storage

Plugin state is stored at:

• ~/.openclaw/lobster-cash/wallets.json
• or LOBSTER_CASH_WALLETS_DIR if set

Per agent it stores:

• local signer keypair
• pairing/setup state
• wallet address
• access/refresh tokens

Migration Note

If you previously configured wallet + API key manually, run lobster_setup again to migrate.

Development Testing

From the monorepo root:

pnpm run test:plugin:unit
pnpm run test:plugin:integration
pnpm run test:plugin

Test files are intentionally kept outside the publishable plugin package, under plugins/openclaw/tests/.

Coverage includes:

• tool/api/wallet unit tests
• plugin registration + tool wiring
• package/manifest metadata sync checks (openclaw.plugin.json vs package.json)
• local end-to-end plugin flow over HTTP mock server (setup, refresh, balance, tx create/approve, send, status)

For real server validation (no mocks), use the live scripts:

pnpm run e2e:plugin:setup
pnpm run e2e:plugin:balance

These live scripts preflight-check localhost server reachability before executing.

Optional destructive checks:

PLUGIN_LIVE_SEND_CONFIRM=YES PLUGIN_LIVE_SEND_RECIPIENT=<address> pnpm run e2e:plugin:send

See plugins/openclaw/tests/README.md for full live test configuration.