pear-protocol

🍐 Pear Protocol — ヘッドレス（エージェントウォレット）

Hyperliquid 上でのペア/バスケット取引：ロングレッグとショートレッグを 1 つの 合成ポジションとして開きます。このスキルはヘッドレス認証のみを使用します — エージェント自身の Privy ウォレットが V3 ゲートウェイに対して SIWE ログインに署名します。ブラウザも OAuth も ユーザー操作も不要です。あらゆる Starchild エージェントでそのまま動作します。

エンドポイント

• 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>	アカウントが 2 つ以上になったら必須
MCP サーバー	x-api-key を直接	ゲートウェイのウォレット Bearer は MCP では拒否されます（異なるトークン種別）

• GET /markets には ?connector=hyperliquid が必須です（291 マーケット：価格、 ファンディング、OI、24 時間の出来高/変動）。

API キーのスコープが MCP ツールの範囲を制限します

POST /api-keys（Bearer）ボディ {"label": "...", "scope": "read"|"read_write"} （フィールドは name ではなく label です。生のキーは一度だけ返されます）。読み取りキー → 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。

規約：読み取りキーを PEAR_API_KEY として、（取引する場合は）read_write キーを PEAR_API_KEY_RW として workspace/.env に保存します。MCP で取引するには、 pear_mcp.py を呼び出す前に 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_* の前に必須

エージェントごとに 1 回だけのセットアップ (接続済みアカウント ID は手順 3 で返されます。 .pear/trade_account.json に保存してください):

1. キーペアを生成 (eth_account.Account.create()) → .pear/hl_signer.json (0600) に保存します。
2. HL エージェントウォレットとして承認 — ユーザー署名の approveAgent アクション、EIP-712 ドメイン HyperliquidSignTransaction (chainId 421614)、型 HyperliquidTransaction:ApproveAgent [hyperliquidChain, agentAddress, agentName, nonce] — ウォレットサービス /agent/sign-typed-data 経由で Privy マスターが署名します (hyperliquid スキルの 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) — 正確なペイロード (検証エラーの詳細は connector が存在する場合にのみ表示されます): {"alias": "...", "connector": "hyperliquid", "exchangeIdentifier": <master addr>, "credentials": {"signer_key": <signer priv, snake_case!>}, "metadata": {"agentWalletAddress": <signer addr>, "isSubaccount": false, "mainAccountAddress": <master addr>}} → account.id を含む 201。

資金はマスター HL アカウントの下に留まります。署名者はトレードできますが、出金はできません。

4. Pear のビルダーフィーを承認します (必須 — これがないと実行は失敗します)。 Pear はこれを代行しません。MCP get_fee_recipient {"connector":"hyperliquid"} でビルダーアドレスを取得します (現在は 0xa47d4d99191db54a4829cdf3de2417e527c3b042、フィー 6 bps)。MASTER ウォレット (署名者ではありません) で ユーザー署名の approveBuilderFee アクションに署名します: EIP-712 型 HyperliquidTransaction:ApproveBuilderFee [hyperliquidChain, maxFeeRate, builder, nonce]、ドメイン/チェーン ID のルールは approveAgent と同じです。 maxFeeRate: "0.1%" (HL パープの上限) を使用します。一致する signatureChainId を付けて POST api.hyperliquid.xyz/exchange に送信します。 検証: info {"type":"maxBuilderFee","user":<master>,"builder":<builder>} が > 0 を返す必要があります (100 = 0.1%)。

MCP 経由のトレード — plan → execute パターン

引数の形: {"tradeAccountId": <id>, "params": {...}} — params は executionStyle (market|twap|trigger|ladder) の判別共用体です。 レッグ: {"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 キー、トレードアカウント、オンチェーンのビルダーフィー承認、残高 の内訳 (パープのエクイティとスポット — スポットに資金が留まっている / xyz:* のビルダー DEX 市場でマージンがゼロになる アカウントモードの問題を検出します)、および計画された取引額に対する利用可能 マージン。終了コード 0 = 実行しても安全、非ゼロ = 具体的な理由とともにブロック。 失敗するプリフライトでは実行しないでください。

トレード後のレシート (すべての execute_ の後に実行):*

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

実行ステータス + ベニューのエラー + filledQuantity + ポジションが 実際に存在することを確認します。「FILLED ✅」のみがトレードが成立したことを意味します。

⚠️ status: executed ≠ 約定。 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

トラブルシューティング

• ビルダーフィーの承認にはキャッシュ伝播の遅延があります。 オンチェーンの maxBuilderFee が 0 より大きいことを確認した後でも、Pear の会場チェックが一時的に拒否することがあります（「ビルダーフィーが承認されていません」）— 追加のデバッグを行う前に約 1～2 分待って再試行してください。

• xyz:*（HIP-3 ビルダー DEX）市場は、Hyperliquid アカウントで統合アカウント抽象化が有効になるまで証拠金が $0 と表示されます。 プランの価格設定は正常なのに xyz ペアで利用可能な証拠金がゼロと表示される場合は、まず統合/抽象化アカウントモードを有効にしてから、再プランしてください。

• アカウントスコープのゲートウェイ/MCP 呼び出し（positions、account summary、execute_*）は、トレードアカウントが接続されるまで失敗します — これは想定内です。まずトレードアカウントのレシピに従ってください。マーケットデータとアナリティクスのツールはトレードアカウントなしで動作します。

• ウォレットモジュールをインポートすると、利用できないオプションのアナリティクス統合（例: CoinGecko/Coinglass）に関する無害な警告が出力されることがあります — 無視してください。Pear には影響しません。

• スクリプトは、利用可能な場合は Starchild の認証済みプロキシを介して HTTP を自動ルーティングし、それ以外の場合は直接接続にフォールバックします。設定は不要です。