feat(integrations): Polymarket trading + market data (#1398, venue 1/3) (#2145)

2026-07-30 23:14:37 +00:00 · 2026-05-19 19:15:20 +05:30
parent d4dacd62ae
commit 2f4c3f397d
22 changed files with 3565 additions and 19 deletions
@@ -0,0 +1,124 @@
+# Polymarket Integration (Read + Trading)
+
+This document describes the Polymarket integration for issue #1398.
+
+## Scope
+
+The `polymarket` tool now supports both market browsing and trading workflows over:
+
+- Gamma API (`https://gamma-api.polymarket.com`)
+- CLOB API (`https://clob.polymarket.com`)
+
+Supported read actions:
+
+- `list_markets`
+- `get_market`
+- `list_events`
+- `get_orderbook`
+- `get_price`
+- `get_positions`
+- `get_balance`
+- `get_open_orders`
+- `get_usdc_allowance`
+
+Supported write actions:
+
+- `place_order`
+- `cancel_order`
+
+## Architecture
+
+Implementation lives in `src/openhuman/tools/impl/network/polymarket.rs` with helper modules:
+
+- `clob_auth.rs`: L1 credential derivation + L2 HMAC headers
+- `polymarket_orders.rs`: EIP-712 order typed-data signing
+
+Key runtime behavior:
+
+- Layer-2 API credentials are derived on first authenticated call and cached.
+- Derived credentials are persisted to `integrations.polymarket.derived_clob_credentials` (plain config fallback until secret-store migration lands).
+- Order placement fetches `GET /nonce?user=<eoa>` before signing to avoid replay/nonce mismatch.
+- USDC.e allowance is read via Polygon `eth_call` against ERC-20 `allowance(owner, spender)`.
+
+## Authentication and Signing Flow
+
+### L1 handshake (one-time bootstrap)
+
+- Sign CLOB `ClobAuth` EIP-712 payload with Polygon chain id `137`.
+- Call `POST /auth/api-key`; if needed, fall back to `GET /auth/derive-api-key`.
+- Persist returned `{ apiKey, secret, passphrase }` for L2 usage.
+
+### L2 authenticated requests
+
+Each authenticated CLOB request signs:
+
+- `timestamp + method + request_path (+ body for POST)`
+
+Headers:
+
+- `POLY_ADDRESS`
+- `POLY_SIGNATURE`
+- `POLY_TIMESTAMP`
+- `POLY_NONCE: 0`
+- `POLY_API_KEY`
+- `POLY_PASSPHRASE`
+
+### Order signing
+
+`place_order` signs an EIP-712 order using domain:
+
+- name: `Polymarket CTF Exchange`
+- version: `1`
+- chain id: `137`
+- verifying contract: `integrations.polymarket.clob_exchange_contract`
+
+## Permissions
+
+Write actions are currently guarded by an explicit stopgap approval flag.
+
+- `place_order` and `cancel_order` require `approved=true`.
+- If omitted or `false`, the tool returns:
+  - `Polymarket write requires explicit user approval. Re-invoke with arguments.approved = true after confirming with the user.`
+
+This is temporary until the shared approval gate from #1339 is integrated.
+
+## Configuration
+
+Config path: `integrations.polymarket`.
+
+Fields:
+
+- `enabled` (default `false`)
+- `gamma_base_url` (default `https://gamma-api.polymarket.com`)
+- `clob_base_url` (default `https://clob.polymarket.com`)
+- `timeout_secs` (default `15`)
+- `eoa_address` (optional default user address)
+- `polygon_rpc_url` (default `https://polygon-rpc.com`)
+- `usdc_contract` (default `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`)
+- `clob_exchange_contract` (default `0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E`)
+- `derived_clob_credentials` (optional cached L2 credentials)
+
+## USDC Allowance Contract
+
+`get_usdc_allowance` reports approval state only; it does not mutate chain state.
+
+- Token: USDC.e on Polygon (`0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`)
+- Spender: Polymarket exchange (`0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E`)
+
+If allowance is insufficient, approval must be executed separately (wallet tool / explicit user-approved flow).
+
+## Error and Retry Behavior
+
+- 4xx errors are treated as client errors and are not retried.
+- 429 and 5xx errors are treated as transient and retried up to 3 attempts.
+- Backoff is fixed at 500ms between retries.
+- Timeouts surface as explicit deadline errors.
+
+## Test Strategy
+
+Unit tests are in `src/openhuman/tools/impl/network/polymarket_tests.rs` plus helper-module tests.
+
+- Existing read-path and retry behavior tests remain covered.
+- Added coverage for authenticated read actions, write approval gating, and Polygon allowance reads.
+- `clob_auth.rs` tests cover HMAC/header fixture behavior.
+- `polymarket_orders.rs` tests cover domain and deterministic signing fixture behavior.