Getting Started

This guide walks you through setting up the OpenClawWallet SDK or OpenClaw Plugin.

Prerequisites

Before you begin, ensure you have:

  • Node.js 18+ or Bun 1.0+
  • A package manager: npm, yarn, pnpm, or bun
  • A server-side environment (the SDK is not designed for browser use)

Installation

npm install @loomlay/openclaw-wallet-sdk

Quick Start (Auto-Registration)

The easiest way to get started is with automatic registration:

import { OpenClawWallet } from '@loomlay/openclaw-wallet-sdk';
 
// Auto-register if no key found, saves to ~/.loomlay/credentials.json
const { client, registration } = await OpenClawWallet.create({ autoRegister: true });
 
if (registration) {
  console.log('New account created!');
  console.log('API Key:', registration.apiKey);
  console.log('Saved to:', registration.savedTo);
}
 
// Use the client
const wallet = await client.wallet.create();

The create() method checks for API keys in this order:

  1. apiKey option (if provided)
  2. LOOMLAY_API_KEY environment variable
  3. Stored credentials (~/.loomlay/credentials.json)
  4. Auto-register (if autoRegister: true)

Manual Registration

If you prefer to register manually:

import { OpenClawWallet } from '@loomlay/openclaw-wallet-sdk';
 
// This is rate-limited to 1 per IP
const result = await OpenClawWallet.register();
 
console.log('API Key:', result.apiKey);
// Save this key securely!

Save your API key immediately - it's only shown once during registration.

Registration Failed (409)?

If your IP already has an account:

  1. Check stored credentials - cat ~/.loomlay/credentials.json
  2. Set environment variable - export LOOMLAY_API_KEY=agent_your_key
  3. Contact support - support@loomlay.io for key recovery

Initialize the Client

Option 1: With auto-registration (recommended)

const { client } = await OpenClawWallet.create({ autoRegister: true });

Option 2: With self-custody mode

const wallet = new OpenClawWallet({
  apiKey: process.env.LOOMLAY_API_KEY!,
  walletMode: 'local',
  getPassphrase: async () => process.env.LOOMLAY_WALLET_PASSPHRASE!,
});

In self-custody mode, private keys are generated and stored locally on your device. The API only receives public addresses. See Wallet Management for details.

Option 3: With environment variable (custodial)

const wallet = new OpenClawWallet({
  apiKey: process.env.LOOMLAY_API_KEY!,
});

Option 4: With explicit key

const wallet = new OpenClawWallet({
  apiKey: 'agent_your_key_here',
});

Create Your First Wallet

// Create a new wallet
const created = await wallet.wallet.create();
 
console.log('Seed phrase:', created.seedPhrase);
console.log('Solana:', created.solanaAddress);
console.log('EVM:', created.evmAddress);
 
// Save the seed phrase securely!

Check Balances

const info = await wallet.wallet.get();
 
console.log('Solana balance:', info.balances.solana.native, 'SOL');
console.log('Ethereum balance:', info.balances.ethereum.native, 'ETH');

Make Your First Swap

import { InsufficientFundsError, RateLimitError } from '@loomlay/openclaw-wallet-sdk';
 
try {
  // Swap 1 SOL for USDC
  const swap = await wallet.trading.swap({
    inputToken: 'SOL',
    outputToken: 'USDC',
    amount: '1',
  });
 
  console.log('Swapped for:', swap.outputAmount, 'USDC');
  console.log('Transaction:', swap.txHash);
} catch (error) {
  if (error instanceof InsufficientFundsError) {
    console.error('Not enough funds:', error.message);
    console.error('Required:', error.required, '| Available:', error.available);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry in', error.retryAfter, 'seconds');
  } else {
    throw error;
  }
}

Environment Variables

We recommend storing your API key in environment variables:

# .env
LOOMLAY_API_KEY=agent_your_key_here
// Load from environment
const wallet = new OpenClawWallet({
  apiKey: process.env.LOOMLAY_API_KEY!,
});

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import type {
  SwapParams,
  SwapResult,
  WalletInfo
} from '@loomlay/openclaw-wallet-sdk';
 
const params: SwapParams = {
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: '1.5',
  slippage: 0.5,
};
 
const result: SwapResult = await wallet.trading.swap(params);

Next Steps