@loomlay/openclaw-wallet-plugin

OpenClaw Wallet SDK plugin for AI agents - provides 27 native tools for multi-chain wallet management, trading, and DEX data.

Features

• Zero Config - Auto-registers and saves API key on first use
• 27 Native Tools - Wallet, trading, DEX data, token launch, and more
• Multi-Chain Support - Solana, Ethereum, Base, Arbitrum, Optimism, Polygon, BSC
• Flexible Amounts - Supports "1.5", "$100", "50%", "max"
• Standardized Responses - Consistent { success, data, error } format
• TypeScript First - Full type definitions for all tools

Zero Configuration

The plugin automatically handles API key management:

1. First use: Automatically registers for an API key and saves it to ~/.loomlay/credentials.json
2. Subsequent uses: Loads the saved API key automatically

No environment variables required for basic usage. Just install and use.

// On first call, auto-registers and saves credentials
const wallet = await wallet_create();
// API key automatically saved to ~/.loomlay/credentials.json

// Subsequent calls use the saved key
const balance = await wallet_get();

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)

Integration Options

ClawHub (Recommended for AI Agents)

Install directly via ClawHub for seamless agent integration:

clawhub install loomlay/openclaw-wallet

This installs the skill and makes all 27 tools available to your agent automatically.

NPM (For Programmatic Use)

Install via npm for programmatic access in your own applications:

npm install @loomlay/openclaw-wallet-plugin

Configuration

Zero Config (Recommended)

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

1. Registers for a new API key
2. Saves the key to ~/.loomlay/credentials.json
3. Uses the saved key for all subsequent requests

Environment Variable (Optional)

Override auto-registration by setting an environment variable:

export LOOMLAY_API_KEY=agent_your_key_here

Programmatic Configuration (Optional)

import { initPlugin, initPluginAsync } from '@loomlay/openclaw-wallet-plugin';

// Sync: Uses existing key from env/config/stored credentials
initPlugin({
  apiKey: 'agent_your_key_here',  // Optional if LOOMLAY_API_KEY set
  baseUrl: 'https://api.loomlay.com' // Optional
});

// Async: Supports auto-registration
const { client, registration } = await initPluginAsync({
  autoRegister: true // Default: true
});

if (registration) {
  console.log('New account created:', registration.apiKey);
  console.log('Saved to:', registration.savedTo);
}

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 (27)

Wallet (3 tools)

| Tool | Description | |------|-------------| | wallet_create | Create a new multi-chain wallet with BIP39 seed phrase | | wallet_get | Get wallet addresses and balances | | wallet_export_keys | Export private keys (requires seed phrase) |

Trading (5 tools)

| Tool | Description | |------|-------------| | swap | Execute a token swap | | swap_quote | Get a swap quote without executing | | transfer | Transfer tokens to an address | | bridge | Bridge tokens between chains | | bridge_quote | Get a bridge quote |

Tokens (4 tools)

| Tool | Description | |------|-------------| | token_search | Search tokens by name/symbol/address | | token_price | Get current USD price | | token_details | Get detailed token information | | token_chart | Get OHLCV chart data |

Portfolio (2 tools)

| Tool | Description | |------|-------------| | portfolio_get | Get combined portfolio across chains | | portfolio_history | Get transaction history |

DEX (7 tools)

| Tool | Description | |------|-------------| | dex_trending | Get trending trading pairs | | dex_volume | Get top volume pairs | | dex_gainers | Get top price gainers | | dex_losers | Get top price losers | | dex_new | Get newly created pairs | | dex_pumpfun | Get Pumpfun trending (Solana) | | dex_query | Advanced query with custom filters |

Tokenize (2 tools)

| Tool | Description | |------|-------------| | tokenize_launch | Launch a new token | | tokenize_info | Get your launched token info |

Fees (2 tools)

| Tool | Description | |------|-------------| | fees_status | Get fee status for your token | | fees_claim | Claim accumulated trading fees |

RPC (2 tools)

| Tool | Description | |------|-------------| | rpc_call | Direct RPC call to any chain | | rpc_chains | Get list of supported chains |

Usage Examples

Direct Function Calls

import {
  wallet_create,
  wallet_get,
  swap,
  swap_quote,
  dex_trending
} from '@loomlay/openclaw-wallet-plugin';

// Create wallet
const wallet = await wallet_create();
if (wallet.success) {
  console.log('Address:', wallet.data.wallet.solanaAddress);
  console.log('Seed phrase:', wallet.data.seedPhrase);
}

// Check balance
const balance = await wallet_get();
if (balance.success) {
  console.log('SOL:', balance.data.balances.solana.sol);
}

// Get swap quote
const quote = await swap_quote({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '$100'
});
if (quote.success) {
  console.log('Output:', quote.data.outputAmount);
}

// Execute swap
const result = await swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '1.5'
});

// Get trending
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
  }
}

Error Handling

import { swap, RateLimitError, ApiError } from '@loomlay/openclaw-wallet-plugin';

const result = await swap({
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '1'
});

if (!result.success) {
  switch (result.error?.code) {
    case 'RATE_LIMITED':
      console.log(`Wait ${result.error.retryAfter}s`);
      break;
    case 'BAD_REQUEST':
      console.log('Invalid parameters:', result.error.message);
      break;
    case 'UNAUTHORIZED':
      console.log('Check API key');
      break;
    default:
      console.log('Error:', result.error?.message);
  }
}

Skill Integration

The plugin includes a skill file for AI agent training:

import skillContent from '@loomlay/openclaw-wallet-plugin/skill';
// Or read from: node_modules/@loomlay/openclaw-wallet-plugin/skill/SKILL.md

The skill teaches agents:

• Wallet security best practices
• Quote-before-trade workflow
• Error handling patterns
• Chain-specific behaviors

Amount Formats

Trading tools accept flexible amounts:

| Format | Example | Description | |--------|---------|-------------| | Decimal | "1.5" | Exact token amount | | USD | "$100" | Dollar value | | Percentage | "50%" | Percentage of balance | | Max | "max" | Entire balance |

Supported Chains

| Chain | Swaps | Bridges | RPC | |-------|-------|---------|-----| | Solana | ✅ | ✅ | ✅ | | Ethereum | ✅ | ✅ | ✅ | | Base | ✅ | ✅ | ✅ | | Arbitrum | ✅ | ✅ | ✅ | | Optimism | ✅ | ✅ | ✅ | | Polygon | ✅ | ✅ | ✅ | | BSC | ✅ | ✅ | ✅ |

Plugin Manifest

The openclaw.plugin.json file describes all tools for plugin systems:

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

Security Notes

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

License

MIT