Polymarket Integration (v1 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.