docs: Polymarket Infrastructure Tools — companion guide for production CLOB operations

[osr21]

Polymarket Infrastructure Tools — Companion Toolkit for clob-client-v2

This PR adds a companion guide (docs-infra-tools-companion.md) documenting six open-source infrastructure tools built on top of clob-client-v2. Each tool solves a specific operational problem that surfaces once you move beyond basic order placement.

Docs repo: https://github.com/osr21/polymarket-infra-tools
Live dashboard: https://polymarket-hub.replit.app/infra-tools/

---

Why this PR

The six most-upvoted open issue clusters in this repo (and py-clob-client-v2, rs-clob-client-v2) point to the same gap: developers know how to place orders with the SDK, but they don't have tooling to answer the harder operational questions that come next:

Open issue cluster	Gap	Tool that closes it
#34 (ghost fills — MATCHED but no on-chain settlement)	No independent settlement confirmation	CLOB Indexer — streams OrderFilled on-chain
#97, #95, #75, #73, #67, #66 (POLY_1271 signer mismatch)	API key bound to EOA, orders need deposit wallet	OMS — audits signer field on every order
balance: 0 after FAK fills (cache saturation)	CLOB balance cache doesn't decrement	OMS — local position view independent of API cache
No way to test signing before burning real USDC	No local matching engine	CLOB Simulator — in-memory price-time-priority engine
Large orders move the market	No slicing logic in SDK	Smart Order Router — TWAP/VWAP execution
Kalshi/Manifold pricing the same event differently	No cross-venue monitoring	Arbitrage Engine — spread detection across three venues

---

The Six Tools

1. CLOB Indexer

Streams OrderFilled events from the Polymarket Exchange contract on Polygon via eth_getLogs. Provides on-chain ground-truth for fill settlement — independent of the CLOB API. Addresses the ghost-fill problem (issue #34 in py-clob-client-v2): the CLOB marks orders MATCHED before on-chain settlement completes; the Indexer confirms only what actually settled.

2. Order Management System (OMS)

Tracks positions, cost basis, realized/unrealized P&L, and a double-entry accounting ledger. Reconciles against Indexer fills. The local position view remains accurate when the CLOB balance cache saturates — the root cause of the balance: 0 errors reported across all three V2 repos.

3. Market Maker

V2-native two-sided quote engine. Posts BID + ASK around a configurable fair value with spread control, inventory skewing, and a hard kill switch. Written in TypeScript against the V2 contract addresses — the poly-market-maker Python keeper still targets V1 and breaks on V2 due to FilterParams removal and order_version_mismatch.

4. Smart Order Router (SOR)

Breaks large orders into TWAP or VWAP slices. Submitting a $5,000+ position as a single order sweeps multiple book levels and signals intent to the market. 10-slice TWAP over 5 minutes typically improves average fill by 1–3% on mid-liquidity markets.

POST /infra/sor/orders
{ "tokenId": "0x…", "side": "BUY", "strategy": "TWAP",
  "totalSizeUsdc": 5000, "slices": 10, "intervalMs": 30000 }

5. Arbitrage Engine

Polls Kalshi, Manifold, and PredictIt for equivalent market prices and compares against Polymarket CLOB mid-prices. Surfaces spread opportunities above a configurable threshold. All three venue APIs are public with no auth. Execution requires simultaneous leg placement on both venues — the guide covers the timing and slippage risks in detail.

6. CLOB Simulator

In-memory price-time-priority matching engine that accepts the same order format as the live CLOB. Pre-seeded with two-sided order books for testing. This is the most directly useful tool for clob-client-v2 developers: validate your V2 signing flow, tick-precision handling, and fee calculations locally before touching the live CLOB with real USDC.

---

POLY_1271 Deposit Wallet — Operational Layer

The POLY_1271 issue cluster (#97, #95, #75, #73, #67, #66) is a SDK-layer fix, but there's a second layer: even after the SDK is fixed, deposit-wallet operations need runtime verification that the API key binds correctly to the deposit wallet (not the EOA). The OMS adds this audit:

// OMS validates on every order post:
assert(order.signer === depositWalletAddress,
  `signer mismatch: got ${order.signer}, expected ${depositWalletAddress}`);
assert(apiKey.owner === depositWalletAddress,
  `api key bound to wrong address: ${apiKey.owner}`);

---

Connection to This Repo

The companion guide explains exactly how each tool integrates with clob-client-v2:

• Which SDK methods it wraps or replaces
• How it handles the POLY_1271 signer flow
• Code examples using @polymarket/clob-client-v2 imports

The guide lives at docs-infra-tools-companion.md in the root — consistent with the existing README.md and examples/ pattern in this repo.

---

Checklist

• Adds documentation only — no source changes, no new dependencies
• Addresses the highest-impact open issue clusters (fix: preserve structured errors in paginated methods #34, Market orders: taker amount rounded to tick precision (5-6 decimals) but API caps it at 4 — orders rejected #87, No way to mint API credentials for POLY_1271 deposit wallets — /auth rejects an ERC-7739-wrapped ClobAuth signature that the wallet itself validates on-chain #97 and the POLY_1271 family)
• Code examples use @polymarket/clob-client-v2 types and conventions
• All six tools have full API documentation and DB schemas at https://github.com/osr21/polymarket-infra-tools

---

Note

Low Risk
Documentation-only addition with no runtime, auth, or dependency changes.

Overview
Adds docs-infra-tools-companion.md, a new root-level companion guide for developers running production systems on @polymarket/clob-client-v2.

The doc introduces six external polymarket-infra-tools capabilities (CLOB Indexer, OMS, market maker, SOR, cross-venue arb, local simulator), with problem/solution framing, sample API usage, and links to the tools repo and live dashboard. It also maps common open issues in this repo (ghost fills, balance cache, POLY_1271 signer, tick precision, etc.) to which tool mitigates them, plus a short getting-started section.

Documentation only — no application code or dependency changes.

^{Reviewed by Cursor Bugbot for commit 04d4dc9. Bugbot is set up for automated code reviews on this repo. Configure here.}