> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/developing/polymarket.md).

# 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.