pear-protocol

🍐 Pear Protocol — Headless（Agent 钱包）

基于 Hyperliquid 的配对/篮子交易：将多头和空头两条腿作为同一个 合成仓位开立。本技能仅使用 HEADLESS 认证 —— Agent 自有的 Privy 钱包针对 V3 网关签署 SIWE 登录；无需浏览器、无需 OAuth、 无需用户交互。任何 Starchild Agent 均可开箱即用。

端点

• V3 网关（REST）： https://pro-gateway.pearprotocol.io
• Orchard MCP： https://mcp.pearprotocol.io/mcp（可流式 HTTP， 无状态 —— 直接接受 x-api-key；文档：https://docs.pear.garden）

认证 — scripts/gateway.py（用这个，不要手写 curl）

python3 skills/pear-protocol/scripts/gateway.py login        # SIWE login w/ agent wallet, caches tokens
python3 skills/pear-protocol/scripts/gateway.py status       # identity + token validity
python3 skills/pear-protocol/scripts/gateway.py ensure-key   # mint PEAR_API_KEY into .env (once)
python3 skills/pear-protocol/scripts/gateway.py markets --limit 15
python3 skills/pear-protocol/scripts/gateway.py get /trade-accounts
python3 skills/pear-protocol/scripts/gateway.py post <path> '<json>'   # writes; auto Bearer

流程：POST /auth/nonce {address} → wallet.wallet_sign(message)（EIP-191； 即使 personal_sign 恢复出底层 EOA，网关仍接受智能钱包地址 —— 不存在 EIP-1271 问题）→ POST /auth/login {method:"wallet",address,signature} → accessToken（JWT 约 15 分钟， 自动刷新/重新登录）。令牌缓存于 workspace/.pear/gateway_tokens.json （0600）。nonce→login 单飞：并发的 nonce 请求会轮换 nonce， 并使先前的签名返回 401。

哪种调用用哪种凭证

调用类型	认证	说明
网关读取（行情、资金费）	x-api-key: $PEAR_API_KEY	持久，读取范围
网关写入（订单、交易账户）	Authorization: Bearer …	api_key → 403；gateway.py 自动刷新
账户级调用	+ x-trade-account-id: <id>	账户超过 1 个后为必需
MCP 服务	直接使用 x-api-key	网关钱包 Bearer 在 MCP 上会被拒绝（令牌类型不同）

• GET /markets 必须带 ?connector=hyperliquid（291 个市场：价格、 资金费、OI、24h 成交量/涨跌幅）。

API-key 范围决定 MCP 工具面

POST /api-keys（Bearer）请求体 {"label": "...", "scope": "read"|"read_write"} （字段是 label 不是 name；原始 key 仅返回一次）。读取 key → 16 个 分析/账户工具。read_write → 32 个工具，增加交易： open_basket、close_basket、set_position_tpsl、 rebalance_position、adjust_position、enable_auto_rebalance 的 plan/execute 配对，外加 sync_account、cancel_pending_order、manage_saved_basket。

约定：将读取 key 存为 PEAR_API_KEY，并（如涉及交易）将一个 read_write key 存为 PEAR_API_KEY_RW，放在 workspace/.env 中。用于 MCP 交易时， 在调用 pear_mcp.py 前先 export PEAR_API_KEY=$PEAR_API_KEY_RW。

MCP 客户端 — scripts/pear_mcp.py

python3 skills/pear-protocol/scripts/pear_mcp.py status
python3 skills/pear-protocol/scripts/pear_mcp.py list
python3 skills/pear-protocol/scripts/pear_mcp.py call <tool> '<json-args>'

自动使用来自 env/.env 的 PEAR_API_KEY（x-api-key 请求头）。读取工具： get_position（+history）、discover_assets、list_baskets、 search_prediction_markets、get_leaderboard、list_trade_accounts、 get_account_summary、get_fee_quote、get_tca、list_pending_orders 等。

交易账户（Hyperliquid）—— 在任何 execute_* 之前必需

每个 Agent 一次性设置（已连接账户 id 会在第 3 步返回； 将其保存在 .pear/trade_account.json 中）：

1. 生成密钥对（eth_account.Account.create()）→ 保存到 .pear/hl_signer.json（0600）。
2. 批准为 HL Agent 钱包 —— 用户签名的 approveAgent 操作，EIP-712 域 HyperliquidSignTransaction（chainId 421614），类型 HyperliquidTransaction:ApproveAgent [hyperliquidChain, agentAddress, agentName, nonce] —— 由 Privy master 通过钱包服务 /agent/sign-typed-data 签名（与 hyperliquid skill 的 sign_user_action 相同的模式）。提交到 POST api.hyperliquid.xyz/exchange，带上 signatureChainId: "0x66eee"（即使在 Mainnet 上也使用 —— hyperliquidChain 字段用于选择网络；请使用该值）。42161 / 0xa4b1 也被接受， 并已验证可用 —— 真正的要求是 signatureChainId 必须与签名时使用的域 chainId 完全一致。用 info {"type":"extraAgents","user":<master>} 验证。
3. POST /trade-accounts（Bearer）—— 精确 payload（validation 错误只有在 存在 connector 时才会显示详细信息）： {"alias": "...", "connector": "hyperliquid", "exchangeIdentifier": <master addr>, "credentials": {"signer_key": <signer priv, snake_case!>}, "metadata": {"agentWalletAddress": <signer addr>, "isSubaccount": false, "mainAccountAddress": <master addr>}} → 201，返回 account.id。

资金保留在 master HL 账户下；signer 负责交易，不能提现。

4. 批准 Pear 的 builder fee（必需 —— 没有它执行会失败）。 Pear 不会替你执行此操作。通过 MCP get_fee_recipient {"connector":"hyperliquid"} 获取 builder 地址（当前为 0xa47d4d99191db54a4829cdf3de2417e527c3b042，fee 6 bps）。用 MASTER 钱包（不是 signer）签署一个用户签名的 approveBuilderFee 操作：EIP-712 类型 HyperliquidTransaction:ApproveBuilderFee [hyperliquidChain, maxFeeRate, builder, nonce]，domain/chain-id 规则与 approveAgent 相同。使用 maxFeeRate: "0.1%"（HL perps 上限）。提交到 POST api.hyperliquid.xyz/exchange，带上匹配的 signatureChainId。 验证：info {"type":"maxBuilderFee","user":<master>,"builder":<builder>} 必须返回 > 0（100 = 0.1%）。

通过 MCP 交易 —— plan → execute 模式

Arg 结构：{"tradeAccountId": <id>, "params": {...}} —— params 是一个 基于 executionStyle（market|twap|trigger|ladder）的可辨识联合。 Legs：{"source":"symbol","symbol":"BTC","side":"BUY"|"SELL"} + 顶层 totalUsd、leverage、marginMode。plan_* = 使用带定价 legs/margin 的 dry-run （执行前务必向用户展示）；execute_* = 实盘。 HL 每个 leg 最低 $10 notional（会自动上调并给出警告）。

Preflight（每次 execute_ 前运行）：*

python3 scripts/preflight.py check --notional <usd> [--leverage N]

验证：API key、交易账户、链上 builder-fee 批准、余额 明细（perp equity 与 spot —— 可捕获卡在 spot 中的资金 / 会使 xyz:* builder-DEX 市场 保证金归零的账户模式问题），以及可用 margin 与计划 notional 的对比。Exit 0 = 可安全执行；非零 = 被阻止， 并给出具体原因。不要在 preflight 失败时执行。

交易后 receipt（每次 execute_ 后运行）：*

python3 scripts/preflight.py verify <execution_id> --trade-account <id>

检查执行状态 + venue 错误 + filledQuantity + 仓位 是否确实存在。只有 "FILLED ✅" 才表示发生了交易。

⚠️ status: executed ≠ filled。 execute_* 响应只表示 Pear 提交了订单。务必验证结果：检查执行记录 中的 venue 错误和 filledQuantity > 0，然后确认仓位存在 （get_position / HL clearinghouseState）。一个常见的明确拒绝是 "Builder fee has not been approved" → 运行交易账户 配方中的第 4 步，然后重试。

get_account_summary args：{"tradeAccountId": <id>, "params": {"scope": "balance"}}。

说明

• 只读的配对数据（资金、比率）也可以来自 hyperliquid 技能；当操作 Pear 账户或使用 Pear 分析时，请使用 Pear。
• 可选：由 Pear 签发的 clientId 可用于归属路由交易量（请联系 Pear）。
• 文档：https://docs.pear.garden/api-integration/access-management/authentication-process

故障排除

• Builder 费用审批存在缓存传播延迟。 在链上 maxBuilderFee 验证为 > 0 后，Pear 的场所检查可能仍会短暂拒绝（"Builder fee has not been approved"）——请等待约 1–2 分钟并重试，然后再进一步调试。

• 在 Hyperliquid 账户上启用统一账户抽象之前，xyz:*（HIP-3 builder-DEX）市场显示的保证金为 $0。 如果某个计划定价正常，但某个 xyz 交易对的可用保证金显示为零，请先启用统一/抽象账户模式，然后重新规划。

• 账户范围的网关/MCP 调用（positions、account summary、execute_*）在连接交易账户之前会失败——这是预期行为；请先按照交易账户的操作指南进行。市场数据和分析工具无需交易账户即可使用。

• 导入钱包模块可能会打印关于不可用的可选分析集成（例如 CoinGecko/Coinglass）的无害警告——请忽略它们；它们不会影响 Pear。

• 脚本在可用时会自动通过 Starchild 的经过身份验证的代理路由 HTTP，否则回退到直接连接；无需配置。