mirror of
https://github.com/tinyhumansai/openhuman.git
synced 2026-07-28 05:12:33 +00:00
125 lines
3.9 KiB
Markdown
125 lines
3.9 KiB
Markdown
# 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.
|