@crossmint/lobster.cash 0.1.1

package/README.md

@@ -0,0 +1,121 @@
+# Crossmint Wallet Plugin
+
+Solana wallet integration for OpenClaw agents using the lobster.cash server flow.
+
+## Overview
+
+This plugin enables OpenClaw agents to:
+
+- Generate and manage local Solana signing keys (ed25519)
+- Pair with a user wallet using consent-based setup (`/api/claw/setup/*`)
+- Use server-issued tokens for authenticated wallet and order operations
+- Check wallet balances
+- Send tokens
+- Buy products from Amazon
+
+The plugin no longer requires manual API key pasting.
+
+## Installation
+
+```bash
+openclaw plugins install @crossmint/openclaw-wallet
+```
+
+## Configuration
+
+Enable the plugin in `~/.openclaw/.openclaw.json5`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "openclaw-wallet": {
+        enabled: true,
+        config: {
+          serverBaseUrl: "https://www.lobster.cash",
+          requestTimeoutMs: 15000,
+        },
+      },
+    },
+  },
+}
+```
+
+## Setup Workflow
+
+### Step 1: Start setup
+
+Ask the agent: "Set up my Crossmint wallet"
+
+The plugin will:
+
+1. Generate (or reuse) a local signer keypair
+2. Call `POST /api/claw/setup/start`
+3. Sign `pairingNonce` locally
+4. Call `POST /api/claw/setup/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 `crossmint_setup` again.
+
+The plugin will:
+
+1. Poll `GET /api/claw/setup/status`
+2. Read `retrievalNonce` when approved
+3. Sign `retrievalNonce`
+4. Call `POST /api/claw/setup/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/claw/token/refresh/init`
+  - `POST /api/claw/token/refresh`
+- Refresh is proof-of-possession gated (signed nonce)
+
+## Tools
+
+| Tool                     | Description                                                         |
+| ------------------------ | ------------------------------------------------------------------- |
+| `crossmint_setup`        | Start/finalize server-based setup flow                              |
+| `crossmint_configure`    | Deprecated (kept for compatibility)                                 |
+| `crossmint_balance`      | Check wallet balances                                               |
+| `crossmint_send`         | Send tokens to another address                                      |
+| `crossmint_wallet_info`  | Get wallet/setup session info                                       |
+| `crossmint_tx_status`    | Check transaction status                                            |
+| `crossmint_buy`          | Buy products from Amazon with SOL or USDC                           |
+| `crossmint_order_status` | Check order status (uses stored order client secret when available) |
+
+## Order Flow
+
+For purchases, plugin uses proxy endpoints:
+
+1. `POST /api/proxy/orders`
+2. `POST /api/proxy/wallets/:wallet/transactions` (serialized transaction)
+3. Local signature + `POST /api/proxy/wallets/:wallet/transactions/:txId/approve`
+4. `POST /api/proxy/orders/:orderId/payment` with `x-order-client-secret`
+
+## Local Storage
+
+Plugin state is stored at:
+
+- `~/.openclaw/crossmint-wallets/wallets.json`
+- or `CROSSMINT_WALLETS_DIR` if set
+
+Per agent it stores:
+
+- local signer keypair
+- pairing/setup state
+- wallet address
+- access/refresh tokens
+- order client secrets for follow-up status calls
+
+## Migration Note
+
+If you previously configured wallet + API key manually, run `crossmint_setup` again to migrate.

package/index.ts

@@ -0,0 +1,73 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  createCrossmintSetupTool,
+  createCrossmintConfigureTool,
+  createCrossmintBalanceTool,
+  createCrossmintSendTool,
+  createCrossmintWalletInfoTool,
+  createCrossmintTxStatusTool,
+  createCrossmintBuyTool,
+  createCrossmintOrderStatusTool,
+} from "./src/tools.js";
+import { crossmintConfigSchema } from "./src/config.js";
+
+const plugin = {
+  id: "openclaw-wallet",
+  name: "Crossmint Wallet",
+  description:
+    "Solana wallet integration with Crossmint. Manage wallets, check balances, and send tokens using delegated signing.",
+
+  configSchema: crossmintConfigSchema,
+
+  register(api: OpenClawPluginApi) {
+    // Parse and validate config at registration time
+    const config = crossmintConfigSchema.parse(api.pluginConfig);
+
+    // Register wallet setup tool (generates keypair, shows delegation URL)
+    api.registerTool(createCrossmintSetupTool(api, config), {
+      name: "crossmint_setup",
+    });
+
+    // Register configure tool (saves wallet address and API key from web)
+    api.registerTool(createCrossmintConfigureTool(api, config), {
+      name: "crossmint_configure",
+    });
+
+    // Register balance tool
+    api.registerTool(createCrossmintBalanceTool(api, config), {
+      name: "crossmint_balance",
+    });
+
+    // Register send tool
+    api.registerTool(createCrossmintSendTool(api, config), {
+      name: "crossmint_send",
+    });
+
+    // Register wallet info tool
+    api.registerTool(createCrossmintWalletInfoTool(api, config), {
+      name: "crossmint_wallet_info",
+    });
+
+    // Register transaction status tool
+    api.registerTool(createCrossmintTxStatusTool(api, config), {
+      name: "crossmint_tx_status",
+    });
+
+    // Register Amazon buy tool
+    api.registerTool(createCrossmintBuyTool(api, config), {
+      name: "crossmint_buy",
+    });
+
+    // Register order status tool
+    api.registerTool(createCrossmintOrderStatusTool(api, config), {
+      name: "crossmint_order_status",
+    });
+
+    api.logger.info("Crossmint wallet plugin loaded", {
+      serverBaseUrl: config.serverBaseUrl,
+      requestTimeoutMs: config.requestTimeoutMs,
+    });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "openclaw-wallet",
+  "name": "Crossmint",
+  "description": "Solana wallet integration using Crossmint smart wallets with delegated signing.",
+  "version": "0.3.0",
+  "skills": ["skills/crossmint"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@crossmint/lobster.cash",
+  "version": "0.1.1",
+  "description": "OpenClaw plugin for Solana wallet integration with Crossmint smart wallets",
+  "type": "module",
+  "main": "./index.ts",
+  "files": [
+    "index.ts",
+    "src/",
+    "skills/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Crossmint/lobster.cash",
+    "directory": "packages/openclaw-crossmint-plugin"
+  },
+  "keywords": [
+    "openclaw",
+    "crossmint",
+    "solana",
+    "wallet",
+    "plugin",
+    "crypto",
+    "web3"
+  ],
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.48",
+    "@solana/web3.js": "^1.98.0",
+    "bs58": "^6.0.0",
+    "tweetnacl": "^1.0.3"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.26"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/skills/crossmint/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: crossmint
+description: Use when the user wants to manage Solana wallets, check balances, send tokens, buy from Amazon, or run Crossmint/lobster.cash setup flow.
+metadata: { "openclaw": { "emoji": "💳" } }
+---
+
+# Crossmint Wallet
+
+Manage Solana wallets through the lobster.cash server-backed consent flow.
+
+This skill is the source of truth for how agents should operate the Crossmint plugin safely and correctly.
+
+## Critical model (read first)
+
+1. This is a **server-session flow**, not manual API key setup.
+2. `crossmint_setup` is the entry point for both first-time setup and setup finalization.
+3. The agent keeps a **local signer** (ed25519 keypair) and signs server nonces.
+4. The server issues short-lived `accessToken` + longer-lived `refreshToken`.
+5. Protected wallet/order actions use Bearer access token; refresh happens automatically.
+6. `crossmint_configure` is deprecated and should not be used for normal setup.
+
+## When to activate this skill
+
+Activate whenever the user asks to:
+
+1. Set up or reconnect agent wallet access
+2. Check wallet balance
+3. Send USDC
+4. Track transaction status
+5. Buy Amazon products through the plugin
+6. Track order status
+7. Debug pairing/token/session failures
+
+## Tool selection map
+
+| User intent                     | Tool                     | Notes                                                      |
+| ------------------------------- | ------------------------ | ---------------------------------------------------------- |
+| Connect wallet first time       | `crossmint_setup`        | Returns consent URL, then must be run again after approval |
+| Re-run pending setup            | `crossmint_setup`        | Polls setup status and finalizes retrieval when approved   |
+| See setup/session state         | `crossmint_wallet_info`  | Includes setup status and pending consent URL              |
+| Check funds                     | `crossmint_balance`      | Requires completed setup                                   |
+| Send tokens                     | `crossmint_send`         | Optionally wait for completion                             |
+| Check send tx status            | `crossmint_tx_status`    | Optionally wait for completion                             |
+| Buy Amazon item                 | `crossmint_buy`          | Requires complete shipping + recipient fields              |
+| Check order/delivery status     | `crossmint_order_status` | Uses stored `clientSecret` or user-provided one            |
+| Legacy config confusion         | `crossmint_setup`        | Migrates legacy wallets to server-token model              |
+| Ask about `crossmint_configure` | `crossmint_configure`    | Returns deprecation guidance; keep for compatibility only  |
+
+## Setup workflow (exact behavior)
+
+### First run of `crossmint_setup`
+
+The plugin:
+
+1. Generates/reuses local signer keypair
+2. Calls `POST /api/claw/setup/start`
+3. Signs `pairingNonce` with local signer
+4. Calls `POST /api/claw/setup/verify`
+5. Stores `pairingId` and `consentUrl`
+6. Returns instructions to open consent URL
+
+### User action
+
+User opens consent URL and approves in browser.
+
+### Second run of `crossmint_setup`
+
+The plugin:
+
+1. Calls `GET /api/claw/setup/status?pairingId=...`
+2. If approved, reads `retrievalNonce`
+3. Signs `retrievalNonce`
+4. Calls `POST /api/claw/setup/retrieve`
+5. Stores `walletAddress`, `accessToken`, `refreshToken`, `expiresAt`
+6. Marks setup configured
+
+## Setup status handling
+
+When setup is pending, `crossmint_setup` may return these states:
+
+1. `awaiting-consent`:
+   URL issued; user still needs to approve
+2. `awaiting-approval`:
+   Verification done, waiting on consent completion
+3. `denied`:
+   User denied; ask user to re-run setup to generate a new consent request
+4. `expired`:
+   Consent window expired; re-run setup to restart
+5. `configured`:
+   Wallet ready
+
+Agent behavior:
+
+1. Never invent success if setup is not configured
+2. If pending, always show consent URL and next step
+3. If denied/expired, explain that a fresh `crossmint_setup` run is required
+
+## Auth and refresh behavior
+
+1. Protected calls include `Authorization: Bearer <accessToken>`
+2. Plugin refreshes automatically before expiry and on `ACCESS_TOKEN_EXPIRED`
+3. Refresh sequence:
+   1. `POST /api/claw/token/refresh/init`
+   2. Sign `refreshNonce`
+   3. `POST /api/claw/token/refresh`
+4. If refresh token is missing/invalid, agent must ask user to run setup again
+
+## Wallet and transfer operations
+
+### `crossmint_balance`
+
+Use for funds overview. Returns token/amount list.
+
+If no wallet/session:
+
+1. Tell user to run `crossmint_setup`
+2. If setup pending, point user to consent and rerun setup
+
+### `crossmint_send`
+
+USDC-only policy:
+
+1. Always send `usdc`
+2. Never choose `sol` or other token identifiers
+
+Required:
+
+1. `to`
+2. `amount`
+
+Optional:
+
+1. `wait` (default `false`)
+2. `timeoutMs` (default `60000`)
+
+Transfer flow:
+
+1. Create proxy transaction
+2. Sign approval message locally
+3. Approve transaction
+4. Return pending/success/failed with tx details
+
+### `crossmint_tx_status`
+
+Use when user asks "did it go through?" or wants confirmation wait.
+
+## Amazon purchase operations
+
+### `crossmint_buy` requirements
+
+Do not call unless all required fields are known:
+
+1. `productId` (ASIN or Amazon URL)
+2. `recipientEmail`
+3. `recipientName`
+4. `addressLine1`
+5. `city`
+6. `postalCode`
+7. `country`
+
+Optional:
+
+1. `addressLine2`
+2. `state`
+
+Currency policy:
+
+1. Always use `usdc`
+2. Do not use `sol`
+
+### Safe purchase policy (mandatory)
+
+Before purchase:
+
+1. Confirm the exact product if user request is vague
+2. Confirm shipping fields
+3. Keep payment currency as `usdc`
+
+After purchase:
+
+1. Read returned product title and price back to user
+2. Share order ID and transaction explorer link
+3. Tell user to use `crossmint_order_status` for delivery updates
+
+### `crossmint_order_status`
+
+1. Takes `orderId`
+2. Can use optional `clientSecret`
+3. If no stored or provided client secret exists, explain that status lookup requires it
+
+## Legacy/migration behavior
+
+If wallet info indicates legacy API-key setup:
+
+1. Explain legacy config is deprecated
+2. Instruct user to run `crossmint_setup` again to migrate
+3. Do not request manual API key paste
+
+## Error playbook
+
+### "No wallet found"
+
+Meaning: setup never started.
+
+Action: run `crossmint_setup`.
+
+### "Wallet not configured" or pending setup text
+
+Meaning: consent flow not complete.
+
+Action:
+
+1. open consent URL
+2. re-run `crossmint_setup`
+
+### `ACCESS_TOKEN_EXPIRED`
+
+Meaning: access token expired.
+
+Action: plugin should refresh automatically; if it still fails, run `crossmint_setup` again.
+
+### Missing refresh token / invalid session
+
+Meaning: stored session no longer usable.
+
+Action: rerun full setup flow.
+
+### Order status missing client secret
+
+Meaning: plugin has no stored order session.
+
+Action: ask user for explicit `clientSecret` for that order.
+
+## Agent response style guidelines
+
+When operating this skill:
+
+1. Keep next actions explicit and numbered
+2. Include concrete status (`pending`, `configured`, `denied`, `expired`) in user-facing text
+3. For high-risk operations (send/buy), echo critical details before execution
+4. Never claim money moved unless tx/order status indicates success/completed
+
+## Local storage and security notes
+
+1. State file: `~/.openclaw/crossmint-wallets/wallets.json` (or `CROSSMINT_WALLETS_DIR`)
+2. Stored per agent:
+   1. local keypair
+   2. setup/pairing status
+   3. wallet address
+   4. access/refresh tokens + expiry
+   5. order client secrets
+3. Private key stays local; only signatures are sent to server endpoints
+
+## Quick examples
+
+### User: "Connect my wallet"
+
+1. Call `crossmint_setup`
+2. Return consent URL
+3. Tell user to approve it
+4. Tell user to run setup again after approval
+
+### User: "Send 20 USDC to <address> and wait"
+
+1. Ensure configured wallet
+2. Call `crossmint_send` with `wait=true` (USDC-only policy)
+3. Return tx id, status, hash/explorer if available
+
+### User: "Buy this Amazon ASIN B00O79SKV6"
+
+1. Confirm shipping + email fields
+2. Call `crossmint_buy`
+3. Return order ID, payment status, explorer link
+4. Offer `crossmint_order_status` follow-up