OpenClaw Plugin

The OpenClaw Plugin provides 29 native tools for multi-chain wallet management, trading, and market data directly within AI coding assistants like Claude Code. The plugin defaults to self-custody mode — private keys are generated and encrypted locally on your device, never sent to any server.

Architecture Overview

The OpenClaw ecosystem has a dual-layer architecture:

The SDK is designed for developers building applications. The Plugin wraps the SDK and exposes its functionality as discrete tools that AI agents can invoke directly.

Installation

npm install @loomlay/openclaw-wallet-plugin

Configuration

Zero Configuration (Recommended)

The plugin works out of the box with no configuration required. On first use, it automatically:

1. Registers for a new API key (saved to ~/.loomlay/credentials.json)
2. Generates wallet keys locally on your device
3. Encrypts keys with your passphrase (saved to ~/.loomlay/wallet.json)
4. Registers only public addresses with the API

import { wallet_create, wallet_unlock } from '@loomlay/openclaw-wallet-plugin';
 
// First use: auto-registers API key, creates local wallet
const wallet = await wallet_create();
// → Keys generated on YOUR device, encrypted with passphrase
// → Public addresses registered with API for balance lookups
 
// Unlock wallet for signing operations
await wallet_unlock({ passphrase: 'your-passphrase' });
 
// All trades sign locally — private key never sent to server

API Key Resolution Order

The plugin checks for API keys in this order:

1. LOOMLAY_API_KEY environment variable (highest priority)
2. Stored credentials (~/.loomlay/credentials.json)
3. Auto-register new account (if no key found)

Passphrase Resolution Order

For signing operations (swaps, transfers), the passphrase is resolved:

1. LOOMLAY_WALLET_PASSPHRASE environment variable (highest priority, recommended)
2. In-memory cache (set via wallet_unlock)
3. Error thrown with instructions

Environment Variables (Optional)

# Override auto-registration
export LOOMLAY_API_KEY=agent_your_key_here
 
# Set wallet passphrase (avoids passphrase appearing in conversation logs)
export LOOMLAY_WALLET_PASSPHRASE=your-secure-passphrase
 
# Optional: Custom API base URL
export LOOMLAY_BASE_URL=https://api.loomlay.com

Programmatic Configuration (Optional)

import { initPlugin, initPluginAsync } from '@loomlay/openclaw-wallet-plugin';
 
// Sync: Requires existing key from env or stored credentials
initPlugin({
  apiKey: 'agent_your_key_here',
  baseUrl: 'https://api.loomlay.com' // Optional
});
 
// Async: Supports auto-registration
const { client, registration } = await initPluginAsync();

Disable Auto-Registration

If you want to require explicit API key configuration:

import { initPluginAsync } from '@loomlay/openclaw-wallet-plugin';
 
// Throws error if no key found instead of auto-registering
const { client } = await initPluginAsync({ autoRegister: false });

Available Tools (29)

The plugin provides 29 tools organized into 8 categories:

Wallet (5 tools)

Trading (5 tools)

Tokens (4 tools)

Portfolio (2 tools)

DEX (7 tools)

Tokenize (2 tools)

Fees (2 tools)

RPC (2 tools)

Skill System

The plugin includes a skill file (SKILL.md) that teaches AI agents how to use the tools safely and effectively.

What the Skill Teaches

The skill provides guidance on:

1. Core Workflow - A structured approach: Authenticate, Understand, Validate, Execute, Verify, Document
2. Security Best Practices - Seed phrase handling, transaction safety, API key management
3. Quote-Before-Trade Pattern - Always get quotes and show expected outcomes before executing
4. Error Handling - Recovery patterns for rate limits, insufficient funds, and network errors
5. Chain-Specific Behaviors - Differences between Solana and EVM chains

Key Safety Principles

The skill enforces these safety principles for AI agents:

Security comes first. Wallets contain real value.
Every action involving funds should be deliberate,
verified, and explained to the user before execution.

Quality Gate Checklist:

• User explicitly requested this action
• Quote shown and confirmed for trades
• Address validated for transfers
• Sufficient balance confirmed
• Slippage/price impact acceptable
• Transaction hash provided after execution

Accessing the Skill

// Import from the package
import skillContent from '@loomlay/openclaw-wallet-plugin/skill';
 
// Or read the file directly
// node_modules/@loomlay/openclaw-wallet-plugin/skill/SKILL.md

Usage Example

Self-Custody Workflow

import {
  wallet_create,
  wallet_unlock,
  wallet_get,
  swap,
  swap_quote,
  dex_trending
} from '@loomlay/openclaw-wallet-plugin';
 
// 1. Create wallet (keys generated and encrypted locally)
const wallet = await wallet_create();
if (wallet.success) {
  console.log('Solana Address:', wallet.data.wallet.solanaAddress);
  console.log('EVM Address:', wallet.data.wallet.evmAddress);
  // IMPORTANT: Save the seed phrase securely - shown only once
  console.log('Seed Phrase:', wallet.data.seedPhrase);
}
 
// 2. Unlock wallet for signing (or set LOOMLAY_WALLET_PASSPHRASE env var)
await wallet_unlock({ passphrase: 'my-secure-passphrase' });
 
// Check balance
const balance = await wallet_get();
if (balance.success) {
  console.log('SOL Balance:', balance.data.balances.solana.sol);
}
 
// Get a quote before trading
const quote = await swap_quote({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '$100'
});
if (quote.success) {
  console.log('Expected Output:', quote.data.outputAmount, 'USDC');
  console.log('Price Impact:', quote.data.priceImpact, '%');
}
 
// Execute the swap after confirming the quote
const result = await swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '$100'
});
 
// Get trending tokens
const trending = await dex_trending({
  chain: 'solana',
  minLiquidity: 10000,
  limit: 20
});

Using the Tools Registry

import { tools } from '@loomlay/openclaw-wallet-plugin';
 
// Call tools by name
const wallet = await tools.wallet_get();
const trending = await tools.dex_trending({ chain: 'solana' });

Response Format

All tools return a standardized response:

interface ToolResponse<T> {
  success: boolean;
  data?: T;           // Present when success is true
  error?: {
    message: string;
    code?: string;
    retryAfter?: number;  // For rate limit errors
  };
}

Success Response

{
  success: true,
  data: {
    // Tool-specific data
  }
}

Error Response

{
  success: false,
  error: {
    message: "Rate limited",
    code: "RATE_LIMITED",
    retryAfter: 30
  }
}

Amount Formats

Trading tools accept flexible amount formats:

Supported Chains

Plugin Manifest

The openclaw.plugin.json file describes all tools in a machine-readable format:

{
  "name": "@loomlay/openclaw-wallet-plugin",
  "tools": [
    {
      "name": "swap",
      "description": "Execute a token swap...",
      "parameters": { ... },
      "returns": { ... }
    }
  ]
}

This manifest enables plugin systems and AI agents to discover and understand available tools programmatically.

Security Notes

Self-Custody Security

In self-custody mode (default), your keys are protected by:

• Local encryption: PBKDF2-SHA512 (600k iterations) + AES-256-GCM
• File permissions: ~/.loomlay/wallet.json with 0600 (owner read/write only)
• No key transmission: Private keys never sent to any server
• Transaction validation: Fee payer verified before signing
• Key zeroing: Private key buffers zeroed after signing

General

1. API Key - Store in environment variables, never hardcode
2. Seed Phrase - Returned once from wallet_create, store offline securely
3. Quotes First - Always get quotes before executing trades
4. Verify Addresses - Double-check recipient addresses for transfers
5. Check Price Impact - High price impact (>1%) indicates significant market movement

Related Pages

• SDK Overview - Full TypeScript SDK documentation
• Getting Started - SDK setup and first steps
• Trading - Detailed swap, transfer, and bridge documentation
• Market Data - DEX data and market analysis tools
• Error Handling - Error types and recovery patterns
• Rate Limits - API rate limit information