Communitygithub.com

HeyElsa/elsa-openclaw

通过 Elsa API 结合 x402 微支付,提供投资组合分析、代币搜索和交易执行等 DeFi 工具。

elsa-openclaw 是什么?

这是一个 AI 代理技能,用于通过 Elsa API 和 x402 微支付协议执行 DeFi 操作。它支持投资组合管理、代币搜索与价格查询、市场分析及交易执行。该技能定义了一套严格的操作步骤,尤其是针对代币交换(Swap),要求必须依次执行报价获取、模拟运行(Dry Run)、用户确认和最终执行流水线这四个步骤,以确保安全。所有 API 调用都受预算控制(每次调用最高 $0.05,每日最高 $2.00)和速率限制(每分钟最多 30 次)。该技能适用于 Claude Code、Cursor 或 Codex 等 AI 代理平台。其核心工作流程包括使用只读工具获取数据,再通过启用 ELSA_ENABLE_EXECUTION_TOOLS=true 环境变量来使用执行工具(如 swap 确认、创建限价单、开设/平仓永续合约等)。整个流程依赖于 PAYMENT_PRIVATE_KEY 或 TRADE_PRIVATE_KEY 进行付款和交易签名。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add HeyElsa/elsa-openclaw

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Elsa x402 DeFi 工具

此技能提供对 Elsa DeFi API 的访问,用于投资组合管理、代币分析和通过 x402 微支付执行交易。

标准操作流程

预算控制

  • 每次 API 调用最高 $0.05(可配置)
  • 每日最高 $2.00(可配置)
  • 每分钟最多 30 次调用的速率限制
  • 每日预算在配置时区(默认:UTC)的午夜重置

推荐交换流程(OpenClaw)

执行交换时,请遵循以下 4 步流程:

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────┐     ┌─────────────────────┐
│ 1. 获取报价        │ ──▶ │ 2. 模拟运行          │ ──▶ │ 3. 确认      │ ──▶ │ 4. 执行流水线       │
│ elsa_get_swap_quote │     │ elsa_execute_swap_  │     │ [用户说     │     │ elsa_pipeline_run_  │
│                     │     │ dry_run             │     │  "yes"]     │     │ and_wait            │
└─────────────────────┘     └─────────────────────┘     └─────────────┘     └─────────────────────┘

第 1 步:获取报价 - 向用户展示他们将收到的内容

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
}'

第 2 步:模拟运行 - 创建流水线,获取 pipeline_id

npx tsx scripts/index.ts elsa_execute_swap_dry_run '{...相同参数...}'
# 返回:{ "pipeline_id": "abc-123", "confirmation_token": "..." }

第 3 步:用户确认 - 展示结果并等待明确的“是”

第 4 步:执行流水线 - 签名并广播交易

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"
}'
# 自动:签名批准交易 → 提交 → 签名交换交易 → 提交 → 返回交易哈希

必需的环境变量

# 用于 x402 API 付款
PAYMENT_PRIVATE_KEY=0x...

# 用于签名交换交易(可选 - 回退到 PAYMENT_PRIVATE_KEY)
TRADE_PRIVATE_KEY=0x...

# 启用执行工具
ELSA_ENABLE_EXECUTION_TOOLS=true

关键规则

  • 永远不要在未向用户展示报价前执行交换
  • 永远不要在循环中调用执行工具
  • 永远不要在预算限制超出时继续操作
  • 始终检查 elsa_budget_status,如果不确定剩余预算
  • 始终对任何交换操作首先使用模拟运行模式

工具目录

只读工具(始终可用)

elsa_search_token

跨支持的区块链搜索代币。

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

输入:

  • query(字符串,必需):代币名称、符号或地址
  • limit(数字,可选):最大结果数(默认:10)

elsa_get_token_price

获取代币的当前价格。

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

输入:

  • token_address(字符串,必需):代币合约地址
  • chain(字符串,可选):链名称(默认:"base")

elsa_get_balances

获取钱包的代币余额。

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

输入:

  • wallet_address(字符串,必需):要查询的钱包地址

elsa_get_portfolio

获取全面的投资组合分析。

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

输入:

  • wallet_address(字符串,必需):要分析的钱包地址

elsa_analyze_wallet

获取钱包行为和风险评估。

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

输入:

  • wallet_address(字符串,必需):要分析的钱包地址

elsa_get_swap_quote

获取具有最优路由的交换报价。

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
}'

输入:

  • from_chain(字符串,必需):源链
  • from_token(字符串,必需):源代币地址
  • from_amount(字符串,必需):要交换的金额
  • to_chain(字符串,必需):目标链
  • to_token(字符串,必需):目标代币地址
  • wallet_address(字符串,必需):钱包地址
  • slippage(数字,必需):滑点容忍度(0-50)

elsa_execute_swap_dry_run

模拟交换而不实际执行。返回后续确认执行所需的确认令牌。

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
}'

输出包括:

  • 交换模拟结果
  • confirmation_token(如果 ELSA_REQUIRE_CONFIRMATION_TOKEN=true)
  • 令牌在 ELSA_CONFIRMATION_TTL_SECONDS 后过期

elsa_budget_status

检查当前预算使用情况和剩余限制。

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

输出:

  • spent_today_usd:今日已花费金额
  • remaining_today_usd:剩余每日预算
  • calls_last_minute:最近一次调用次数
  • last_calls:最近调用详情

elsa_get_limit_orders

获取钱包的所有限价订单。

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

输入:

  • wallet_address(字符串,必需):要查询的钱包地址
  • chain(字符串,可选):链名称(默认:"base")

输出:

  • orders:包含状态、价格和到期时间的限价订单数组

elsa_get_perp_positions

获取钱包的永续合约头寸。

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

输入:

  • wallet_address(字符串,必需):要查询的钱包地址

输出:

  • positions:包含盈亏、杠杆和清算价格的未平仓永续头寸数组
  • total_unrealized_pnl:未实现利润/亏损总和
  • total_margin:使用的总保证金

elsa_get_transaction_history

获取钱包的交易历史。

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

输入:

  • wallet_address(字符串,必需):要查询的钱包地址
  • chain(字符串,可选):按链筛选
  • limit(数字,可选):最大结果数(默认:20,最大:100)

输出:

  • transactions:包含详情、代币转账和状态的交易数组

执行工具(需要 ELSA_ENABLE_EXECUTION_TOOLS=true)

elsa_execute_swap_confirmed

执行已确认的交换。需要事先进行模拟运行和确认令牌。

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

检查流水线/交易的状态。

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

elsa_pipeline_submit_tx_hash

向流水线提交已签名的交易哈希。

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

elsa_pipeline_run_and_wait

编排完整的流水线执行,自动签名和提交。

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

模式:

  • local_signer:使用 TRADE_PRIVATE_KEY 签名并广播交易
  • external_signer:返回未签名的 tx_data 供外部签名

elsa_create_limit_order

创建限价订单,在价格达到目标时执行。

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
}'

输入:

  • wallet_address(字符串,必需):钱包地址
  • chain(字符串,必需):链名称
  • from_token(字符串,必需):要卖出的代币
  • to_token(字符串,必需):要买入的代币
  • from_amount(字符串,必需):卖出金额
  • limit_price(字符串,必需):触发执行的目标价格
  • expiry_hours(数字,可选):订单到期小时数(默认:24,最大:720)

elsa_cancel_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"
}'

输入:

  • wallet_address(字符串,必需):钱包地址
  • order_id(字符串,必需):要取消的订单 ID
  • chain(字符串,可选):链名称(默认:"base")

elsa_open_perp_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"
}'

输入:

  • wallet_address(字符串,必需):钱包地址
  • market(字符串,必需):市场对(例如 "ETH-USD", "BTC-USD")
  • side(枚举,必需):"long" 或 "short"
  • size_usd(字符串,必需):以美元计的头寸规模
  • leverage(数字,可选):杠杆倍数(默认:1,最大:100)
  • take_profit(字符串,可选):止盈价格
  • stop_loss(字符串,可选):止损价格

elsa_close_perp_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
}'

输入:

  • wallet_address(字符串,必需):钱包地址
  • position_id(字符串,必需):要平仓的头寸 ID
  • close_percentage(数字,可选):平仓百分比(默认:100,范围:1-100)

支持的链

  • base(默认)
  • ethereum
  • arbitrum
  • optimism
  • polygon
  • bsc
  • avalanche
  • zksync

API 成本

工具预估成本
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

即将推出

  • Polymarket API - 预测市场交易和数据

相关技能