Principles & schemas

The locked rules that survive every rewrite. Read this once, then again before you ship.

Positioning rules

• Polytraders is the trading-infrastructure layer for Polymarket — user-controlled execution tools, risk controls, strategy templates, market analytics, and builder-attributed order routing. Not a bot store.
• No copy-trading, no signal-following, no wallet-following. 3.14 is Liquidity-Pulse, an internal liquidity model.
• No performance claims. Sharpe, PnL, hit-rate, target return — none of it. Configuration knobs only.
• No operator names anywhere on the page. The product describes itself.
• Plain-English reporting is mandatory for every bot. If a non-technical user can't understand what happened, the bot is not done.

Authority hierarchy

Risk > Security > Execution > Strategy > Discovery > Intelligence > Governance. A higher layer can always block a lower one. Governance never blocks anything; it explains.

The six standard schemas

OrderIntent — Strategy → Risk (Polymarket V2)

type OrderIntent = {
  intent_id: string;          // UUIDv4 — idempotency key for the entire pipeline
  strategy_id: string;        // which strategy emitted it
  market_id: string;          // Polymarket condition_id (bytes32 hex)
  outcome_id: string;         // YES or NO token id
  side: "BUY" | "SELL";
  size_usd: number;           // pUSD notional
  price: number;              // 0.001..0.999 (tick = 0.001)
  order_type: "LIMIT" | "MARKET" | "POST_ONLY" | "GTC" | "GTD" | "FOK" | "IOC";
  time_in_force?: number;     // seconds
  reduce_only?: boolean;
  // V2 builder attribution — native field, NOT HMAC headers
  builder?: { code: string;       // bytes32 builderCode
              fee_bps: number };  // ≤ 100 taker, ≤ 50 maker
  // V2 negative-risk awareness
  negrisk_aware?: boolean;
  emitted_at: string;         // ISO 8601
};

// NOTE: fees are NOT on the signed order in V2. The operator sets fees at
// match time. Only the BUILDER fee rate (capped) is on the order.

RiskVote — every Risk bot

type RiskDecision = "APPROVE" | "RESHAPE_REQUIRED" | "REJECT" | "WARNING_ONLY";
type RiskVote = {
  guard_id: string;
  decision: RiskDecision;
  severity: "INFO" | "WARN" | "P1" | "P0";
  reason_code: string;        // UPPER_SNAKE, stable, machine-readable
  message: string;
  constraints?: {
    max_size_usd?: number;
    max_price?: number;
    min_price?: number;
    passive_only?: boolean;
    close_only?: boolean;
    cooldown_seconds?: number;
    require_manual_review?: boolean;
  };
  inputs_used: string[];
  checked_at: string;
};

ExecutionPlan — Risk → Execution

type ExecutionPlan = {
  plan_id: string;
  intent_id: string;
  effective_size_usd: number;
  effective_price: number;
  order_type: OrderIntent["order_type"];
  passive_only: boolean;
  close_only: boolean;
  builder?: { code: string; fee_bps: number };
  constraints_applied: RiskVote[];
  approved_at: string;
};

SecurityCheck — Security layer

type SecurityCheck = {
  check_id: string;
  scope: "wallet" | "contract" | "session" | "signing";
  decision: "ALLOW" | "DENY" | "REQUIRE_2FA" | "PAUSE";
  reason_code: string;
  evidence: Record<string, unknown>;
  checked_at: string;
};

GovernanceLog — Governance layer

type GovernanceLog = {
  log_id: string;
  kind: "config_change" | "incident" | "manual_override" | "reconciliation" | "audit";
  actor: string;
  target: string;
  before?: unknown;
  after?: unknown;
  reason: string;
  evidence_uri?: string;
  created_at: string;
};

PostTradeExplanation — Governance

type PostTradeExplanation = {
  fill_id: string;
  intent_id: string;
  user_summary: string;       // plain English, no jargon
  guards_consulted: { guard_id: string; decision: string; reason_code: string }[];
  exec_path: string[];        // SmartRouter trail
  builder_attribution?: { code: string; fee_bps: number };
  generated_at: string;
};

Reason-code rules

• UPPER_SNAKE_CASE only.
• Stable across versions — never reword an existing code; deprecate and add a new one.
• Specific enough to drive a dashboard filter; never an English sentence.
• Examples: ORDER_BOOK_UNAVAILABLE, STALE_MARKET_DATA, SPREAD_TOO_WIDE, INSUFFICIENT_VISIBLE_DEPTH, STRATEGY_BUDGET_EXCEEDED, ORACLE_DISPUTE_ACTIVE, WALLET_PERMISSION_DENIED, CONTRACT_ADDRESS_NOT_ALLOWED, PARAMETER_CHANGE_REQUIRES_APPROVAL.

Default-value guidance

Bot status	Default posture
Planned	Conservative specification only. No live impact.
Beta	Conservative defaults, low caps, manual review on edge cases.
Limited live	Conservative defaults, explicit override process required.
General live	Defaults may relax only with performance + incident data.
Advanced	Manual review, capped exposure, full explanation always.

Threshold standards

Type	Meaning
Informational	Bot logs but takes no action.
Warning	Bot reports concern but does not block.
Soft constraint	Bot downsizes, delays, or changes execution mode.
Hard constraint	Bot rejects, pauses, or requires manual review.
Locked rule	Cannot be changed by user or strategy.

Implementation references

Each link below opens a focused sub-page covering one slice of the implementation surface. Read in order if you are new; jump in if you know what you need.

Do not build

These ten patterns are forbidden. They are the easiest mistakes to make and the most expensive ones to catch in production.

Final instruction

Do not expand the bot library by adding more bot names. Expand it by making each bot implementable. A good bot page should allow a developer to build the first version without asking: what data do I need? what parameters exist? what are the defaults? what should happen if the data is missing? when should it reject? what does it log? what does the user see? how do I know it is ready to ship?