Elsa x402 API

---

name: openclaw-elsa-x402 description: DeFi tools for portfolio analysis, token search, and swap execution via Elsa API with x402 micropayments metadata: {"openclaw":{"requires":{"env":["PAYMENT_PRIVATE_KEY"]},"primaryEnv":"PAYMENT_PRIVATE_KEY"}}

---

Elsa x402 DeFi Tools

This skill provides access to the Elsa DeFi API for portfolio management, token analysis, and swap execution using x402 micropayments.

Standard Operating Procedure

Budget Controls

Maximum $0.05 per API call (configurable)

Maximum $2.00 per day (configurable)

Maximum 30 calls per minute rate limit

Daily budget resets at midnight in configured timezone (default: UTC)

Recommended Swap Flow (OpenClaw)

When executing swaps, follow this 4-step 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", "confirmation_token": "..." }

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

Required Environment Variables

# For x402 API payments
PAYMENT_PRIVATE_KEY=0x...
For signing swap transactions (optional - falls back to PAYMENT_PRIVATE_KEY)
TRADE_PRIVATE_KEY=0x...
Enable execution tools
ELSA_ENABLE_EXECUTION_TOOLS=true

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

Tool Catalog

Read-Only Tools (Always Available)

#### elsa_search_token Search for tokens across supported blockchains.

npx tsx scripts/index.ts elsa_search_token '{"query": "USDC", "limit": 5}'

Input:

query (string, required): Token name, symbol, or address

limit (number, optional): Max results (default: 10)

---

#### elsa_get_token_price Get current price for a token.

npx tsx scripts/index.ts elsa_get_token_price '{"token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chain": "base"}'

Input:

token_address (string, required): Token contract address

chain (string, optional): Chain name (default: "base")

---

#### elsa_get_balances Get token balances for a wallet.

npx tsx scripts/index.ts elsa_get_balances '{"wallet_address": "0x..."}'

Input:

wallet_address (string, required): Wallet address to query

---

#### elsa_get_portfolio Get comprehensive portfolio analysis.

npx tsx scripts/index.ts elsa_get_portfolio '{"wallet_address": "0x..."}'

Input:

wallet_address (string, required): Wallet address to analyze

---

#### elsa_analyze_wallet Get wallet behavior and risk assessment.

npx tsx scripts/index.ts elsa_analyze_wallet '{"wallet_address": "0x..."}'

Input:

wallet_address (string, required): Wallet address to analyze

---

#### elsa_get_swap_quote Get a swap quote with optimal routing.

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

Input:

from_chain (string, required): Source chain

from_token (string, required): Source token address

from_amount (string, required): Amount to swap

to_chain (string, required): Destination chain

to_token (string, required): Destination token address

wallet_address (string, required): Wallet address

slippage (number, required): Slippage tolerance (0-50)

---

#### elsa_execute_swap_dry_run Simulate a swap without execution. Returns a confirmation token for subsequent confirmed execution.

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

Output includes:

Swap simulation results

confirmation_token (if ELSA_REQUIRE_CONFIRMATION_TOKEN=true)

Token expires after ELSA_CONFIRMATION_TTL_SECONDS

---

#### elsa_budget_status Check current budget usage and remaining limits.

npx tsx scripts/index.ts elsa_budget_status '{}'

Output:

spent_today_usd: Amount spent today

remaining_today_usd: Remaining daily budget

calls_last_minute: Recent call count

last_calls: Recent call details

---

#### elsa_get_limit_orders Get all limit orders for a wallet.

npx tsx scripts/index.ts elsa_get_limit_orders '{"wallet_address": "0x...", "chain": "base"}'

Input:

wallet_address (string, required): Wallet address to query

chain (string, optional): Chain name (default: "base")

Output:

orders: Array of limit orders with status, prices, and expiry

---

#### elsa_get_perp_positions Get perpetual positions for a wallet.

npx tsx scripts/index.ts elsa_get_perp_positions '{"wallet_address": "0x..."}'

Input:

wallet_address (string, required): Wallet address to query

Output:

positions: Array of open perp positions with PnL, leverage, and liquidation prices

total_unrealized_pnl: Sum of unrealized profits/losses

total_margin: Total margin used

---

#### elsa_get_transaction_history Get transaction history for a wallet.

npx tsx scripts/index.ts elsa_get_transaction_history '{"wallet_address": "0x...", "chain": "base", "limit": 20}'

Input:

wallet_address (string, required): Wallet address to query

chain (string, optional): Filter by chain

limit (number, optional): Max results (default: 20, max: 100)

Output:

transactions: Array of transactions with details, token transfers, and status

---

Execution Tools (Requires ELSA_ENABLE_EXECUTION_TOOLS=true)

#### elsa_execute_swap_confirmed Execute a confirmed swap. Requires prior dry-run and confirmation token.

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

---

#### elsa_pipeline_get_status Check status of a pipeline/transaction.

npx tsx scripts/index.ts elsa_pipeline_get_status '{"pipeline_id": "pip_123456789"}'

---

#### elsa_pipeline_submit_tx_hash Submit a signed transaction hash to the pipeline.

npx tsx scripts/index.ts elsa_pipeline_submit_tx_hash '{"task_id": "task_123", "tx_hash": "0x..."}'

---

#### elsa_pipeline_run_and_wait Orchestrate full pipeline execution with automatic signing and submission.

npx tsx scripts/index.ts elsa_pipeline_run_and_wait '{
  "pipeline_id": "pip_123456789",
  "timeout_seconds": 120,
  "poll_interval_seconds": 2,
  "mode": "local_signer"
}'

Modes:

local_signer: Signs and broadcasts transactions using TRADE_PRIVATE_KEY

external_signer: Returns unsigned tx_data for external signing

---

#### elsa_create_limit_order Create a limit order to execute when price reaches target.

ELSA_ENABLE_EXECUTION_TOOLS=true npx tsx scripts/index.ts elsa_create_limit_order '{
  "wallet_address": "0x...",
  "chain": "base",
  "from_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "to_token": "0x4200000000000000000000000000000000000006",
  "from_amount": "100",
  "limit_price": "0.0004",
  "expiry_hours": 24
}'

Input:

wallet_address (string, required): Wallet address

chain (string, required): Chain name

from_token (string, required): Token to sell

to_token (string, required): Token to buy

from_amount (string, required): Amount to sell

limit_price (string, required): Target price to trigger execution

expiry_hours (number, optional): Hours until order expires (default: 24, max: 720)

---

#### elsa_cancel_limit_order Cancel an existing limit order.

ELSA_ENABLE_EXECUTION_TOOLS=true npx tsx scripts/index.ts elsa_cancel_limit_order '{
  "wallet_address": "0x...",
  "order_id": "order_123",
  "chain": "base"
}'

Input:

wallet_address (string, required): Wallet address

order_id (string, required): Order ID to cancel

chain (string, optional): Chain name (default: "base")

---

#### elsa_open_perp_position Open a perpetual futures position.

ELSA_ENABLE_EXECUTION_TOOLS=true npx tsx scripts/index.ts elsa_open_perp_position '{
  "wallet_address": "0x...",
  "market": "ETH-USD",
  "side": "long",
  "size_usd": "100",
  "leverage": 5,
  "take_profit": "4000",
  "stop_loss": "2800"
}'

Input:

wallet_address (string, required): Wallet address

market (string, required): Market pair (e.g., "ETH-USD", "BTC-USD")

side (enum, required): "long" or "short"

size_usd (string, required): Position size in USD

leverage (number, optional): Leverage multiplier (default: 1, max: 100)

take_profit (string, optional): Take profit price

stop_loss (string, optional): Stop loss price

---

#### elsa_close_perp_position Close an open perpetual position.

ELSA_ENABLE_EXECUTION_TOOLS=true npx tsx scripts/index.ts elsa_close_perp_position '{
  "wallet_address": "0x...",
  "position_id": "pos_123",
  "close_percentage": 100
}'

Input:

wallet_address (string, required): Wallet address

position_id (string, required): Position ID to close

close_percentage (number, optional): Percentage to close (default: 100, range: 1-100)

Supported Chains

base (default)

ethereum

arbitrum

optimism

polygon

bsc

avalanche

zksync

API Costs

| Tool | Estimated Cost | |------|----------------| | elsa_search_token | $0.002 | | elsa_get_token_price | $0.002 | | elsa_get_balances | $0.002 | | elsa_get_portfolio | $0.002 | | elsa_analyze_wallet | $0.005 | | elsa_get_swap_quote | $0.002 | | elsa_execute_swap_dry_run | $0.005 | | elsa_get_limit_orders | $0.002 | | elsa_get_perp_positions | $0.002 | | elsa_get_transaction_history | $0.002 | | elsa_create_limit_order | $0.05 | | elsa_cancel_limit_order | $0.01 | | elsa_open_perp_position | $0.05 | | elsa_close_perp_position | $0.05 | | elsa_execute_swap_confirmed | $0.05 |

Coming Soon

Polymarket APIs - Prediction market trading and data