Skip to content

docs: correct CLOB V2 live-readiness status #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cgfixit merged 1 commit into from
Jul 13, 2026
Merged

docs: correct CLOB V2 live-readiness status #115

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 20 additions & 16 deletions PROFITABILITY_ANALYSIS_JUNE_2026.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,29 @@
# PolyMarket_Mimic_Trader Real-Money Feasibility

**Updated:** 2026-07-12
**Repo snapshot inspected for this recheck:** `origin/main` at `c286279` plus the current money-mode branch.
**Repo snapshot inspected for this recheck:** `origin/main` at `38c2639`.

## Verdict

**Still conditional NO for non-paper real-money mode.**

The latest main branch is materially better than the June review: it now handles current Polymarket API shapes, price-shaped taker fees, CLOB fee metadata, strict mode validation, live geoblock and forward-paper startup gates, WebSocket heartbeat behavior, `usdcSize` activity notional, timing telemetry, and partial exits.
The latest main branch is materially better than the June review: it now handles price-shaped taker fees, CLOB fee metadata, strict mode validation, live geoblock and forward-paper startup gates, WebSocket heartbeat behavior, `usdcSize` activity notional, timing telemetry, partial exits, and conservative all-in BUY sizing.

Those fixes remove several stale implementation blockers. They do **not** prove the strategy is profitable, and they do **not** make the targeted international CLOB a legal or practical real-money venue for a US or Georgia-based operator.

## Current-Source Recheck (2026-07-12)

- **[verified external fact]** Current Polymarket trading docs still recommend `py-clob-client-v2`, L1-to-L2 auth, and deposit-wallet `signature_type=3` plus funder/deposit-wallet address for new API users.
- **[verified external fact]** The international API lists the United States as close-only for both frontend and API order entry. Polymarket US is a separate CFTC-designated contract market operated by QCX LLC.
- **[verified external fact]** Polymarket migrated production trading to CLOB V2 on 2026-04-28. Legacy V1 SDKs and V1-signed orders are no longer supported; the supported Python path is `py-clob-client-v2`, with pUSD collateral and the V2 order structure.
- **[verified external fact]** The international API lists the United States as **blocked**, not close-only. Polymarket US is a separate CFTC-designated contract market operated by QCX LLC, with a separate API and API-key authentication model.
- **[verified external fact]** The Data API activity endpoint supports `TRADE`, `REDEEM`, and `REWARD` filters. The federal UIGEA definition depends on applicable federal and state law, the Wire Act addresses specified interstate or foreign wagering transmissions, and Georgia's constitution prohibits listed gambling forms except authorized exceptions.
- **[repo fact]** This repo still pins `py-clob-client>=0.34,<1.0`, initializes the international CLOB client, and requests tracker activity with `type=TRADE` even though its scorer contains redemption handling.
- **[repo fact]** This repo still pins `py-clob-client>=0.34,<1.0`, uses the legacy `py_clob_client` adapter and order structures, initializes the international CLOB client, and requests tracker activity with `type=TRADE` even though its scorer contains redemption handling.
- **[inference]** The international live path remains a venue mismatch for a Georgia operator, while the separate Polymarket US venue would require a different, currently absent adapter and its own eligibility/API review.
- **[unknown]** The cited federal and Georgia text does not by itself classify every event contract or automation pattern. Venue-specific counsel is still required.

## What Is Fixed In The Current Tree

- Current Data API leaderboard path and schema are handled.
- Market WebSocket path and application-level `PING` heartbeat are handled.
- Market WebSocket connectivity and application-level `PING` heartbeat are handled, but the current nested `price_changes` event shape is not.
- Activity rows can use `usdcSize` for copied trade notional.
- Paper fills use Polymarket's price-shaped taker fee curve: `fee_rate * price * (1 - price)`.
- Market fee metadata is pulled from CLOB/Gamma data when available.
Expand All @@ -33,16 +33,16 @@ Those fixes remove several stale implementation blockers. They do **not** prove
- Timing telemetry exists for profitability analysis.
- `config.yaml` uses the canonical `paper_taker_fee_rate` key.
- Partial exit fills retain and account for the open remainder.
- This branch sizes BUY shares against conservative all-in entry cost so slippage and fees cannot push a configured dollar budget above its ceiling.
- BUY shares are sized against conservative all-in entry cost so slippage and fees cannot push a configured dollar budget above its ceiling.

## Why Real-Money Mode Is Still Blocked

1. **Venue and legal mismatch.** The code targets the international crypto CLOB, whose official geoblock lists the United States as close-only. Polymarket US is a separate CFTC-designated venue, but this repo has no adapter for it. The geoblock preflight is a safety check, not permission to trade.
1. **Venue and legal mismatch.** The code targets the international crypto CLOB, whose official geoblock lists the United States as blocked. Polymarket US is a separate CFTC-designated venue with a separate API, but this repo has no adapter for it. The geoblock preflight is a safety check, not permission to trade.
2. **No profitability proof.** There is still no held-out offline backtest that measures selected traders forward, net of spread, slippage, taker fees, latency, skipped fills, no-fills, and market impact.
3. **Paper mode is not a go-live signal.** Paper mode is useful for plumbing and telemetry, but it still cannot prove live fill quality, partial/no-fill selection bias, or thin-book market impact.
4. **The copied signal is delayed and public.** The bot copies after public activity appears. Skilled Polymarket traders appear to earn much of their edge by reacting first; a delayed copier may buy after the source trade has already moved the book.
5. **Trader metrics remain biased.** The scorer can process redemptions, but its only activity fetch asks for `type=TRADE`, so held-to-resolution results are disconnected. Worthless-expiry losses can still be absent entirely. Historical ROI/win-rate inputs therefore remain biased.
6. **SDK/auth risk remains.** The repo has deposit-wallet config, but the official current-doc path is still `py-clob-client-v2` plus `signature_type=3` for new API users, while this repo's live client remains on `py-clob-client`; migration and real deposit-wallet order-path proof remain open work.
6. **The live client is on an unsupported protocol.** Production trading moved to CLOB V2, while this repo still uses the legacy V1 package and order structures. Deposit-wallet configuration does not make that adapter compatible. A V2 migration and minimal-funds order-path proof are prerequisites, not optional hardening.
7. **Breaker persistence is incomplete.** Daily PnL, consecutive-loss cooldown, and cooldown expiry remain in-memory state, and the shipped `drawdown_stop_pct` setting is not wired into the runtime risk configuration.

## Minimum Bar Before Real Money
Expand All @@ -53,25 +53,29 @@ Do not fund live mode until all of these are true:
- Paper mode reports include detection latency, submit latency, observed spread, simulated VWAP, fee, skip reason, and realized PnL by trader and market type.
- Trader scoring is de-biased for missing worthless-expiry losses or explicitly excludes strategies where that bias dominates.
- A venue-specific legal review confirms the operator, state, venue, automation method, and funding path are allowed.
- The exact live auth path is tested with minimal funds and redacted logs, including deposit-wallet behavior if `signature_type=3` is used.
- The live adapter uses the supported CLOB V2 SDK, pUSD collateral model, V2 order structure, and current auth/signing flow.
- The exact live auth and order path is tested with minimal funds and redacted logs.
- There is a rollback plan: tiny bankroll, daily loss stop, alerts, no reused hot wallet, and paper mode remains the default.

## Current Next Best Work

1. Build the offline backtest harness and make it the real go-live gate.
2. Add paper/live execution parity reports from real order-book snapshots.
3. Restore redemption visibility and de-bias trader metrics for unresolved or worthless outcomes.
4. Re-verify the Polymarket SDK/auth path and decide whether live mode remains in scope.
5. Scope a Polymarket US adapter separately if US real-money trading is a goal.
1. Fail closed before live startup while the repo remains on the unsupported V1 client.
2. Decide whether to migrate to international CLOB V2 or remove that live path; scope a Polymarket US adapter separately for US real-money trading.
3. Build the offline backtest harness and make it the real go-live gate.
4. Add paper/live execution parity reports from real order-book snapshots.
5. Restore redemption visibility and de-bias trader metrics for unresolved or worthless outcomes.

## Primary Sources Rechecked

- [Polymarket trading overview](https://docs.polymarket.com/trading/overview)
- [Polymarket CLOB V2 migration guide](https://docs.polymarket.com/v2-migration)
- [Polymarket changelog](https://docs.polymarket.com/changelog)
- [Polymarket user activity API](https://docs.polymarket.com/api-reference/core/get-user-activity)
- [Polymarket geographic restrictions](https://docs.polymarket.com/api-reference/geoblock)
- [Polymarket US API introduction](https://docs.polymarket.us/api-reference/introduction)
- [CFTC designation for QCX LLC d/b/a Polymarket US](https://www.cftc.gov/IndustryOversight/IndustryFilings/TradingOrganizations/49571)
- [31 U.S.C. 5362](https://uscode.house.gov/view.xhtml?edition=prelim&num=0&req=granuleid%3AUSC-prelim-title31-section5362)
- [18 U.S.C. 1084](https://uscode.house.gov/view.xhtml?edition=prelim&num=0&req=granuleid%3AUSC-prelim-title18-section1084)
- [Georgia Secretary of State constitution publications](https://sos.ga.gov/search?query=constitution)
- [Georgia Constitution, revised 2025](https://sos.ga.gov/georgia-constitution-revised-2025)

This is not financial or legal advice. It is the repo-level engineering status after the latest `origin/main` changes.
Loading