@crossmint/openclaw-wallet 0.2.2 → 0.2.3

package/README.md

@@ -9,6 +9,7 @@ This plugin enables OpenClaw agents to:
 - Use Crossmint smart wallets on Solana
 - Check wallet balances (SOL, USDC, SPL tokens)
 - Send tokens to other addresses
+- **Buy products from Amazon** with SOL or USDC
 
 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.
 
@@ -38,7 +39,7 @@ Enable the plugin in `~/.openclaw/.openclaw.json5`:
 
 ## Usage
 
-### Setting Up a Wallet (2-Step Process)
+### Setting Up a Wallet (3-Step Process)
 
 **Step 1: Generate keypair and get delegation URL**
 
@@ -46,13 +47,13 @@ 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
+2. Provide a delegation URL: `https://www.lobster.cash/configure?pubkey=<your-public-key>`
 
 **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
+   - Create a Crossmint smart wallet on Solana devnet
    - Add the agent's public key as a delegated signer
    - Show you the **wallet address** and **API key**
 
@@ -75,6 +76,33 @@ The agent will:
 2. Sign the transaction locally using ed25519
 3. Submit to Crossmint for execution on Solana
 
+### Buying from Amazon
+
+Ask the agent: "Buy me this Amazon product: B00O79SKV6"
+
+The agent will:
+1. Ask for shipping address if not provided
+2. Create an order with Crossmint
+3. Sign the payment transaction locally
+4. Submit the payment and confirm on-chain
+5. Return the order ID and Solana explorer link
+
+**Example purchase flow:**
+```
+User: "Buy B00O79SKV6 and ship to John Doe, 123 Main St, New York NY 10001"
+
+Agent: ✅ Purchase complete!
+
+Product: AmazonBasics USB Cable
+Price: 0.05 SOL
+Order ID: order_abc123
+Payment: completed
+
+Transaction: https://explorer.solana.com/tx/5x...?cluster=devnet
+
+Use crossmint_order_status to check delivery status.
+```
+
 ## Tools
 
 | Tool | Description |
@@ -88,6 +116,36 @@ The agent will:
 | `crossmint_buy` | Buy products from Amazon with SOL or USDC |
 | `crossmint_order_status` | Check Amazon order/delivery status |
 
+## Amazon Purchase Flow
+
+When you use `crossmint_buy`, the plugin executes a complete delegated signer flow:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. Create Order                                            │
+│     POST /orders → Returns serialized payment transaction   │
+├─────────────────────────────────────────────────────────────┤
+│  2. Create Transaction                                      │
+│     POST /wallets/{address}/transactions                    │
+│     → Returns approval message to sign                      │
+├─────────────────────────────────────────────────────────────┤
+│  3. Sign Approval (Local)                                   │
+│     Agent signs message with ed25519 keypair                │
+├─────────────────────────────────────────────────────────────┤
+│  4. Submit Approval                                         │
+│     POST /wallets/{address}/transactions/{id}/approvals     │
+├─────────────────────────────────────────────────────────────┤
+│  5. Wait for Broadcast                                      │
+│     Poll until on-chain txId is available                   │
+├─────────────────────────────────────────────────────────────┤
+│  6. Confirm Payment (CRITICAL)                              │
+│     POST /orders/{orderId}/payment                          │
+│     → Notifies Crossmint that payment is on-chain           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+All steps are handled automatically by the plugin.
+
 ## Architecture
 
 ```
@@ -102,7 +160,7 @@ The agent will:
                          │
                          ▼
 ┌─────────────────────────────────────────────────────────────┐
-│                  Delegation Web App (external)               │
+│              Delegation Web App (lobster.cash)               │
 ├─────────────────────────────────────────────────────────────┤
 │  - Receives agent's public key via URL                      │
 │  - Creates Crossmint smart wallet                           │
@@ -114,16 +172,17 @@ The agent will:
 ┌─────────────────────────────────────────────────────────────┐
 │                    Crossmint Smart Wallet                    │
 ├─────────────────────────────────────────────────────────────┤
-│  - Deployed on Solana                                       │
+│  - Deployed on Solana (devnet)                              │
 │  - Agent's address registered as delegated signer           │
 │  - User retains admin control                               │
+│  - Holds SOL/USDC for purchases and transfers               │
 └─────────────────────────────────────────────────────────────┘
 ```
 
 ## Security
 
-- Private keys are stored locally on the agent's machine with secure file permissions
-- Keys are never transmitted to Crossmint
+- Private keys are stored locally on the agent's machine with secure file permissions (0600)
+- Keys are never transmitted to Crossmint - only signatures
 - 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
@@ -135,13 +194,23 @@ The agent will:
 - 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
+- Complete the web setup flow at the delegation URL
+- Run `crossmint_configure` with wallet address and API key from the web app
 
 **"Failed to get balance" or "Failed to send"**
-- Verify the API key is correct
+- Verify the API key is correct (should start with `ck_staging_`)
 - Check that the wallet address matches the one shown in the web app
 - Ensure the wallet has sufficient balance
 
+**"Insufficient funds" (Amazon purchase)**
+- Check balance with `crossmint_balance`
+- Fund the wallet with more SOL or USDC
+- For devnet testing, use Solana faucets for test SOL
+
+**"Timeout waiting for transaction to be broadcast"**
+- Check transaction status with `crossmint_tx_status`
+- Solana network may be congested - wait and retry
+
 ## Plugin Management
 
 ```bash
@@ -155,3 +224,11 @@ openclaw plugins info openclaw-wallet
 openclaw plugins enable openclaw-wallet
 openclaw plugins disable openclaw-wallet
 ```
+
+## Supported Currencies
+
+| Currency | Token | Use Cases |
+|----------|-------|-----------|
+| SOL | Native Solana | Transfers, Amazon purchases |
+| USDC | USD Coin | Transfers, Amazon purchases |
+| SPL tokens | Any mint address | Transfers only |

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-wallet",
   "name": "Crossmint",
   "description": "Solana wallet integration using Crossmint smart wallets with delegated signing.",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "skills": ["skills/crossmint"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossmint/openclaw-wallet",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "OpenClaw plugin for Solana wallet integration with Crossmint smart wallets",
   "type": "module",
   "main": "./index.ts",

package/skills/crossmint/SKILL.md

@@ -43,14 +43,14 @@ User: "Set up my Crossmint wallet"
 Agent: Use crossmint_setup
 ```
 
-This generates a local ed25519 keypair and returns a delegation URL.
+This generates a local ed25519 keypair and returns a delegation URL pointing to `https://www.lobster.cash/configure?pubkey=<agent-public-key>`.
 
 ### 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
+The user opens the delegation URL in their browser. The web app (lobster.cash) will:
+1. Create a Crossmint smart wallet on Solana devnet
 2. Add the agent's public key as a delegated signer
-3. Display the **wallet address** and **API key**
+3. Display the **wallet address** and **API key** for the user to copy
 
 ### Step 3: Configure the agent
 
@@ -59,7 +59,7 @@ 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.
+Now the wallet is ready to use for balance checks, transfers, and Amazon purchases.
 
 ## Common Operations
 
@@ -70,7 +70,7 @@ User: "What's my wallet balance?"
 Agent: Use crossmint_balance
 ```
 
-Returns SOL, USDC, and other token balances.
+Returns SOL, USDC, and other token balances on the smart wallet.
 
 ### Send tokens
 
@@ -112,6 +112,19 @@ Agent: Use crossmint_wallet_info
 
 Buy products from Amazon using SOL or USDC from the agent's wallet. Crossmint acts as Merchant of Record, handling payments, shipping, and taxes.
 
+### How It Works (Under the Hood)
+
+When you use `crossmint_buy`, the plugin executes a 6-step delegated signer flow:
+
+1. **Create Order** - Crossmint creates an Amazon order and returns a payment transaction
+2. **Create Transaction** - The serialized transaction is submitted to Crossmint's wallet API
+3. **Sign Approval** - The agent signs an approval message locally using ed25519
+4. **Submit Approval** - The signed approval is sent to Crossmint
+5. **Wait for Broadcast** - Poll until the transaction is confirmed on-chain
+6. **Confirm Payment** - Submit the on-chain transaction ID to complete the order
+
+The entire flow happens automatically - the agent handles all signing and API calls.
+
 ### Buy a product
 
 ```
@@ -121,9 +134,37 @@ Agent: Use crossmint_buy with product ASIN and shipping address
 
 Required information:
 - Amazon product ASIN or URL
-- Recipient email
+- Recipient email (for order confirmation)
 - Full shipping address (name, street, city, postal code, country)
 
+### Successful Purchase Response
+
+When a purchase completes successfully, you'll receive:
+- **Order ID** - Use with `crossmint_order_status` to track delivery
+- **Transaction Explorer Link** - Solana explorer URL to verify the payment on-chain
+- **Payment Status** - Confirms payment was processed
+- **Product Details** - Title and price of the purchased item
+
+Example response:
+```
+✅ Purchase complete!
+
+Product: AmazonBasics USB Cable
+Price: 0.05 SOL
+Order ID: order_abc123
+Payment: completed
+
+Transaction: https://explorer.solana.com/tx/5x...?cluster=devnet
+
+Shipping to:
+John Doe
+123 Main St
+New York, NY 10001
+US
+
+Use crossmint_order_status to check delivery status.
+```
+
 ### Check order status
 
 ```
@@ -131,18 +172,27 @@ User: "What's the status of my order?"
 Agent: Use crossmint_order_status with the order ID
 ```
 
+Returns:
+- Order phase (quote, payment, delivery, completed)
+- Payment status
+- Delivery status
+- Tracking information (when available)
+
 ### Amazon Product Locator Formats
 
-- ASIN: `B00O79SKV6`
+All of these formats work:
+- ASIN only: `B00O79SKV6`
 - Full URL: `https://www.amazon.com/dp/B00O79SKV6`
+- With amazon: prefix: `amazon: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 requires special shipping (hazmat, oversized)
+- Item is digital (ebooks, software, music, etc.)
 - Item is from Amazon Fresh, Pantry, Pharmacy, or Subscribe & Save
+- Item is out of stock or unavailable for shipping to the address
 
 ## Tool Parameters
 
@@ -214,9 +264,9 @@ Orders may fail if:
   "addressLine1": "required - street address",
   "addressLine2": "optional - apt, suite, etc.",
   "city": "required",
-  "state": "optional - state/province code",
+  "state": "optional - state/province code (e.g., 'CA', 'NY')",
   "postalCode": "required",
-  "country": "required - e.g., 'US'",
+  "country": "required - ISO country code (e.g., 'US')",
   "currency": "optional - 'sol' or 'usdc' (default: 'usdc')",
   "agentId": "optional"
 }
@@ -248,27 +298,70 @@ 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
+2. Ask user to complete web setup at the URL
+3. Use crossmint_configure with the wallet address and API key from the web app
 ```
 
 ### "Failed to get balance" or "Failed to send"
 
-- Verify the API key is correct
-- Check wallet address matches the web app
+- Verify the API key is correct (should start with `ck_staging_` for devnet)
+- Check wallet address matches the one shown in the web app
 - Ensure sufficient balance for transfers
 
+### "Insufficient funds" (Amazon purchase)
+
+The wallet doesn't have enough SOL or USDC for the purchase.
+
+```
+Agent:
+1. Use crossmint_balance to check current balance
+2. Ask user to fund the wallet with more SOL/USDC
+3. For devnet testing, use Solana faucets to get test SOL
+```
+
+### "Order created but no serialized transaction returned"
+
+The order was created but payment couldn't be prepared. This usually means:
+- Product is unavailable or restricted
+- Shipping address is invalid
+- Price changed during checkout
+
+### "Timeout waiting for transaction to be broadcast"
+
+The transaction was signed but didn't confirm on-chain within 30 seconds.
+
+```
+Agent:
+1. Use crossmint_tx_status to check the transaction status
+2. If still pending, wait longer or retry
+3. Check Solana network status for congestion
+```
+
 ## Security Notes
 
 - Private keys are stored locally at `~/.openclaw/crossmint-wallets/`
-- Keys never leave the agent's machine
+- Keys never leave the agent's machine - only signatures are sent to Crossmint
 - Uses ed25519 cryptography (Solana native)
-- Users retain admin control and can revoke delegation anytime
+- Users retain admin control and can revoke delegation anytime via the Crossmint dashboard
 - Always verify recipient addresses before sending
+- The API key grants limited permissions - only what the user authorized during delegation
 
 ## 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
+1. **Always check balance before purchasing** - Avoid failed transactions due to insufficient funds
+2. **Confirm shipping address with user** - Double-check addresses for Amazon purchases
+3. **Get devnet tokens for testing** - Use Solana devnet faucets to get test SOL before trying purchases
+4. **One wallet per agent** - Each agent ID gets its own keypair and wallet
+5. **Save the order ID** - Users should note the order ID to track delivery status later
+6. **Verify on-chain** - The explorer link lets users verify the payment transaction on Solana
+
+## Supported Currencies
+
+For Amazon purchases:
+- **SOL** - Native Solana token
+- **USDC** - USD Coin stablecoin on Solana
+
+For transfers:
+- **SOL** - Native Solana token
+- **USDC** - USD Coin stablecoin
+- **Any SPL token** - Specify the token mint address

package/src/amazon-order.test.ts

@@ -0,0 +1,528 @@
+import { Keypair } from "@solana/web3.js";
+import bs58 from "bs58";
+import nacl from "tweetnacl";
+import { describe, it, expect } from "vitest";
+
+/**
+ * End-to-end test for Amazon order purchase via Crossmint.
+ *
+ * This test demonstrates the complete delegated signer flow:
+ * 1. Create an Amazon order via Crossmint API
+ * 2. Create a Crossmint transaction with the serialized transaction
+ * 3. Sign the approval message with the delegated signer
+ * 4. Submit the approval to Crossmint
+ * 5. Wait for transaction to be broadcast and get txId
+ * 6. Submit txId to /payment endpoint (CRITICAL STEP!)
+ * 7. Poll for order completion
+ *
+ * Run with:
+ *   CROSSMINT_API_KEY=your-key \
+ *   PAYER_ADDRESS=your-smart-wallet-address \
+ *   SIGNER_PRIVATE_KEY=your-delegated-signer-base58-private-key \
+ *   pnpm test src/amazon-order.test.ts
+ */
+
+// Configuration from environment
+const API_KEY = process.env.CROSSMINT_API_KEY || "";
+const PAYER_ADDRESS = process.env.PAYER_ADDRESS || ""; // Smart wallet address
+const SIGNER_PRIVATE_KEY = process.env.PAYER_PRIVATE_KEY || ""; // Delegated signer private key
+
+// Crossmint API base URLs (staging = devnet)
+const CROSSMINT_ORDERS_API = "https://staging.crossmint.com/api/2022-06-09";
+const CROSSMINT_WALLETS_API = "https://staging.crossmint.com/api/2025-06-09";
+
+// Test product - can be overridden via environment variable
+const TEST_AMAZON_ASIN = process.env.TEST_AMAZON_ASIN || "B00AATAHY0";
+
+// Skip tests if credentials not provided
+const LIVE = API_KEY && PAYER_ADDRESS && SIGNER_PRIVATE_KEY;
+
+/**
+ * Step 1: Create the Amazon Order
+ */
+async function createAmazonOrder(amazonASIN: string, payerAddress: string, currency: string = "sol") {
+  const response = await fetch(`${CROSSMINT_ORDERS_API}/orders`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-KEY": API_KEY,
+    },
+    body: JSON.stringify({
+      recipient: {
+        email: "buyer@example.com",
+        physicalAddress: {
+          name: "John Doe",
+          line1: "350 5th Ave",
+          line2: "Suite 400",
+          city: "New York",
+          state: "NY",
+          postalCode: "10118",
+          country: "US",
+        },
+      },
+      payment: {
+        method: "solana",
+        currency: currency,
+        payerAddress: payerAddress,
+        receiptEmail: "buyer@example.com",
+      },
+      lineItems: [
+        {
+          productLocator: `amazon:${amazonASIN}`,
+        },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to create order: ${error}`);
+  }
+
+  return await response.json();
+}
+
+/**
+ * Step 2: Create Crossmint transaction from serialized transaction
+ * Returns transactionId and message to sign
+ */
+async function createCrossmintTransaction(
+  payerAddress: string,
+  serializedTransaction: string,
+  signerAddress: string
+) {
+  const response = await fetch(
+    `${CROSSMINT_WALLETS_API}/wallets/${encodeURIComponent(payerAddress)}/transactions`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-KEY": API_KEY,
+      },
+      body: JSON.stringify({
+        params: {
+          transaction: serializedTransaction,
+          signer: `external-wallet:${signerAddress}`,
+        },
+      }),
+    }
+  );
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to create transaction: ${error}`);
+  }
+
+  return await response.json();
+}
+
+/**
+ * Step 3: Sign the approval message with delegated signer
+ */
+function signApprovalMessage(message: string, privateKeyBase58: string): string {
+  const secretKey = bs58.decode(privateKeyBase58);
+  const messageBytes = bs58.decode(message);
+  const signature = nacl.sign.detached(messageBytes, secretKey);
+  return bs58.encode(signature);
+}
+
+/**
+ * Step 4: Submit approval to Crossmint
+ */
+async function submitApproval(
+  payerAddress: string,
+  transactionId: string,
+  signerAddress: string,
+  signature: string
+) {
+  const response = await fetch(
+    `${CROSSMINT_WALLETS_API}/wallets/${encodeURIComponent(payerAddress)}/transactions/${encodeURIComponent(transactionId)}/approvals`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-KEY": API_KEY,
+      },
+      body: JSON.stringify({
+        approvals: [
+          {
+            signer: `external-wallet:${signerAddress}`,
+            signature: signature,
+          },
+        ],
+      }),
+    }
+  );
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to submit approval: ${error}`);
+  }
+
+  return await response.json();
+}
+
+/**
+ * Step 5: Get transaction status from Crossmint Wallets API
+ * Poll until we get the on-chain txId
+ */
+async function getTransactionStatus(payerAddress: string, transactionId: string) {
+  const response = await fetch(
+    `${CROSSMINT_WALLETS_API}/wallets/${encodeURIComponent(payerAddress)}/transactions/${encodeURIComponent(transactionId)}`,
+    {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-KEY": API_KEY,
+      },
+    }
+  );
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to get transaction status: ${error}`);
+  }
+
+  return await response.json();
+}
+
+/**
+ * Step 5b: Poll for transaction to be broadcast and get on-chain txId
+ */
+async function waitForTransactionBroadcast(
+  payerAddress: string,
+  transactionId: string,
+  timeoutMs: number = 30000
+): Promise<string | null> {
+  const startTime = Date.now();
+  
+  while (Date.now() - startTime < timeoutMs) {
+    const txStatus = await getTransactionStatus(payerAddress, transactionId);
+    console.log("Transaction status:", txStatus.status);
+    
+    // Check if transaction has been broadcast and we have the on-chain txId
+    if (txStatus.onChain?.txId) {
+      console.log("On-chain txId:", txStatus.onChain.txId);
+      return txStatus.onChain.txId;
+    }
+    
+    // Also check for txId directly on the response
+    if (txStatus.txId) {
+      console.log("txId from response:", txStatus.txId);
+      return txStatus.txId;
+    }
+
+    // Check if status indicates completion
+    if (txStatus.status === "success" || txStatus.status === "completed") {
+      // Try to find txId in various places
+      const txId = txStatus.onChain?.txId || txStatus.txId || txStatus.hash;
+      if (txId) {
+        return txId;
+      }
+    }
+
+    // Check for failure
+    if (txStatus.status === "failed") {
+      throw new Error(`Transaction failed: ${JSON.stringify(txStatus)}`);
+    }
+
+    // Wait before polling again
+    await new Promise(resolve => setTimeout(resolve, 2000));
+  }
+
+  console.log("Timeout waiting for transaction broadcast");
+  return null;
+}
+
+/**
+ * Step 6: Submit payment to Crossmint Orders API (CRITICAL!)
+ * This notifies Crossmint that the payment transaction has been submitted
+ */
+async function processPayment(orderId: string, txId: string, clientSecret?: string) {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-API-KEY": API_KEY,
+  };
+  if (clientSecret) {
+    headers["Authorization"] = clientSecret;
+  }
+
+  const response = await fetch(`${CROSSMINT_ORDERS_API}/orders/${orderId}/payment`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      type: "crypto-tx-id",
+      txId: txId,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to process payment: ${error}`);
+  }
+
+  return await response.json();
+}
+
+/**
+ * Step 7: Poll for Order Completion
+ */
+async function pollOrderStatus(
+  orderId: string,
+  clientSecret: string,
+  timeoutMs: number = 60000
+): Promise<{ paymentStatus: string; deliveryStatus: string }> {
+  return new Promise((resolve) => {
+    const intervalId = setInterval(async () => {
+      try {
+        const response = await fetch(`${CROSSMINT_ORDERS_API}/orders/${orderId}`, {
+          method: "GET",
+          headers: {
+            "Content-Type": "application/json",
+            "X-API-KEY": API_KEY,
+            Authorization: clientSecret,
+          },
+        });
+
+        if (!response.ok) {
+          console.log("Failed to get order status:", await response.text());
+          return;
+        }
+
+        const orderStatus = await response.json();
+        const paymentStatus = orderStatus.payment?.status || "unknown";
+        const deliveryStatus = orderStatus.lineItems?.[0]?.delivery?.status || "pending";
+
+        console.log("Payment:", paymentStatus);
+        console.log("Delivery:", deliveryStatus);
+
+        if (paymentStatus === "completed") {
+          clearInterval(intervalId);
+          console.log("Payment completed! Amazon order is being fulfilled.");
+          resolve({ paymentStatus, deliveryStatus });
+        }
+      } catch (error) {
+        console.error("Error polling order status:", error);
+      }
+    }, 2500);
+
+    setTimeout(() => {
+      clearInterval(intervalId);
+      console.log("Timeout - check order manually");
+      resolve({ paymentStatus: "timeout", deliveryStatus: "unknown" });
+    }, timeoutMs);
+  });
+}
+
+/**
+ * Get order status (single call)
+ */
+async function getOrderStatus(orderId: string, clientSecret?: string) {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-API-KEY": API_KEY,
+  };
+  if (clientSecret) {
+    headers["Authorization"] = clientSecret;
+  }
+
+  const response = await fetch(`${CROSSMINT_ORDERS_API}/orders/${orderId}`, {
+    method: "GET",
+    headers,
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to get order: ${error}`);
+  }
+
+  return await response.json();
+}
+
+/**
+ * Get signer public key from private key
+ */
+function getSignerAddress(privateKeyBase58: string): string {
+  const secretKey = bs58.decode(privateKeyBase58);
+  const keypair = Keypair.fromSecretKey(secretKey);
+  return keypair.publicKey.toBase58();
+}
+
+describe("Amazon Order E2E Test", () => {
+  describe.skipIf(!LIVE)("live: delegated signer purchase flow", () => {
+    it("creates order and pays with delegated signer approval", async () => {
+      const signerAddress = getSignerAddress(SIGNER_PRIVATE_KEY);
+
+      console.log("\n=== Starting Amazon Order E2E Test (Delegated Signer Flow) ===\n");
+      console.log("Smart Wallet (Payer):", PAYER_ADDRESS);
+      console.log("Delegated Signer:", signerAddress);
+      console.log("Amazon ASIN:", TEST_AMAZON_ASIN);
+
+      // Step 1: Create the order
+      console.log("\n--- Step 1: Creating Amazon order ---");
+      const { order, clientSecret } = await createAmazonOrder(
+        TEST_AMAZON_ASIN,
+        PAYER_ADDRESS,
+        "sol"
+      );
+
+      console.log("Order ID:", order.orderId);
+      console.log("Order Phase:", order.phase);
+      console.log("Client Secret:", clientSecret ? "✓ received" : "✗ missing");
+
+      expect(order.orderId).toBeDefined();
+      expect(order.phase).toBeDefined();
+
+      // Check if we have a serialized transaction
+      const serializedTransaction = order.payment?.preparation?.serializedTransaction;
+      console.log(
+        "Serialized Transaction:",
+        serializedTransaction ? `✓ received (${serializedTransaction.length} chars)` : "✗ missing"
+      );
+
+      if (!serializedTransaction) {
+        console.log("\nOrder created but no serialized transaction returned.");
+        console.log("Full order response:", JSON.stringify(order, null, 2));
+        return;
+      }
+
+      // Check for insufficient funds
+      if (order.payment?.failureReason?.code === "insufficient-funds") {
+        console.log("\n⚠️ Insufficient funds:", order.payment.failureReason.message);
+        console.log("Please fund the wallet and try again.");
+        return;
+      }
+
+      // Step 2: Create Crossmint transaction
+      console.log("\n--- Step 2: Creating Crossmint transaction ---");
+      const txResponse = await createCrossmintTransaction(
+        PAYER_ADDRESS,
+        serializedTransaction,
+        signerAddress
+      );
+
+      console.log("Transaction ID:", txResponse.id);
+      console.log("Transaction Status:", txResponse.status);
+
+      const messageToSign = txResponse.approvals?.pending?.[0]?.message;
+      console.log("Message to sign:", messageToSign ? `✓ received (${messageToSign.length} chars)` : "✗ missing");
+
+      if (!messageToSign) {
+        console.log("\nNo message to sign. Transaction response:", JSON.stringify(txResponse, null, 2));
+        return;
+      }
+
+      // Step 3: Sign the approval message
+      console.log("\n--- Step 3: Signing approval message ---");
+      const signature = signApprovalMessage(messageToSign, SIGNER_PRIVATE_KEY);
+      console.log("Signature:", `✓ generated (${signature.length} chars)`);
+
+      // Step 4: Submit approval
+      console.log("\n--- Step 4: Submitting approval to Crossmint ---");
+      const approvalResponse = await submitApproval(
+        PAYER_ADDRESS,
+        txResponse.id,
+        signerAddress,
+        signature
+      );
+
+      console.log("Approval Response:", JSON.stringify(approvalResponse, null, 2));
+
+      // Step 5: Wait for transaction to be broadcast and get on-chain txId
+      console.log("\n--- Step 5: Waiting for transaction broadcast ---");
+      const onChainTxId = await waitForTransactionBroadcast(PAYER_ADDRESS, txResponse.id, 30000);
+
+      if (!onChainTxId) {
+        console.log("Could not get on-chain txId. Checking approval response for txId...");
+        // Try to get txId from approval response
+        const fallbackTxId = approvalResponse.onChain?.txId || approvalResponse.txId || approvalResponse.hash;
+        if (!fallbackTxId) {
+          console.log("No txId available. Cannot call /payment endpoint.");
+          console.log("Full approval response:", JSON.stringify(approvalResponse, null, 2));
+          return;
+        }
+      }
+
+      const txIdToSubmit = onChainTxId || approvalResponse.onChain?.txId || approvalResponse.txId;
+
+      // Step 6: Submit payment to Crossmint (CRITICAL!)
+      console.log("\n--- Step 6: Submitting payment to Crossmint /payment endpoint ---");
+      console.log("Submitting txId:", txIdToSubmit);
+      
+      const paymentResponse = await processPayment(order.orderId, txIdToSubmit!, clientSecret);
+      console.log("Payment Response:", JSON.stringify(paymentResponse, null, 2));
+
+      // Step 7: Poll for order completion
+      console.log("\n--- Step 7: Polling for order completion ---");
+      const { paymentStatus, deliveryStatus } = await pollOrderStatus(
+        order.orderId,
+        clientSecret,
+        60000
+      );
+
+      console.log("\n=== Final Status ===");
+      console.log("Payment Status:", paymentStatus);
+      console.log("Delivery Status:", deliveryStatus);
+
+      // Payment should eventually complete
+      expect(["completed", "timeout", "crypto-payer-insufficient-funds"]).toContain(paymentStatus);
+    }, 180000); // 3 minute timeout
+
+    it("creates order only (inspect response)", async () => {
+      console.log("\n=== Create Order Only Test ===\n");
+
+      const { order, clientSecret } = await createAmazonOrder(
+        TEST_AMAZON_ASIN,
+        PAYER_ADDRESS,
+        "sol"
+      );
+
+      console.log("Order ID:", order.orderId);
+      console.log("Order Phase:", order.phase);
+      console.log("Quote:", JSON.stringify(order.quote, null, 2));
+      console.log("Payment:", JSON.stringify(order.payment, null, 2));
+
+      expect(order.orderId).toBeDefined();
+
+      console.log("\n--- Full Response ---");
+      console.log(JSON.stringify({ order, clientSecret }, null, 2));
+    }, 30000);
+  });
+
+  describe("unit tests", () => {
+    it("validates keypair creation from base58", () => {
+      const testKeypair = Keypair.generate();
+      const secretKeyBase58 = bs58.encode(testKeypair.secretKey);
+      const recreatedKeypair = Keypair.fromSecretKey(bs58.decode(secretKeyBase58));
+      expect(recreatedKeypair.publicKey.toBase58()).toBe(testKeypair.publicKey.toBase58());
+    });
+
+    it("validates signature generation", () => {
+      const testKeypair = Keypair.generate();
+      const secretKeyBase58 = bs58.encode(testKeypair.secretKey);
+      const testMessage = bs58.encode(Buffer.from("test message"));
+
+      const signature = signApprovalMessage(testMessage, secretKeyBase58);
+      expect(signature).toBeDefined();
+      expect(signature.length).toBeGreaterThan(0);
+
+      // Verify signature
+      const sigBytes = bs58.decode(signature);
+      const msgBytes = bs58.decode(testMessage);
+      const isValid = nacl.sign.detached.verify(msgBytes, sigBytes, testKeypair.publicKey.toBytes());
+      expect(isValid).toBe(true);
+    });
+  });
+});
+
+export {
+  createAmazonOrder,
+  createCrossmintTransaction,
+  signApprovalMessage,
+  submitApproval,
+  waitForTransactionBroadcast,
+  processPayment,
+  pollOrderStatus,
+  getOrderStatus,
+  getTransactionStatus,
+};

package/src/api.ts

@@ -17,6 +17,7 @@ export type CrossmintTransaction = {
   id: string;
   status: string;
   hash?: string;
+  txId?: string; // Top-level txId from API response
   explorerLink?: string;
   onChain?: {
     status?: string;
@@ -109,6 +110,7 @@ export async function getTransactionStatus(
     id: data.id,
     status: data.status,
     hash: data.onChain?.txId || data.hash,
+    txId: data.txId, // Top-level txId from API response
     explorerLink: data.onChain?.txId
       ? `https://explorer.solana.com/tx/${data.onChain.txId}?cluster=devnet`
       : undefined,
@@ -319,14 +321,19 @@ export type TransactionResponse = {
 // Headless Checkout API Functions (Delegated Signer Flow)
 // ============================================================================
 
+export type CreateOrderResponse = {
+  order: CrossmintOrder;
+  clientSecret: string;
+};
+
 /**
  * Step 1: Create an order for purchasing products (e.g., from Amazon)
- * Returns order with serializedTransaction to use in step 2
+ * Returns order with serializedTransaction and clientSecret for subsequent API calls
  */
 export async function createOrder(
   config: CrossmintApiConfig,
   request: CreateOrderRequest,
-): Promise<CrossmintOrder> {
+): Promise<CreateOrderResponse> {
   const response = await fetchCrossmint(config, "/2022-06-09/orders", {
     method: "POST",
     body: JSON.stringify(request),
@@ -337,9 +344,12 @@ export async function createOrder(
     throw new Error(`Failed to create order: ${error}`);
   }
 
-  // API returns { clientSecret, order } - extract the order
+  // API returns { clientSecret, order }
   const data = await response.json();
-  return data.order;
+  return {
+    order: data.order,
+    clientSecret: data.clientSecret,
+  };
 }
 
 /**
@@ -414,11 +424,17 @@ export async function submitApproval(
 export async function getOrder(
   config: CrossmintApiConfig,
   orderId: string,
+  clientSecret?: string,
 ): Promise<CrossmintOrder> {
+  const headers: Record<string, string> = {};
+  if (clientSecret) {
+    headers["Authorization"] = clientSecret;
+  }
+
   const response = await fetchCrossmint(
     config,
     `/2022-06-09/orders/${encodeURIComponent(orderId)}`,
-    { method: "GET" },
+    { method: "GET", headers },
   );
 
   if (!response.ok) {
@@ -429,20 +445,124 @@ export async function getOrder(
   return response.json();
 }
 
+/**
+ * Step 5: Wait for transaction to be broadcast and get on-chain txId
+ * Polls the transaction status until we get the on-chain transaction ID
+ */
+export async function waitForTransactionBroadcast(
+  config: CrossmintApiConfig,
+  walletAddress: string,
+  transactionId: string,
+  timeoutMs: number = 30000,
+  pollIntervalMs: number = 2000,
+): Promise<string | null> {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeoutMs) {
+    const txStatus = await getTransactionStatus(config, walletAddress, transactionId);
+
+    // Check if transaction has been broadcast and we have the on-chain txId
+    if (txStatus.onChain?.txId) {
+      return txStatus.onChain.txId;
+    }
+
+    // Also check for txId directly on the response
+    if (txStatus.txId) {
+      return txStatus.txId;
+    }
+
+    // Check if status indicates completion
+    if (txStatus.status === "success" || txStatus.status === "completed") {
+      // Try to find txId in various places
+      const txId = txStatus.onChain?.txId || txStatus.txId || txStatus.hash;
+      if (txId) {
+        return txId;
+      }
+    }
+
+    // Check for failure
+    if (txStatus.status === "failed") {
+      throw new Error(`Transaction failed: ${JSON.stringify(txStatus)}`);
+    }
+
+    // Wait before polling again
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+
+  return null;
+}
+
+/**
+ * Step 6: Submit payment confirmation to Crossmint Orders API (CRITICAL!)
+ * This notifies Crossmint that the payment transaction has been submitted on-chain
+ */
+export async function submitPaymentConfirmation(
+  config: CrossmintApiConfig,
+  orderId: string,
+  onChainTxId: string,
+  clientSecret?: string,
+): Promise<CrossmintOrder> {
+  const headers: Record<string, string> = {};
+  if (clientSecret) {
+    headers["Authorization"] = clientSecret;
+  }
+
+  const response = await fetchCrossmint(
+    config,
+    `/2022-06-09/orders/${encodeURIComponent(orderId)}/payment`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        type: "crypto-tx-id",
+        txId: onChainTxId,
+      }),
+    },
+  );
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to submit payment confirmation: ${error}`);
+  }
+
+  return response.json();
+}
+
+export type PurchaseResult = {
+  order: CrossmintOrder;
+  transactionId: string;
+  onChainTxId: string;
+  explorerLink: string;
+};
+
 /**
  * Complete Amazon purchase flow with delegated signer
- * Combines all 3 API calls + local signing
+ *
+ * Steps:
+ * 1. Create order → returns serializedTransaction and clientSecret
+ * 2a. Create Crossmint transaction with serialized tx
+ * 2b. Sign the approval message locally with ed25519
+ * 2c. Submit approval to Crossmint
+ * 5. Wait for transaction to be broadcast → get on-chain txId
+ * 6. Submit txId to /payment endpoint (CRITICAL!)
+ *
+ * Returns the final order state after payment confirmation.
  */
 export async function purchaseProduct(
   config: CrossmintApiConfig,
   request: CreateOrderRequest,
   keypair: Keypair,
-): Promise<{ order: CrossmintOrder; transactionId: string }> {
+): Promise<PurchaseResult> {
   // Step 1: Create order
-  const order = await createOrder(config, request);
+  const { order, clientSecret } = await createOrder(config, request);
 
   const serializedTransaction = order.payment?.preparation?.serializedTransaction;
   if (!serializedTransaction) {
+    // Check for insufficient funds
+    const failureReason = (order.payment as { failureReason?: { code: string; message: string } })?.failureReason;
+    if (failureReason?.code === "insufficient-funds") {
+      throw new Error(`Insufficient funds: ${failureReason.message}`);
+    }
     throw new Error(
       `Order created but no serialized transaction returned. Payment status: ${order.payment?.status || "unknown"}`,
     );
@@ -461,14 +581,14 @@ export async function purchaseProduct(
     throw new Error("Transaction created but no message to sign");
   }
 
-  // Step 2 (local): Sign the message with ed25519
-  // Message is base58 encoded (Solana standard) - same as transfers
+  // Step 2b (local): Sign the message with ed25519
+  // Message is base58 encoded (Solana standard)
   const messageBytes = bs58.decode(messageToSign);
   const nacl = (await import("tweetnacl")).default;
   const signature = nacl.sign.detached(messageBytes, keypair.secretKey);
   const signatureBase58 = bs58.encode(signature);
 
-  // Step 2b: Submit approval
+  // Step 2c: Submit approval
   await submitApproval(
     config,
     request.payment.payerAddress,
@@ -477,7 +597,37 @@ export async function purchaseProduct(
     signatureBase58,
   );
 
-  return { order, transactionId: txResponse.id };
+  // Step 5: Wait for transaction to be broadcast and get on-chain txId
+  const onChainTxId = await waitForTransactionBroadcast(
+    config,
+    request.payment.payerAddress,
+    txResponse.id,
+    30000, // 30 second timeout
+  );
+
+  if (!onChainTxId) {
+    throw new Error("Timeout waiting for transaction to be broadcast on-chain");
+  }
+
+  // Step 6: Submit payment confirmation (CRITICAL!)
+  const updatedOrder = await submitPaymentConfirmation(
+    config,
+    order.orderId,
+    onChainTxId,
+    clientSecret,
+  );
+
+  const explorerLink =
+    config.environment === "staging"
+      ? `https://explorer.solana.com/tx/${onChainTxId}?cluster=devnet`
+      : `https://explorer.solana.com/tx/${onChainTxId}`;
+
+  return {
+    order: updatedOrder,
+    transactionId: txResponse.id,
+    onChainTxId,
+    explorerLink,
+  };
 }
 
 /**

package/src/tools.ts

@@ -675,18 +675,22 @@ export function createCrossmintBuyTool(_api: OpenClawPluginApi, _config: Crossmi
         const productTitle = result.order.lineItems?.[0]?.metadata?.title || "Product";
         const totalPrice = result.order.quote?.totalPrice;
         const priceText = totalPrice ? `${totalPrice.amount} ${totalPrice.currency}` : "See order details";
+        const paymentStatus = result.order.payment?.status || result.order.phase;
 
         return {
           content: [
             {
               type: "text",
-              text: `Purchase initiated!\n\nProduct: ${productTitle}\nPrice: ${priceText}\nOrder ID: ${result.order.orderId}\nStatus: ${result.order.phase}\n\nShipping to:\n${recipientName}\n${addressLine1}${addressLine2 ? `\n${addressLine2}` : ""}\n${city}${state ? `, ${state}` : ""} ${postalCode}\n${country}\n\nUse crossmint_order_status to check delivery status.`,
+              text: `✅ Purchase complete!\n\nProduct: ${productTitle}\nPrice: ${priceText}\nOrder ID: ${result.order.orderId}\nPayment: ${paymentStatus}\n\nTransaction: ${result.explorerLink}\n\nShipping to:\n${recipientName}\n${addressLine1}${addressLine2 ? `\n${addressLine2}` : ""}\n${city}${state ? `, ${state}` : ""} ${postalCode}\n${country}\n\nUse crossmint_order_status to check delivery status.`,
             },
           ],
           details: {
             orderId: result.order.orderId,
             transactionId: result.transactionId,
+            onChainTxId: result.onChainTxId,
+            explorerLink: result.explorerLink,
             phase: result.order.phase,
+            paymentStatus,
             productLocator,
             totalPrice,
             recipient: orderRequest.recipient,