Repeatable edge only
A trading bot without a sharply bounded objective becomes a smart gambler. This bot is not for open-ended prediction. It is for repeatable edge extraction.
All Rationales
Back to homeEvery rationale from the current ClawsPoly spec, collected in one place.
This page exists so the site can carry the full doctrine, not just selective highlights. The README mirrors the same logic for repo-level orientation.
Mission
Trade for edge, not for theater
ClawsPoly is positioned as a disciplined system that earns trust by narrowing scope and rejecting vague machine-gambling narratives.
Deterministic order path
Polymarket is a real trading venue, not a chat interface. Any model that can hallucinate must sit outside the order path.
System shape follows venue reality
The platform facts are not implementation trivia. They dictate the system shape: server-side only, signed-order workflow, low-latency WebSocket-first data path, auth isolation, rate-limit-aware execution, and a compliance gate before trade submission.
Strategy
Launch the cleanest edge first
Marketing should sell discipline before scale. The sequencing itself is part of the brand promise.
Speed-gap first
Speed-gap arbitrage is the cleanest mechanical edge. It depends less on opinion and more on timing.
Narrative strategies come later
Reasoning-gap repricing has higher theoretical upside but larger model risk. It comes after the speed-gap engine is proven.
Cross-venue is powerful but heavier
Cross-venue arbitrage is powerful but operationally heavier because the hedge leg adds coordination, capital fragmentation, and counterparty complexity.
Order matters
The rollout order minimizes ambiguity. Strategy A has the least narrative interpretation risk.
Architecture
Each layer has a job
The site should make the operating model legible. Every layer exists because a trading venue punishes ambiguity.
Discovery normalizes the venue
You cannot trade what you cannot normalize. Discovery creates a stable internal catalog.
Polling is too slow
The market channel is for real-time book state, the user channel is for the truth of your own orders and fills, and polling alone is too slow.
Signals must be inspectable
A signal must be inspectable and machine-testable. If a human cannot understand why the bot wants to trade, you cannot safely debug it.
Risk is the survival layer
This is the heart of survival. Every profitable bot eventually meets a regime it does not understand. The risk engine exists for that day.
Execution stays isolated
Execution needs its own isolated layer because order-logic bugs are the fastest route to self-inflicted loss.
Auditability is not optional
If the bot cannot explain its behavior after the fact, it is not production-grade.
Operations
Separate concerns before they hurt you
The product story includes service boundaries, host assumptions, and security posture because those are part of credibility.
Services separate for real reasons
Separate services are not for fashion. They let you scale market data independently, keep risk logic safe, and run execution with minimal dependencies.
Start simple on infrastructure
Latency matters, but this system is unlikely to need a huge cluster at first. Keep it simple until the edge proves itself.
Never mix hot money and reserves
Never combine treasury and hot execution funds.
Credentials stay server-side
This follows both security best practice and Polymarket’s own guidance: derive and store L2 credentials in secret management, never expose them client-side, and keep the user WebSocket server-only.
Market Scope
The bot earns money by saying no
Universe selection is both a risk control and a marketing promise. Narrowness signals discipline.
Universe selection is risk control
A market is eligible only when the order book is enabled, depth is sufficient, the spread is controlled, resolution logic is understood, and the event category is explicitly enabled.
Avoid exotic markets early
Phase 1 stays in short-duration crypto markets, simple binary structures, and markets with liquid books and transparent external references. Avoid exotic markets early. Complexity destroys edge through hidden assumptions.
Good bots skip most trades
Good bots make money from saying no most of the time.
Modeling
Simple models first, honest friction always
The fair-value story should sound calibrated, not mystical. The marketing language needs to reinforce that.
Calibrate before sophistication
Do not start with fancy modeling. Start with something you can calibrate and falsify.
Theoretical edge is not enough
A theoretical edge that cannot be captured net of execution friction is fake.
LLMs parse, they do not trade
Use the model as a parser and hypothesis generator, not as the final decision-maker.
Signal Discipline
Net edge or no trade
Signals are only valuable when they survive friction, confidence thresholds, and time decay.
Gross edge does not count
Gross edge is irrelevant. Net edge is the only edge.
Confidence filters noise
Minimum confidence reduces overtrading in noisy conditions.
Stale alpha turns against you
Stale alpha is anti-alpha.
Risk
Conservatism belongs before the order
The strongest marketing promise here is that ClawsPoly does not let strategy bypass hard controls.
Conservative before submission
The correct place to be conservative is before the order goes out.
Phase 1 is for survival
Phase 1 is for learning and survival, not heroics.
Prediction markets are inventory businesses
Prediction markets are inventory businesses as much as signal businesses.
Execution
Control price, state, and retries
The public pitch should stress control over price behavior, lifecycle certainty, and duplicate prevention.
Limit orders preserve control
Using Polymarket’s limit-order primitive gives full control over price and fill behavior.
Edges need different postures
Different edges require different execution postures. One-size-fits-all execution leaks money.
State ambiguity is expensive
Ambiguous order state is how bots double-submit or forget risk.
Retries need identity
Network retries without idempotency become duplicate trades.
Data Path
Fast channels with truth recovery
The market-data pitch should frame speed and reconciliation as complementary, not competing, concerns.
WebSockets are fast, snapshots recover truth
WebSockets are fast; snapshots are truth recovery.
Venue truth beats assumptions
Risk and inventory should key off confirmed venue state, not assumptions.
One dirty feed can fabricate edge
One dirty feed can fabricate fake arbitrage.
Policy
Compliance is part of execution quality
The bot does not become serious by ignoring venue rules. Policy gates are product features.
Fail closed on geography
A rejected order after the signal is already generated wastes resources and can cascade into logic bugs.
Allowlists prevent accidental expansion
A market-policy allowlist prevents a discovery bug from expanding the trading universe by accident.
Observability
If it cannot be replayed, it cannot be trusted
Replay, health, metrics, and alerts are all part of the external credibility story.
Append-only logs keep postmortems honest
Append-only logs make postmortems honest.
Running is not the same as safe
You need to distinguish process is running from bot is safe to trade.
Metrics expose execution decay
A profitable strategy can be ruined by a mediocre execution layer. Metrics reveal where the decay occurs.
Silence is not safety
Alerts exist because silence is not safety.
Speed-Gap v1
Price the book, do not worship it
This is the first live strategy, and it should be marketed as disciplined, narrow, and measurable.
Eligible only when the reference is clean
A short-duration binary market with a liquid order book, clear external crypto reference, and fully codified resolution mechanics is the cleanest path from observation to expected value.
Polymarket is a book to be priced
The bot should treat Polymarket as a book to be priced, not a source of truth.
Filter twice
The best trades are filtered twice: once by signal, once by market quality.
Explicit exits are mandatory
A production bot needs explicit exits. We will not hold because maybe it comes back.
Validation
Backtests should assume reality fights back
The public story should promise operational honesty, not a fantasy curve-fit.
Replay at event level
Candles are insufficient. You need event-level replay for a microstructure strategy.
Backtests must not assume magical fills
Most backtests lie by assuming magical fills.
Do not skip the ladder
Profitability in research does not justify skipping operational validation.
Paper and live should share strategy code
Do not fork the strategy code between paper and live. Only the execution adapter should change.
One paper PnL number is theater
Run optimistic, median, and pessimistic paper scenarios because a single paper PnL number is theater.
Rollout & Security
Scale proven process, not hopeful code
The beta story should be revenue-first now, reliability-first always, and security-tight from day one.
Scale proven processes
You scale proven processes, not hopeful code.
Leaky keys erase profits
A bot that makes money and leaks keys is not profitable.
Compartmentalize signing
Private key isolation exists for compartmentalization.
No browser-side trading credentials
No browser-side trading credentials. Ever.
Failure
Design for the ugly day
ClawsPoly should market its failure behavior as aggressively as its upside. That is what makes the promise believable.
Failure behavior defines production quality
Every production bot should be designed around its failure behavior, not just its happy path.
Build Scope
Prove one edge, not a circus
The repo should feel like a sharp beginning: bold on the front end, narrow in operational promises, and ready to expand without pretending everything is live.
Performance specialization is earned
Python gets you speed of development. Rust is introduced only where latency truly matters.
Structure follows operational boundaries
Directory structure should reflect operational boundaries, not just code aesthetics.
Version 1 proves one edge
Version 1 should prove one edge, not perform a circus.
Reliability first, profitability second
A real trading system is accepted on reliability first, profitability second.