pear-protocol

🍐 Pear Protocol — Headless (agent wallet)

Pair/basket trading on top of Hyperliquid: open a long and a short leg as one synthetic position. This skill uses HEADLESS auth only — the agent's own Privy wallet signs a SIWE login against the V3 gateway; no browser, no OAuth, no user interaction. Works out of the box for any Starchild agent.

Endpoints

• V3 gateway (REST): https://pro-gateway.pearprotocol.io
• Orchard MCP: https://mcp.pearprotocol.io/mcp (streamable HTTP, stateless — accepts x-api-key directly; docs: https://docs.pear.garden)

Auth — scripts/gateway.py (use this, don't hand-roll 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

Flow: POST /auth/nonce {address} → wallet.wallet_sign(message) (EIP-191; gateway accepts the smart-wallet address even though personal_sign recovers to the underlying EOA — no EIP-1271 issue) → POST /auth/login {method:"wallet",address,signature} → accessToken (JWT ~15 min, auto-refresh/re-login). Tokens cached in workspace/.pear/gateway_tokens.json (0600). Single-flight nonce→login: concurrent nonce requests rotate the nonce and 401 the earlier signature.

Which credential for which call

Call type	Auth	Notes
Gateway reads (markets, funding)	x-api-key: $PEAR_API_KEY	persistent, read scope
Gateway writes (orders, trade-accounts)	Authorization: Bearer …	api_key → 403; gateway.py auto-refreshes
Account-scoped calls	+ x-trade-account-id: <id>	mandatory once >1 account
MCP server	x-api-key directly	gateway wallet Bearer is REJECTED on MCP (different token type)

• GET /markets REQUIRES ?connector=hyperliquid (291 markets: price, funding, OI, 24h vol/change).

API-key scopes gate the MCP tool surface

POST /api-keys (Bearer) body {"label": "...", "scope": "read"|"read_write"} (field is label NOT name; raw key returned ONCE). Read key → 16 analytics/account tools. read_write → 32 tools, adding trading: plan/execute pairs for open_basket, close_basket, set_position_tpsl, rebalance_position, adjust_position, enable_auto_rebalance, plus sync_account, cancel_pending_order, manage_saved_basket.

Convention: store the read key as PEAR_API_KEY and (if trading) a read_write key as PEAR_API_KEY_RW in workspace/.env. For MCP trading, export PEAR_API_KEY=$PEAR_API_KEY_RW before calling pear_mcp.py.

MCP client — 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>'

Auto-uses PEAR_API_KEY from env/.env (x-api-key header). Read tools: 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, etc.

Trade account (Hyperliquid) — REQUIRED before any execute_*

One-time setup per agent (the connected account id is returned at step 3; keep it in .pear/trade_account.json):

1. Generate keypair (eth_account.Account.create()) → save to .pear/hl_signer.json (0600).
2. Approve as HL agent wallet — user-signed approveAgent action, EIP-712 domain HyperliquidSignTransaction (chainId 421614), types HyperliquidTransaction:ApproveAgent [hyperliquidChain, agentAddress, agentName, nonce] — signed by the Privy master via wallet service /agent/sign-typed-data (same pattern as hyperliquid skill's sign_user_action). Submit to POST api.hyperliquid.xyz/exchange with signatureChainId: "0x66eee" (used even on Mainnet — the hyperliquidChain field selects the network; use that). 42161 / 0xa4b1 is also accepted and was verified working — the real requirement is that signatureChainId exactly matches the domain chainId used when signing. Verify with info {"type":"extraAgents","user":<master>}.
3. POST /trade-accounts (Bearer) — EXACT payload (validation errors only show details when connector is present): {"alias": "...", "connector": "hyperliquid", "exchangeIdentifier": <master addr>, "credentials": {"signer_key": <signer priv, snake_case!>}, "metadata": {"agentWalletAddress": <signer addr>, "isSubaccount": false, "mainAccountAddress": <master addr>}} → 201 with account.id.

Funds stay under the master HL account; signer trades, can't withdraw.

4. Approve Pear's builder fee (REQUIRED — executions fail without it). Pear does NOT do this for you. Get the builder address via MCP get_fee_recipient {"connector":"hyperliquid"} (currently 0xa47d4d99191db54a4829cdf3de2417e527c3b042, fee 6 bps). Sign a user-signed approveBuilderFee action with the MASTER wallet (not the signer): EIP-712 type HyperliquidTransaction:ApproveBuilderFee [hyperliquidChain, maxFeeRate, builder, nonce], same domain/chain-id rules as approveAgent. Use maxFeeRate: "0.1%" (HL perps cap). Submit to POST api.hyperliquid.xyz/exchange with matching signatureChainId. Verify: info {"type":"maxBuilderFee","user":<master>,"builder":<builder>} must return > 0 (100 = 0.1%).

Trading via MCP — plan → execute pattern

Arg shape: {"tradeAccountId": <id>, "params": {...}} — params is a discriminated union on executionStyle (market|twap|trigger|ladder). Legs: {"source":"symbol","symbol":"BTC","side":"BUY"|"SELL"} + top-level totalUsd, leverage, marginMode. plan_* = dry-run with priced legs/margin (ALWAYS show the user before executing); execute_* = live. HL $10 min notional per leg (auto-bumped with warning).

Preflight (run before every execute_*):

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

Verifies: API key, trade account, on-chain builder-fee approval, balance breakdown (perp equity vs spot — catches funds stuck in spot / account-mode issues that zero out margin on xyz:* builder-DEX markets), and available margin vs the planned notional. Exit 0 = safe to execute; nonzero = blocked with the specific reason. Do NOT execute on a failing preflight.

Post-trade receipt (run after every execute_*):

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

Checks execution status + venue errors + filledQuantity + that the position actually exists. Only "FILLED ✅" means a trade happened.

⚠️ status: executed ≠ filled. The execute_* response only means Pear submitted the order. ALWAYS verify the outcome: check the execution record for venue errors and filledQuantity > 0, then confirm the position exists (get_position / HL clearinghouseState). A common definitive rejection is "Builder fee has not been approved" → run step 4 of the trade-account recipe, then retry.

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

Notes

• Read-only pair data (funding, ratios) can also come from the hyperliquid skill; use Pear when acting on a Pear account or using Pear analytics.
• Optional: a Pear-issued clientId attributes routed volume (contact Pear).
• Docs: https://docs.pear.garden/api-integration/access-management/authentication-process

Troubleshooting

• Builder-fee approval has cache propagation delay. After on-chain maxBuilderFee verifies > 0, Pear's venue check may still reject briefly ("Builder fee has not been approved") — wait ~1–2 min and retry before debugging further.

• xyz: (HIP-3 builder-DEX) markets show $0 margin until unified account abstraction is enabled* on the Hyperliquid account. If a plan prices fine but available margin reads zero on an xyz pair, enable unified/abstracted account mode first, then re-plan.

• Account-scoped gateway/MCP calls (positions, account summary, execute_*) fail until a trade account is connected — expected; follow the trade-account recipe first. Market data and analytics tools work without one.

• Importing the wallet module may print harmless warnings about unavailable optional analytics integrations (e.g. CoinGecko/Coinglass) — ignore them; they don't affect Pear.

• Scripts auto-route HTTP through Starchild's authenticated proxy when available and fall back to direct connections otherwise; no configuration needed.