Pear Protocol 是一个基于 Hyperliquid 的配对/篮子交易技能，核心思路是把一条多头腿和一条空头腿组合成一个合成头寸。该技能仅使用无头（headless）认证：智能体自己的 Privy 钱包对 V3 网关签署 SIWE 登录，不需要浏览器、OAuth 或用户交互，对任意 Starchild 智能体开箱即用。
接口方面，V3 网关（REST）地址为 https://pro-gateway.pearprotocol.io；Orchard MCP 地址为 https://mcp.pearprotocol.io/mcp（streamable HTTP、无状态，可直接接受 x-api-key，文档见 https://docs.pear.garden）。
认证通过 scripts/gateway.py 完成，官方建议使用该脚本而非手写 curl。常用命令包括：login（用智能体钱包执行 SIWE 登录并缓存令牌）、status（查看身份与令牌有效性）、ensure-key（一次性生成 PEAR_API_KEY 写入 .env）、markets --limit 15、get /trade-accounts、post <path> '<json>'（写操作，自动带 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 为单飞（single-flight）：并发 nonce 请求会轮换 nonce 并使较早的签名返回 401。
不同调用使用不同凭据：网关读操作（市场、资金费率）使用 x-api-key: $PEAR_API_KEY（持久、读范围）；网关写操作（订单、交易账户）使用 Authorization: Bearer …（api_key 会返回 403，gateway.py 会自动刷新）；账户范围调用需附加 x-trade-account-id: <id>（当账户多于一个时强制）；MCP 服务器直接使用 x-api-key（网关钱包 Bearer 在 MCP 上会被拒绝，因为令牌类型不同）。GET /markets 必须带 ?connector=hyperliquid（共 291 个市场，含价格、资金费率、持仓量、24 小时成交量/涨跌幅）。
API key 的作用域决定 MCP 工具面：POST /api-keys（Bearer）请求体 {"label": "...", "scope": "read"|"read_write"}（字段是 label 而非 name；原始 key 只返回一次）。read 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。约定：把 read key 存为 PEAR_API_KEY，若有交易需求再把 read_write key 存为 PEAR_API_KEY_RW 于 workspace/.env。MCP 交易前需 export PEAR_API_KEY=$PEAR_API_KEY_RW 再调用 pear_mcp.py。
MCP 客户端为 scripts/pear_mcp.py，支持 status、list、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_* 之前必须完成，每个智能体一次性设置：1）生成密钥对（eth_account.Account.create()）并保存到 .pear/hl_signer.json（0600）；2）批准为 HL 代理钱包——用户签名的 approveAgent 动作，EIP-712 域 HyperliquidSignTransaction（chainId 421614），类型 HyperliquidTransaction:ApproveAgent [hyperliquidChain, agentAddress, agentName, nonce]，由 Privy 主钱包通过钱包服务 /agent/sign-typed-data 签名（与 hyperliquid 技能的 sign_user_action 模式相同），提交到 POST api.hyperliquid.xyz/exchange 并带 signatureChainId: "0x66eee"（主网也使用该值，由 hyperliquidChain 字段选择网络；42161 / 0xa4b1 也被接受且经验证可用，真正要求是 signatureChainId 与签名时使用的域 chainId 完全一致），可用 info {"type":"extraAgents","user":<master>} 验证；3）POST /trade-accounts（Bearer），精确载荷为 {"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（验证错误只有在包含 connector 时才显示细节）。资金保留在 HL 主账户下，签名者负责交易但不能提现。4）批准 Pear 的 builder fee（必需，未批准则执行失败，Pear 不会代为处理）。通过 MCP get_fee_recipient {"connector":"hyperliquid"} 获取 builder 地址（当前为 0xa47d4d99191db54a4829cdf3de2417e527c3b042，费率 6 bps）。用主钱包（非签名者）签署用户签名的 approveBuilderFee 动作：EIP-712 类型 HyperliquidTransaction:ApproveBuilderFee [hyperliquidChain, maxFeeRate, builder, nonce]，域/chain-id 规则与 approveAgent 相同。maxFeeRate 使用 "0.1%"（HL 永续上限）。提交到 POST api.hyperliquid.xyz/exchange 并带匹配的 signatureChainId。验证：info {"type":"maxBuilderFee","user":<master>,"builder":<builder>} 必须返回 > 0（100 = 0.1%）。
通过 MCP 交易采用 plan → execute 模式。参数形状为 {"tradeAccountId": <id>, "params": {...}}，params 是以 executionStyle（market|twap|trigger|ladder）为判别字段的联合类型。腿（legs）为 {"source":"symbol","symbol":"BTC","side":"BUY"|"SELL"}，加上顶层 totalUsd、leverage、marginMode。plan_* 为带定价腿/保证金的干跑（执行前务必展示给用户）；execute_* 为实盘。HL 每条腿最低名义价值 10 美元（会自动上调并给出警告）。
每次 execute_* 前运行预检：python3 scripts/preflight.py check --notional <usd> [--leverage N]。它验证 API key、交易账户、链上 builder-fee 批准、余额构成（永续权益 vs 现货——可发现资金卡在现货或账户模式问题导致 xyz:* builder-DEX 市场保证金归零），以及可用保证金与计划名义价值的对比。退出码 0 表示可安全执行；非零表示被阻止并给出具体原因。预检失败时不要执行。
每次 execute_* 后运行交易回执：python3 scripts/preflight.py verify <execution_id> --trade-account <id>。它检查执行状态、场所错误、filledQuantity 以及头寸是否真实存在。只有 "FILLED ✅" 才表示成交。注意：status: executed ≠ filled，execute_* 响应只表示 Pear 已提交订单，务必验证结果：检查执行记录中的场所错误和 filledQuantity > 0，再确认头寸存在（get_position / HL clearinghouseState）。常见的明确拒绝是 "Builder fee has not been approved"，此时运行交易账户配方第 4 步后重试。get_account_summary 参数为 {"tradeAccountId": <id>, "params": {"scope": "balance"}}。
其他说明：只读的配对数据（资金费率、比例）也可来自 hyperliquid 技能；当需要操作 Pear 账户或使用 Pear 分析时使用 Pear。可选：Pear 签发的 clientId 可归因路由成交量（需联系 Pear）。文档见 https://docs.pear.garden/api-integration/access-management/authentication-process。
故障排查：builder-fee 批准存在缓存传播延迟，链上 maxBuilderFee 验证 > 0 后，Pear 的场所检查可能仍短暂拒绝（"Builder fee has not been approved"），等待约 1–2 分钟再重试，不要急于进一步调试。xyz:（HIP-3 builder-DEX）市场在 Hyperliquid 账户启用统一账户抽象前会显示 0 保证金；若某个 xyz 配对计划定价正常但可用保证金为零，先启用统一/抽象账户模式再重新计划。账户范围的网关/MCP 调用（持仓、账户摘要、execute_*）在连接交易账户前会失败，这是预期行为，先按交易账户配方操作；市场数据和分析工具无需交易账户即可使用。导入钱包模块可能打印关于可选分析集成（如 CoinGecko/Coinglass）不可用的无害警告，可忽略，不影响 Pear。脚本在可用时会自动通过 Starchild 的认证代理路由 HTTP，否则回退到直连，无需配置。