OpenClaw Wallet Plugin

Multi-chain wallet and trading toolkit for AI agents with 27 tools.

Installation

You must install the npm package before using any tools:

npm install @loomlay/openclaw-wallet-plugin

This installs the plugin and all its dependencies. No additional packages needed.

Authentication is automatic. On first use, the plugin auto-registers for an API key and saves it to ~/.loomlay/credentials.json. No manual setup required.

To use a specific API key instead of auto-registration:

export LOOMLAY_API_KEY=agent_your_key_here

First-Time Setup

IMPORTANT: After installing the plugin, you must set up a wallet before using trading/wallet tools.

On first interaction with a user (or when the skill is first loaded), run this setup sequence:

const { wallet_get, wallet_create } = require('@loomlay/openclaw-wallet-plugin');

// 1. Check if a wallet already exists
const existing = await wallet_get();

if (!existing.success) {
  // 2. No wallet yet — create one
  const created = await wallet_create();
  if (created.success) {
    // 3. Show the user their new wallet
    // IMPORTANT: The seed phrase is shown ONCE. Tell the user to save it.
    // "Your wallet has been created:"
    // "  Solana: <solanaAddress>"
    // "  EVM: <evmAddress>"
    // "  Seed phrase: <seedPhrase> (save this securely — it won't be shown again)"
  }
} else {
  // Wallet exists — show addresses
  // "Your wallet:"
  // "  Solana: <solanaAddress>"
  // "  SOL balance: <balance>"
}

Always run this check before any wallet or trading operation. If wallet_get() fails with UNAUTHORIZED, the API key may need to be re-registered — delete ~/.loomlay/credentials.json and retry.

How to Use the Tools

All 27 tools are exported as flat async functions from the plugin package. Use them in Node.js like this:

const { wallet_get, swap_quote, swap, dex_trending, token_search } = require('@loomlay/openclaw-wallet-plugin');

// Check wallet balance
const wallet = await wallet_get();
// wallet.data.balances.solana.sol

// Get trending tokens
const trending = await dex_trending({ chain: 'solana', limit: 10 });
// trending.data.pairs[...]

Every tool returns a standardized response:

{
  success: true,       // or false
  data: { ... },       // result data (when success is true)
  error: {             // error info (when success is false)
    message: "...",
    code: "RATE_LIMITED",
    retryAfter: 30     // seconds (for rate limits)
  }
}

Always check result.success before using result.data.

Important: Verify Before Executing

For any action involving funds:

1. Get a quote first — show the user what will happen
2. Get user confirmation — never execute without approval
3. Execute — run the transaction
4. Verify — check the result and new balances

const { swap_quote, swap } = require('@loomlay/openclaw-wallet-plugin');

// Step 1: Quote
const quote = await swap_quote({ inputToken: 'SOL', outputToken: 'USDC', amount: '$100' });
// Tell user: "You'll swap ~1.2 SOL for ~$99.50 USDC"

// Step 2: User confirms → Step 3: Execute
const result = await swap({ inputToken: 'SOL', outputToken: 'USDC', amount: '$100' });
if (result.success) {
  // Show txHash and new balance
}

Security Rules

• Never log seed phrases — wallet_create() returns it once, tell user to save it offline
• Never execute without user confirmation — always quote first
• Never guess token addresses — use token_search() to find them
• Never hardcode API keys — use environment variables

Amount Formats

Trading tools accept flexible amounts:

| Format | Example | Meaning |

|--------|---------|---------|

| Decimal | "1.5" | Exact token amount |

| USD | "$100" | Dollar value (auto-converts) |

| Percentage | "50%" | Half of balance |

| Max | "max" | Entire balance |

All 27 Tools Reference

Wallet (3)

const { wallet_create, wallet_get, wallet_export_keys } = require('@loomlay/openclaw-wallet-plugin');

// Create new wallet (returns seed phrase ONCE)
await wallet_create()
// → { wallet: { solanaAddress, evmAddress }, seedPhrase, message }

// Get wallet addresses and balances
await wallet_get()
// → { wallet: { solanaAddress, evmAddress }, balances: { solana, evm } }

// Export private keys (requires seed phrase)
await wallet_export_keys({ seedPhrase: '12 word phrase here' })
// → { solanaPrivateKey, evmPrivateKey }

Trading (5)

const { swap, swap_quote, transfer, bridge, bridge_quote } = require('@loomlay/openclaw-wallet-plugin');

// Swap tokens
await swap({ inputToken: 'SOL', outputToken: 'USDC', amount: '$100', chain: 'solana', slippage: 1 })
// → { success, txHash, inputAmount, outputAmount }

// Get swap quote (no execution)
await swap_quote({ inputToken: 'SOL', outputToken: 'USDC', amount: '$100' })
// → { inputAmount, outputAmount, minOutputAmount, priceImpact, route }

// Transfer tokens
await transfer({ token: 'SOL', amount: '1.5', to: 'recipient_address' })
// → { success, txHash, amount, token, to }

// Bridge cross-chain
await bridge({ inputToken: 'SOL', amount: '1', sourceChain: 'solana', destinationChain: 'base' })
// → { success, sourceTxHash, destinationTxHash, status }

// Bridge quote
await bridge_quote({ inputToken: 'SOL', amount: '1', sourceChain: 'solana', destinationChain: 'base' })
// → { inputAmount, outputAmount, fee, estimatedTime }

Tokens (4)

const { token_search, token_price, token_details, token_chart } = require('@loomlay/openclaw-wallet-plugin');

// Search tokens by name/symbol
await token_search({ query: 'BONK' })
// → { tokens: [{ address, symbol, name, price, safetyScore }] }

// Get token price
await token_price({ token: 'SOL', chain: 'solana' })
// → { token, price, chain }

// Get detailed token info
await token_details({ address: 'token_mint_address' })
// → { token, market, safety }

// Get OHLCV chart data
await token_chart({ address: 'token_mint_address' })
// → { data: [...] }

Portfolio (2)

const { portfolio_get, portfolio_history } = require('@loomlay/openclaw-wallet-plugin');

// Get combined portfolio across all chains
await portfolio_get()
// → { positions: [...], totalUsdValue: number }

// Get transaction history
await portfolio_history({ chain: 'solana', limit: 50 })
// → { transactions: [...] }

DEX Market Data (7)

const { dex_trending, dex_volume, dex_gainers, dex_losers, dex_new, dex_pumpfun, dex_query } = require('@loomlay/openclaw-wallet-plugin');

// Trending pairs
await dex_trending({ chain: 'solana', minLiquidity: 10000, limit: 10 })
// → { pairs: [...], pagination }

// Top volume pairs
await dex_volume({ chain: 'solana', minLiquidity: 10000, limit: 10 })

// Top gainers (24h)
await dex_gainers({ chain: 'solana', minLiquidity: 10000, limit: 10 })

// Top losers (24h)
await dex_losers({ chain: 'solana', minLiquidity: 10000, limit: 10 })

// Newly created pairs (< 24h)
await dex_new({ chain: 'solana', minLiquidity: 5000, limit: 10 })

// Pumpfun trending (Solana only)
await dex_pumpfun({ maxAge: 6, maxProgress: 80, limit: 10 })

// Advanced query with custom filters
await dex_query({
  chain: 'solana',
  timeframe: 'h24',
  rankBy: 'volume',
  order: 'desc',
  minSafetyScore: 80,
  limit: 10
})

Token Launch (2)

const { tokenize_launch, tokenize_info } = require('@loomlay/openclaw-wallet-plugin');

// Launch a token (one per account)
await tokenize_launch({
  name: 'My Token',
  symbol: 'MYT',
  tier: '100k',        // 10k, 100k, 1m, 10m
  imageUrl: 'https://...'
})
// → { success, launchId, tokenMint, poolAddress, dexscreenerUrl }

// Get your launched token info
await tokenize_info()
// → { hasToken, launchId, tokenMint, poolAddress, dexscreenerUrl }

Fees (2)

const { fees_status, fees_claim } = require('@loomlay/openclaw-wallet-plugin');

// Check fee status
await fees_status()
// → { totalFeesGeneratedSol, beneficiaryFeesUnclaimedSol, canClaim, feeForfeitsAt }

// Claim fees (platform pays gas)
await fees_claim()
// → { success, amountSol, txSignature }

RPC (2)

const { rpc_call, rpc_chains } = require('@loomlay/openclaw-wallet-plugin');

// Direct RPC call
await rpc_call({ chain: 'solana', method: 'getBalance', params: ['address'] })
// → { result, error }

// List supported chains
await rpc_chains()
// → { chains: [...] }

Supported Chains

| Chain | Swaps | Bridges | RPC |

|-------|-------|---------|-----|

| Solana | yes | yes | yes |

| Ethereum | yes | yes | yes |

| Base | yes | yes | yes |

| Arbitrum | yes | yes | yes |

| Optimism | yes | yes | yes |

| Polygon | yes | yes | yes |

| BSC | yes | yes | yes |

Error Handling

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

if (!result.success) {
  switch (result.error?.code) {
    case 'RATE_LIMITED':
      // Wait result.error.retryAfter seconds and retry
      break;
    case 'BAD_REQUEST':
      // Invalid parameters
      break;
    case 'UNAUTHORIZED':
      // API key issue — check LOOMLAY_API_KEY or ~/.loomlay/credentials.json
      break;
    case 'INSUFFICIENT_BALANCE':
      // Not enough funds
      break;
    default:
      // General error
      break;
  }
}

Reference Documents

• references/wallet-operations.md - Wallet creation, security, key export
• references/trading-guide.md - Swaps, transfers, bridges with amount formats
• references/market-analysis.md - DEX data, trending, filtering
• references/token-launch.md - Tokenize workflow, tiers, fee structure
• references/error-handling.md - Error types, recovery patterns, retries
• references/amount-formats.md - Flexible amounts explained
• references/chain-reference.md - Supported chains and behaviors

Workflows

• workflows/first-time-setup.md - Installation → wallet creation → first trade
• workflows/token-launch-playbook.md - Complete token launch guide