@crossmint/openclaw-wallet 0.2.2

package/README.md

@@ -0,0 +1,157 @@
+# Crossmint Wallet Plugin
+
+Solana wallet integration for OpenClaw agents using Crossmint smart wallets with delegated signing.
+
+## Overview
+
+This plugin enables OpenClaw agents to:
+- Generate and manage local Solana signing keys (ed25519)
+- Use Crossmint smart wallets on Solana
+- Check wallet balances (SOL, USDC, SPL tokens)
+- Send tokens to other addresses
+
+The key innovation is **delegated signing**: the agent holds its own private key locally, and users authorize the agent to operate their Crossmint wallet through a web-based delegation flow.
+
+## Installation
+
+```bash
+openclaw plugins install @crossmint/openclaw-wallet
+```
+
+## Configuration
+
+Enable the plugin in `~/.openclaw/.openclaw.json5`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "openclaw-wallet": {
+        enabled: true
+      }
+    }
+  }
+}
+```
+
+> **Note:** Currently only Solana devnet (staging) is supported. Mainnet support coming soon.
+
+## Usage
+
+### Setting Up a Wallet (2-Step Process)
+
+**Step 1: Generate keypair and get delegation URL**
+
+Ask the agent: "Set up my Crossmint wallet"
+
+The agent will:
+1. Generate a local Solana keypair (ed25519)
+2. Provide a URL with the public key for delegation setup
+
+**Step 2: Complete setup on the web app**
+
+1. Open the delegation URL in your browser
+2. The web app will:
+   - Create a Crossmint smart wallet
+   - Add the agent's public key as a delegated signer
+   - Show you the **wallet address** and **API key**
+
+**Step 3: Configure the agent**
+
+Tell the agent: "Configure my wallet with address X and API key Y"
+
+The agent will use `crossmint_configure` to save these credentials securely.
+
+### Checking Balance
+
+Ask the agent: "What's my wallet balance?"
+
+### Sending Tokens
+
+Ask the agent: "Send 10 USDC to <solana-address>"
+
+The agent will:
+1. Confirm the recipient and amount
+2. Sign the transaction locally using ed25519
+3. Submit to Crossmint for execution on Solana
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `crossmint_setup` | Generate Solana keypair and get delegation URL |
+| `crossmint_configure` | Save wallet address and API key from web app |
+| `crossmint_balance` | Check wallet balances (SOL, USDC, SPL tokens) |
+| `crossmint_send` | Send tokens to another Solana address |
+| `crossmint_wallet_info` | Get detailed wallet information |
+| `crossmint_tx_status` | Check transaction status |
+| `crossmint_buy` | Buy products from Amazon with SOL or USDC |
+| `crossmint_order_status` | Check Amazon order/delivery status |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        OpenClaw Agent                        │
+├─────────────────────────────────────────────────────────────┤
+│  Local Solana Keypair (ed25519)                             │
+│  - Private key stored at ~/.openclaw/crossmint-wallets/     │
+│  - Signs transaction approvals locally                      │
+│  - Wallet address + API key stored after web setup          │
+└────────────────────────┬────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  Delegation Web App (external)               │
+├─────────────────────────────────────────────────────────────┤
+│  - Receives agent's public key via URL                      │
+│  - Creates Crossmint smart wallet                           │
+│  - Adds agent as delegated signer                           │
+│  - Returns wallet address + API key to user                 │
+└────────────────────────┬────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Crossmint Smart Wallet                    │
+├─────────────────────────────────────────────────────────────┤
+│  - Deployed on Solana                                       │
+│  - Agent's address registered as delegated signer           │
+│  - User retains admin control                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Security
+
+- Private keys are stored locally on the agent's machine with secure file permissions
+- Keys are never transmitted to Crossmint
+- Uses ed25519 cryptography (Solana native)
+- API key is stored locally after user retrieves it from web app
+- Users maintain admin control and can revoke delegation at any time
+- The agent can only perform actions explicitly authorized through delegation
+
+## Troubleshooting
+
+**"No wallet found for agent"**
+- Run `crossmint_setup` first to generate a keypair
+
+**"Wallet not fully configured"**
+- Complete the web setup flow and run `crossmint_configure` with wallet address and API key
+
+**"Failed to get balance" or "Failed to send"**
+- Verify the API key is correct
+- Check that the wallet address matches the one shown in the web app
+- Ensure the wallet has sufficient balance
+
+## Plugin Management
+
+```bash
+# List all plugins
+openclaw plugins list
+
+# Check plugin info
+openclaw plugins info openclaw-wallet
+
+# Enable/disable
+openclaw plugins enable openclaw-wallet
+openclaw plugins disable openclaw-wallet
+```

package/index.ts

@@ -0,0 +1,72 @@
+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", {
+      environment: "staging",
+    });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crossmint/openclaw-wallet",
+  "version": "0.2.2",
+  "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/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 crypto balances, send tokens (SOL, USDC), buy products from Amazon with crypto, or set up Crossmint smart wallet delegation. Activate on wallet setup, balance checks, token transfers, Amazon purchases, or Crossmint mentions.
+metadata: { "openclaw": { "emoji": "💳" } }
+---
+
+# Crossmint Wallet
+
+Manage Solana wallets using Crossmint smart wallets with delegated signing. The agent holds a local signing key, and users authorize it via a web-based delegation flow.
+
+> **Note:** Currently only **Solana devnet** (staging environment) is supported. Mainnet/production support coming soon.
+
+## When to Activate
+
+Use this skill when the user:
+
+- Wants to set up a crypto/Solana wallet
+- Asks about wallet balance (SOL, USDC, tokens)
+- Wants to send tokens to someone
+- Wants to buy something from Amazon with crypto
+- Mentions Crossmint or smart wallets
+- Asks about wallet delegation or signing
+
+## Tools Overview
+
+| Tool | Purpose |
+|------|---------|
+| `crossmint_setup` | Generate local keypair, get delegation URL |
+| `crossmint_configure` | Save wallet address + API key after web setup |
+| `crossmint_balance` | Check SOL, USDC, and token balances |
+| `crossmint_send` | Send tokens to another address (supports wait for confirmation) |
+| `crossmint_tx_status` | Check transaction status or wait for completion |
+| `crossmint_wallet_info` | Get detailed wallet information |
+| `crossmint_buy` | Buy products from Amazon with SOL or USDC |
+| `crossmint_order_status` | Check Amazon order/delivery status |
+
+## Setup Workflow (First Time)
+
+### Step 1: Generate keypair
+
+```
+User: "Set up my Crossmint wallet"
+Agent: Use crossmint_setup
+```
+
+This generates a local ed25519 keypair and returns a delegation URL.
+
+### Step 2: User completes web setup
+
+The user opens the delegation URL in their browser. The web app will:
+1. Create a Crossmint smart wallet
+2. Add the agent's public key as a delegated signer
+3. Display the **wallet address** and **API key**
+
+### Step 3: Configure the agent
+
+```
+User: "My wallet address is X and API key is Y"
+Agent: Use crossmint_configure with walletAddress and apiKey
+```
+
+Now the wallet is ready to use.
+
+## Common Operations
+
+### Check balance
+
+```
+User: "What's my wallet balance?"
+Agent: Use crossmint_balance
+```
+
+Returns SOL, USDC, and other token balances.
+
+### Send tokens
+
+```
+User: "Send 10 USDC to <address>"
+Agent: Use crossmint_send with to, amount, token="usdc"
+```
+
+```
+User: "Send 0.1 SOL to <address> and wait for confirmation"
+Agent: Use crossmint_send with to, amount, token="sol", wait=true
+```
+
+Supported tokens:
+- `sol` - Native SOL
+- `usdc` - USDC stablecoin
+- Any SPL token address
+
+### Check transaction status
+
+```
+User: "What's the status of transaction abc-123?"
+Agent: Use crossmint_tx_status with transactionId="abc-123"
+```
+
+```
+User: "Wait for transaction abc-123 to complete"
+Agent: Use crossmint_tx_status with transactionId="abc-123", wait=true
+```
+
+### Get wallet info
+
+```
+User: "Show my wallet details"
+Agent: Use crossmint_wallet_info
+```
+
+## Amazon Purchases
+
+Buy products from Amazon using SOL or USDC from the agent's wallet. Crossmint acts as Merchant of Record, handling payments, shipping, and taxes.
+
+### Buy a product
+
+```
+User: "Buy me this Amazon product: B00O79SKV6"
+Agent: Use crossmint_buy with product ASIN and shipping address
+```
+
+Required information:
+- Amazon product ASIN or URL
+- Recipient email
+- Full shipping address (name, street, city, postal code, country)
+
+### Check order status
+
+```
+User: "What's the status of my order?"
+Agent: Use crossmint_order_status with the order ID
+```
+
+### Amazon Product Locator Formats
+
+- ASIN: `B00O79SKV6`
+- Full URL: `https://www.amazon.com/dp/B00O79SKV6`
+
+### Amazon Order Restrictions
+
+Orders may fail if:
+- Item not sold by Amazon or verified seller
+- Item requires special shipping
+- Item is digital (ebooks, software, etc.)
+- Item is from Amazon Fresh, Pantry, Pharmacy, or Subscribe & Save
+
+## Tool Parameters
+
+### crossmint_setup
+
+```json
+{
+  "agentId": "optional - defaults to current agent"
+}
+```
+
+### crossmint_configure
+
+```json
+{
+  "walletAddress": "required - smart wallet address from web app",
+  "apiKey": "required - API key from web app",
+  "agentId": "optional"
+}
+```
+
+### crossmint_balance
+
+```json
+{
+  "agentId": "optional"
+}
+```
+
+### crossmint_send
+
+```json
+{
+  "to": "required - recipient Solana address or email locator",
+  "amount": "required - e.g., '10', '0.5'",
+  "token": "optional - 'sol', 'usdc', or SPL address (default: 'usdc')",
+  "wait": "optional - if true, wait for confirmation (default: false)",
+  "timeoutMs": "optional - max wait time in ms (default: 60000)",
+  "agentId": "optional"
+}
+```
+
+### crossmint_tx_status
+
+```json
+{
+  "transactionId": "required - transaction ID from crossmint_send",
+  "wait": "optional - if true, wait for terminal state (default: false)",
+  "timeoutMs": "optional - max wait time in ms (default: 60000)",
+  "agentId": "optional"
+}
+```
+
+### crossmint_wallet_info
+
+```json
+{
+  "agentId": "optional"
+}
+```
+
+### crossmint_buy
+
+```json
+{
+  "productId": "required - Amazon ASIN or URL",
+  "recipientEmail": "required - for order confirmation",
+  "recipientName": "required - full name for shipping",
+  "addressLine1": "required - street address",
+  "addressLine2": "optional - apt, suite, etc.",
+  "city": "required",
+  "state": "optional - state/province code",
+  "postalCode": "required",
+  "country": "required - e.g., 'US'",
+  "currency": "optional - 'sol' or 'usdc' (default: 'usdc')",
+  "agentId": "optional"
+}
+```
+
+### crossmint_order_status
+
+```json
+{
+  "orderId": "required - from crossmint_buy response",
+  "agentId": "optional"
+}
+```
+
+## Troubleshooting
+
+### "No wallet found for agent"
+
+The user hasn't run setup yet.
+
+```
+Agent: Use crossmint_setup first to generate a keypair
+```
+
+### "Wallet not fully configured"
+
+Keypair exists but web setup wasn't completed.
+
+```
+Agent:
+1. Use crossmint_wallet_info to get the delegation URL
+2. Ask user to complete web setup
+3. Use crossmint_configure with the wallet address and API key
+```
+
+### "Failed to get balance" or "Failed to send"
+
+- Verify the API key is correct
+- Check wallet address matches the web app
+- Ensure sufficient balance for transfers
+
+## Security Notes
+
+- Private keys are stored locally at `~/.openclaw/crossmint-wallets/`
+- Keys never leave the agent's machine
+- Uses ed25519 cryptography (Solana native)
+- Users retain admin control and can revoke delegation anytime
+- Always verify recipient addresses before sending
+
+## Best Practices
+
+1. **Always check balance before sending** - Avoid failed transactions
+2. **Confirm recipient with user** - Double-check addresses for large transfers
+3. **Get devnet tokens for testing** - Use Solana devnet faucets to get test SOL
+4. **One wallet per agent** - Each agent ID gets its own keypair