Elsa

elsa-openclaw

OpenClaw skill-pack for Elsa x402 DeFi API integration with micropayments.

This plugin enables OpenClaw agents to interact with the Elsa DeFi API using the x402 payment protocol for USDC micropayments on Base.

Security Posture

• Non-custodial: Private keys never leave your machine
• Local signing: All transactions are signed locally using viem
• Budget controls: Per-call and daily USD limits enforced before any paid API call
• Execution disabled by default: Onchain execution tools require explicit opt-in
• Confirmation tokens: Dry-run required before confirmed execution (optional but recommended)
• Separate wallets recommended: Use different keys for API payments vs. trade execution

Features

Read-Only Tools (Always Available)

• elsa_search_token - Search tokens across blockchains
• elsa_get_token_price - Get real-time token pricing
• elsa_get_balances - Get wallet token balances
• elsa_get_portfolio - Comprehensive portfolio analysis
• elsa_analyze_wallet - Wallet behavior and risk assessment
• elsa_get_swap_quote - Get swap quotes and routing
• elsa_execute_swap_dry_run - Simulate swap execution (no onchain action)
• elsa_budget_status - Check current budget usage

Execution Tools (Opt-In)

When ELSA_ENABLE_EXECUTION_TOOLS=true:

• elsa_execute_swap_confirmed - Execute swap with confirmation token
• elsa_pipeline_get_status - Check pipeline/transaction status
• elsa_pipeline_submit_tx_hash - Submit signed transaction hash
• elsa_pipeline_run_and_wait - Orchestrate full pipeline execution

Installation

1. Clone and install

git clone https://github.com/HeyElsa/elsa-openclaw.git
cd elsa-openclaw
npm install

2. Configure OpenClaw

Edit ~/.openclaw/openclaw.json:

{
  "skills": {
    "load": {
      "extraDirs": ["/path/to/elsa-openclaw"]
    },
    "entries": {
      "openclaw-elsa-x402": {
        "env": {
          "PAYMENT_PRIVATE_KEY": "0x_YOUR_WALLET_PRIVATE_KEY"
        }
      }
    }
  }
}

Minimal config - only PAYMENT_PRIVATE_KEY is required. All other settings have sensible defaults.

With execution enabled (for swaps):

{
  "skills": {
    "load": {
      "extraDirs": ["/path/to/elsa-openclaw"]
    },
    "entries": {
      "openclaw-elsa-x402": {
        "env": {
          "PAYMENT_PRIVATE_KEY": "0x...",
          "TRADE_PRIVATE_KEY": "0x...",
          "ELSA_ENABLE_EXECUTION_TOOLS": "true"
        }
      }
    }
  }
}

3. Fund your payment wallet

The payment wallet needs USDC on Base to pay for API calls (~$0.01-0.05 per call).

4. Restart OpenClaw

The skill will load automatically. Verify with /skills in chat.

Usage in OpenClaw

Once configured, just talk naturally:

Smoke Test

After installation, verify the setup:

# Search for a token
npx tsx scripts/index.ts elsa_search_token '{"query": "USDC", "limit": 3}'

# Get portfolio for a sample address
npx tsx scripts/index.ts elsa_get_portfolio '{"wallet_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'

# Check budget status
npx tsx scripts/index.ts elsa_budget_status '{}'

Field Mapping Note: This skill uses wallet_address in tool inputs, which maps internally to Elsa API's evm_address field.

Expected output includes:

• ok: true for successful calls
• billing: { estimated_cost_usd, ... } showing API cost
• meta: { latency_ms, ... } with request metadata

Enabling Execution Tools

WARNING: Execution tools perform real onchain transactions.

# Required for x402 API payments
PAYMENT_PRIVATE_KEY=0x...

# Required for signing swap transactions (falls back to PAYMENT_PRIVATE_KEY if not set)
TRADE_PRIVATE_KEY=0x...

# Enable execution tools
ELSA_ENABLE_EXECUTION_TOOLS=true

1. Set ELSA_ENABLE_EXECUTION_TOOLS=true
2. Ensure TRADE_PRIVATE_KEY has sufficient funds for gas and swaps
3. Recommended: Use separate wallets for payments vs. trading

Recommended Swap Flow

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────┐     ┌─────────────────────┐
│ 1. Get Quote        │ ──▶ │ 2. Dry Run          │ ──▶ │ 3. Confirm  │ ──▶ │ 4. Execute Pipeline │
│ elsa_get_swap_quote │     │ elsa_execute_swap_  │     │ [User says  │     │ elsa_pipeline_run_  │
│                     │     │ dry_run             │     │  "yes"]     │     │ and_wait            │
└─────────────────────┘     └─────────────────────┘     └─────────────┘     └─────────────────────┘

Step 1: Get Quote - Show user what they'll receive

npx tsx scripts/index.ts elsa_get_swap_quote '{
  "from_chain": "base", "from_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "from_amount": "10", "to_chain": "base", "to_token": "0x4200000000000000000000000000000000000006",
  "wallet_address": "0x...", "slippage": 0.5
}'

Step 2: Dry Run - Create pipeline, get pipeline_id

npx tsx scripts/index.ts elsa_execute_swap_dry_run '{...same params...}'
# Returns: { "pipeline_id": "abc-123", ... }

Step 3: User Confirmation - Present results and wait for explicit "yes"

Step 4: Execute Pipeline - Sign and broadcast transactions

ELSA_ENABLE_EXECUTION_TOOLS=true npx tsx scripts/index.ts elsa_pipeline_run_and_wait '{
  "pipeline_id": "abc-123",
  "timeout_seconds": 180,
  "poll_interval_seconds": 3,
  "mode": "local_signer"
}'
# Automatically: signs approve tx → submits → signs swap tx → submits → returns tx hashes

Critical Rules

• NEVER execute swaps without showing the user the quote first
• NEVER call execution tools in a loop
• NEVER proceed if budget limits are exceeded
• ALWAYS check elsa_budget_status if unsure about remaining budget
• ALWAYS use dry-run mode first for any swap operation

Environment Variables

API Pricing

Pricing may change. Actual costs are determined by x402 payment headers at request time.

See current pricing at x402.heyelsa.ai.

Supported Chains

• base (default)
• ethereum
• arbitrum
• optimism
• polygon
• bsc
• avalanche
• zksync

Coming Soon

• Hyperliquid Perp Endpoints - Perpetual futures trading on Hyperliquid L1
• Polymarket APIs - Prediction market trading and data

License

MIT