Plan the Polymarket integration around the official Rust SDK and a staged read-to-trade rollout

[ElioNeto]

Issue imported from tinyhumansai/openhuman#1531
Created at: unknown

---

Summary

Define a Polymarket-specific implementation plan for OpenHuman that uses Polymarket's maintained Rust SDK as the execution base, stages the product from read-only market access to permissioned trading, and avoids copying the Python-first agent reference implementation into the core runtime.

Problem

Issue tinyhumansai#1398 is the right umbrella, but it is still too broad to execute cleanly for Polymarket. We need a venue-specific plan before we start wiring controllers and UI, because Polymarket has several implementation details that materially affect architecture:

• There are multiple official reference repos with different purposes.
• The older Polymarket/rs-clob-client repository is archived and its README now directs new integrations to Polymarket/rs-clob-client-v2.
• Trading requires more than generic wallet sends: CLOB auth, funder/signer handling, allowance setup, and CTF split/merge/redeem flows all need explicit product and safety decisions.
• OpenHuman is desktop-first with a Rust core, so we should not import a Python app architecture just because it exists upstream.
• Polymarket's own public materials explicitly describe jurisdiction restrictions for trading, so read-only data access and write-capable trading flows should not be treated as the same capability.

Useful references reviewed:

• Polymarket/agents
  • Useful as a product-pattern reference for market discovery, agent workflows, RAG/news augmentation, and CLI-level tool shape.
  • Not a direct implementation base for OpenHuman because it is Python-first, assumes direct private-key env usage, and bundles orchestration choices that do not match our Rust controller registry / Tauri app architecture.
• Polymarket/rs-clob-client-v2
  • Best candidate for the execution layer inside src/openhuman/ because it is maintained, Rust-native, typed, and already covers the APIs we are likely to need (clob, gamma, ws, data, ctf, bridge, etc.).
• chainstacklabs/polyclaw
  • Useful as a UX/flow reference for concrete user actions like trending markets, wallet status, approvals, positions, and buy YES/NO flows.
  • Not an implementation base because it is OpenClaw-specific, Python-based, and stores state outside our core/runtime model.

Solution (optional)

Plan the Polymarket work as four explicit phases, each with its own acceptance gate.

Phase 0: architecture and policy decisions

Decide and document:

• Canonical SDK choice: use Polymarket/rs-clob-client-v2, not the archived v1 SDK.
• Capability split: read-only market intelligence vs authenticated trading.
• Jurisdiction/compliance model: how OpenHuman should expose market browsing globally while keeping trading behind explicit eligibility, connection, and confirmation gates.
• Wallet model: how the seed-phrase/multi-chain wallet work in Add seed phrase onboarding and multi-chain wallet setup tinyhumansai/openhuman#1395 and wallet tool work in Add crypto wallet tools for balances, transfers, swaps, and contract calls tinyhumansai/openhuman#1396 map onto Polymarket signer/funder requirements.

Phase 1: read-only Polymarket integration

Add a dedicated src/openhuman/polymarket/ domain with controller schemas for:

• Market discovery/search
• Event and market detail lookup
• Orderbook / price snapshot reads
• Optional websocket-backed live updates
• Read-only positions/account views where API support allows it without signing

This phase should be safe to ship even before trading is enabled.

Phase 2: authenticated trading integration

Add the trading surface in the Rust core using explicit quote/simulate/confirm/execute boundaries:

• Client authentication and API credential management
• Funder/signer derivation and account status checks
• Allowance / approval inspection and setup flows
• Order placement, cancellation, and status inspection
• CTF-aware trade flows where needed (split / merge / redeem) rather than pretending every action is a simple spot buy

No autonomous background trading in this phase.

Phase 3: app UX and connection surfaces

Wire the React app and capability catalog to the real Polymarket support surface:

• ConnectionsPanel status and connection flow
• Read-only market browsing entry points
• Clear trading-risk copy and confirmation UX
• Capability-catalog updates in src/openhuman/about_app/

Phase 4: agent routing and strategy hooks

Once the underlying tools are stable, expose them to a narrow built-in crypto/trading agent:

• Prefer read-before-write and quote-before-execute sequences
• Keep market analysis separate from direct order placement tools
• Treat external research/news/RAG as optional augmentation, not a hard dependency of the core integration

Acceptance criteria

• SDK decision recorded — the implementation plan explicitly chooses Polymarket/rs-clob-client-v2 as the primary Rust integration base and records why the archived v1 SDK and Python agent repo are not direct implementation targets.
• Domain seam defined — a dedicated src/openhuman/polymarket/ module plan exists, including mod.rs, schemas.rs, controller handlers, and provider-specific submodules instead of transport-specific branches.
• Phased rollout defined — the issue breaks Polymarket into read-only, authenticated trading, app UX, and agent-routing phases with clear dependencies.
• Policy boundaries defined — the plan distinguishes read-only data access from trading capability, includes explicit confirmation boundaries, and addresses jurisdiction/compliance gating.
• Wallet mapping defined — the plan explains how OpenHuman wallet work maps onto Polymarket signer/funder/auth requirements, including approvals and CTF-related flows.
• Test strategy defined — the issue identifies Rust unit coverage, JSON-RPC E2E coverage, Vitest coverage, and desktop E2E scenarios needed before shipping trading support.
• Follow-up implementation issues created or linked — the plan is decomposed into implementable child tasks beneath Add Polymarket, Kalshi, and Hyperliquid trading integrations tinyhumansai/openhuman#1398.
• Diff coverage ≥ 80% — implementing PRs meet the changed-lines coverage gate (Vitest + cargo-llvm-cov, enforced by .github/workflows/coverage.yml).

Related

• Parent: Add Polymarket, Kalshi, and Hyperliquid trading integrations tinyhumansai/openhuman#1398
• Umbrella: Add crypto wallet and trading workflows to the OpenHuman agent tinyhumansai/openhuman#1394
• Depends on: Add seed phrase onboarding and multi-chain wallet setup tinyhumansai/openhuman#1395, Add crypto wallet tools for balances, transfers, swaps, and contract calls tinyhumansai/openhuman#1396, Add a dedicated crypto transaction agent tinyhumansai/openhuman#1397
• Official Polymarket agent framework: https://github.com/Polymarket/agents
• Official Polymarket Rust SDK (maintained): https://github.com/Polymarket/rs-clob-client-v2
• Official Polymarket Rust SDK (archived): https://github.com/Polymarket/rs-clob-client
• Product-pattern reference: https://github.com/chainstacklabs/polyclaw
• app/src/components/settings/panels/ConnectionsPanel.tsx
• src/openhuman/about_app/catalog.rs
• src/openhuman/agent/agents/
• src/core/all.rs