openhuman/gitbooks/developing/integrations/polymarket.md

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.