How to Build a Polymarket Trading Bot in 2026

# Polymarket CLOB API credentials
POLY_API_KEY=your_api_key_here
POLY_API_SECRET=your_api_secret_here
POLY_API_PASSPHRASE=your_passphrase_here

# Polymarket proxy/Safe wallet address (separate from your EOA above , 
# this is the address that actually holds your CLOB positions). Shown in
# the Polymarket UI under Settings → API. Pass it as `funder` when
# initializing ClobClient.
POLY_PROXY_ADDRESS=0xyour_proxy_wallet_address_here
# Signature type: 1 = POLY_PROXY (default for accounts created via the
# Polymarket UI), 2 = POLY_GNOSIS_SAFE (Safe-based smart wallets).
POLY_SIGNATURE_TYPE=1

# Your wallet private key (used to sign orders)
POLY_PRIVATE_KEY=0xyour_private_key_here

# Polygon RPC endpoint (use Alchemy or Infura for reliability)
POLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/your_alchemy_key

# Optional: sponsored Chainlink API key for Polymarket RTDS (free public stream
# works without this; the sponsored key adds SLA for serious 15m crypto trading).
# Request a key at https://pm-ds-request.streams.chain.link/
CHAINLINK_RTDS_API_KEY=

# Paper trading mode , keep this true until you've validated end-to-end
PAPER_TRADING=true

# Create project directory
mkdir polymarket-btc-bot && cd polymarket-btc-bot

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install py-clob-client-v2        # Official Polymarket CLOB SDK
pip install python-dotenv         # Load .env credentials
pip install requests              # HTTP calls to price feeds
pip install schedule              # Lightweight job scheduler
pip install web3                  # Polygon RPC interaction

# Create project files
touch .env main.py signal_engine.py orders.py risk.py utils.py
echo ".env" >> .gitignore
echo "venv/" >> .gitignore

echo "Project scaffolded. Fill in .env before running anything."

from py_clob_client_v2 import ClobClient
from py_clob_client_v2 import ApiCreds
from utils import load_env, get_logger

logger = get_logger(__name__)

def build_client() -> ClobClient:
    env = load_env()
    creds = ApiCreds(
        api_key=env["POLY_API_KEY"],
        api_secret=env["POLY_API_SECRET"],
        api_passphrase=env["POLY_API_PASSPHRASE"],
    )
    client = ClobClient(
        host="https://clob.polymarket.com",
        key=env["POLY_PRIVATE_KEY"],
        chain_id=137, # Polygon mainnet
        creds=creds,
        funder=env["POLY_PROXY_ADDRESS"], # the proxy that holds positions
        signature_type=int(env.get("POLY_SIGNATURE_TYPE", "1")), # 1=POLY_PROXY, 2=POLY_GNOSIS_SAFE
    )
    logger.info("CLOB client initialized")
    return client

import json
import time
import requests
from typing import Optional

GAMMA_HOST = "https://gamma-api.polymarket.com"
INTERVAL_S = 15 * 60  # 15-minute cycle

def current_cycle_start() -> int:
    """Wall-clock-aligned start of the current 15-min cycle (unix seconds)."""
    return int(time.time() // INTERVAL_S) * INTERVAL_S

def get_active_btc_15m_market() -> Optional[dict]:
    """
    Resolve the active BTC Up/Down 15M event from Gamma. Returns None only if
    Gamma has not yet published this cycle's event.
    """
    cycle_start = current_cycle_start()
    slug = f"btc-updown-15m-{cycle_start}"

    resp = requests.get(f"{GAMMA_HOST}/events/slug/{slug}", timeout=10)
    if resp.status_code == 404:
        # Gamma occasionally lags the boundary by a few seconds. Fall back
        # to a slug-prefix search and take the earliest endDate.
        fb = requests.get(
            f"{GAMMA_HOST}/markets",
            params={
                "slug_contains": "btc-updown-15m",
                "closed": "false",
                "limit": 20,
            },
            timeout=10,
        )
        fb.raise_for_status()
        rows = sorted(fb.json(), key=lambda m: m.get("endDate") or "")
        market = next(
            (m for m in rows if (m.get("slug") or "").startswith("btc-updown-15m")),
            None,
        )
        if market is None:
            return None
    else:
        resp.raise_for_status()
        event = resp.json()
        market = (event.get("markets") or [event])[0]

    # Gamma serializes these fields as JSON strings.
    outcomes = market["outcomes"]
    if isinstance(outcomes, str):
        outcomes = json.loads(outcomes)
    token_ids = market["clobTokenIds"]
    if isinstance(token_ids, str):
        token_ids = json.loads(token_ids)

    # Assign by outcome name, not by index. Polymarket does not guarantee
    # ordering, and silent UP/DOWN swaps are the worst class of bug to debug.
    by_outcome = {name.strip().lower(): tid for tid, name in zip(token_ids, outcomes)}
    if "up" not in by_outcome or "down" not in by_outcome:
        raise RuntimeError(f"Unexpected outcomes from Gamma: {outcomes}")

    return {
        "condition_id": market.get("conditionId") or market.get("condition_id"),
        "question": market.get("question") or market.get("title", ""),
        "slug": market["slug"],
        "cycle_start": cycle_start,
        "end_time": cycle_start + INTERVAL_S,
        "up_token_id": by_outcome["up"],
        "down_token_id": by_outcome["down"],
    }

import asyncio
import json
import logging
import time
from typing import Dict, List

import requests
import websockets

logger = logging.getLogger(__name__)

CLOB_WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"
CLOB_HOST = "https://clob.polymarket.com"

PriceTable = Dict[str, Dict[str, float]]

async def stream_market_prices(token_ids: List[str], table: PriceTable) -> None:
    """Subscribe to Polymarket's market WS and keep `table` in sync."""
    while True:
        try:
            async with websockets.connect(CLOB_WS_URL, ping_interval=20) as ws:
                await ws.send(json.dumps({
                    "type": "subscribe",
                    "channel": "market",
                    "assets_ids": token_ids,
                }))
                logger.info("Subscribed to %d token(s) on CLOB WS", len(token_ids))
                async for raw in ws:
                    payload = json.loads(raw)
                    events = payload if isinstance(payload, list) else [payload]
                    for evt in events:
                        _apply_event(evt, table)
        except (websockets.ConnectionClosed, OSError) as exc:
            logger.warning("CLOB WS dropped (%s); reconnecting in 5s", exc)
            await asyncio.sleep(5)

def _apply_event(evt: dict, table: PriceTable) -> None:
    tid = evt.get("asset_id")
    et = evt.get("event_type")
    if not tid:
        return
    row = table.setdefault(tid, {})

    if et == "book":
        # Polymarket's book event uses 'buys' and 'sells'; best is at [0].
        buys = evt.get("buys") or []
        sells = evt.get("sells") or []
        if buys:
            row["best_bid"] = float(buys[0]["price"])
        if sells:
            row["best_ask"] = float(sells[0]["price"])

    elif et == "price_change":
        # Each price_changes item carries best_bid/best_ask directly.
        # Skip items missing those, because individual order prices are noisy.
        for change in evt.get("price_changes", []):
            bb, ba = change.get("best_bid"), change.get("best_ask")
            if bb is None or ba is None:
                continue
            try:
                bb_f, ba_f = float(bb), float(ba)
            except (TypeError, ValueError):
                continue
            if 0 <= bb_f <= 1 and 0 <= ba_f <= 1:
                row["best_bid"], row["best_ask"] = bb_f, ba_f

    elif et == "last_trade_price":
        try:
            row["last_trade"] = float(evt.get("price", 0))
        except (TypeError, ValueError):
            pass

    if "best_bid" in row and "best_ask" in row:
        row["mid"] = (row["best_bid"] + row["best_ask"]) / 2.0
    row["ts"] = time.time()

async def poll_book_fallback(token_id: str, table: PriceTable, interval_s: float = 3.0) -> None:
    """Poll /book as a safety net when the WS is silent."""
    while True:
        try:
            r = requests.get(
                f"{CLOB_HOST}/book",
                params={"token_id": token_id},
                timeout=5,
            )
            r.raise_for_status()
            book = r.json()
            row = table.setdefault(token_id, {})
            stale = (time.time() - row.get("ts", 0)) > interval_s
            if stale:
                # /book historically uses bids/asks; some proxies relay buys/sells.
                buys = book.get("bids") or book.get("buys") or []
                sells = book.get("asks") or book.get("sells") or []
                if buys:
                    row["best_bid"] = float(buys[0]["price"])
                if sells:
                    row["best_ask"] = float(sells[0]["price"])
                if "best_bid" in row and "best_ask" in row:
                    row["mid"] = (row["best_bid"] + row["best_ask"]) / 2.0
                    row["ts"] = time.time()
        except Exception as exc:
            logger.debug("book poll for %s failed: %s", token_id[:10], exc)
        await asyncio.sleep(interval_s)

def snapshot(table: PriceTable, market: dict) -> dict:
    """Build a per-cycle snapshot keyed by UP/DOWN."""
    up = table.get(market["up_token_id"], {})
    down = table.get(market["down_token_id"], {})
    keys = ("best_bid", "best_ask", "mid", "last_trade")
    return {
        "slug": market["slug"],
        "up": {k: up.get(k) for k in keys},
        "down": {k: down.get(k) for k in keys},
    }

import asyncio

from utils import get_active_btc_15m_market
from prices import stream_market_prices, poll_book_fallback, snapshot

async def watch_current_market() -> None:
    market = get_active_btc_15m_market()
    if market is None:
        raise RuntimeError(
            "No active BTC 15M market right now. Gamma may briefly lag the "
            "cycle boundary; retry in a few seconds."
        )

    table: dict = {}
    tasks = [
        asyncio.create_task(stream_market_prices(
            [market["up_token_id"], market["down_token_id"]],
            table,
        )),
        asyncio.create_task(poll_book_fallback(market["up_token_id"], table)),
        asyncio.create_task(poll_book_fallback(market["down_token_id"], table)),
    ]

    for _ in range(15):  # 30 seconds of live updates
        await asyncio.sleep(2)
        print(snapshot(table, market))

    for t in tasks:
        t.cancel()

if __name__ == "__main__":
    asyncio.run(watch_current_market())

import json
import os
import threading
import time
from collections import deque
from websocket import WebSocketApp

from utils import get_logger

logger = get_logger(__name__)

RTDS_URL = "wss://ws-live-data.polymarket.com"
COINBASE_URL = "wss://advanced-trade-ws.coinbase.com"

# Shared price state. Two WebSocket threads write here; the signal loop reads.
_lock = threading.Lock()
_history: "deque[tuple[float, float]]" = deque()   # (price, ts)
_latest_price: float | None = None
_active_source: str = "(none)"
_rtds_alive = threading.Event()
STARTUP_TIMEOUT_S = 15
_HISTORY_MAX_AGE_S = 1800

def _push_tick(price: float, source: str) -> None:
    global _latest_price, _active_source
    now = time.time()
    with _lock:
        _latest_price = price
        _active_source = source
        _history.append((price, now))
        cutoff = now - _HISTORY_MAX_AGE_S
        while _history and _history[0][1] < cutoff:
            _history.popleft()

def get_latest_price() -> float | None:
    with _lock:
        return _latest_price

def get_price_delta_pct(lookback_seconds: int = 900) -> float | None:
    now = time.time()
    cutoff = now - lookback_seconds
    with _lock:
        if not _history:
            return None
        old = [(p, ts) for p, ts in _history if ts <= cutoff]
        if not old:
            return None
        return ((_history[-1][0] - old[-1][0]) / old[-1][0]) * 100

# ---- RTDS (Chainlink) , primary ----
def _rtds_run() -> None:
    def _on_open(ws):
        sub = {"action": "subscribe", "subscriptions": [{
            "topic": "crypto_prices_chainlink", "type": "*",
            "filters": json.dumps({"symbol": "btc/usd"}),
        }]}
        ws.send(json.dumps(sub))
        # RTDS keep-alive: send the literal text PING every 5 seconds.
        def _ping():
            while ws.keep_running:
                try: ws.send("PING")
                except Exception: return
                time.sleep(5)
        threading.Thread(target=_ping, daemon=True).start()
        logger.info("RTDS subscribed: crypto_prices_chainlink btc/usd")

    def _on_message(_ws, raw):
        if raw == "PONG": return
        try: msg = json.loads(raw)
        except Exception: return
        if msg.get("topic") != "crypto_prices_chainlink": return
        v = (msg.get("payload") or {}).get("value")
        if v is None: return
        _push_tick(float(v), "rtds-chainlink")
        if not _rtds_alive.is_set():
            _rtds_alive.set()
            logger.info(f"RTDS first BTC tick: ${float(v):,.2f}")

    while True:
        ws = WebSocketApp(RTDS_URL, on_open=_on_open, on_message=_on_message)
        ws.run_forever(ping_interval=0)
        logger.warning("RTDS disconnected; reconnect in 2s")
        time.sleep(2)

# ---- Coinbase , fallback ----
def _coinbase_run() -> None:
    def _on_open(ws):
        ws.send(json.dumps({
            "type": "subscribe", "product_ids": ["BTC-USD"], "channel": "ticker",
        }))
        logger.info("Coinbase WS subscribed: ticker BTC-USD")

    def _on_message(_ws, raw):
        try: msg = json.loads(raw)
        except Exception: return
        if msg.get("channel") != "ticker": return
        for ev in msg.get("events", []):
            for t in ev.get("tickers", []):
                if t.get("product_id") == "BTC-USD":
                    _push_tick(float(t["price"]), "coinbase")

    while True:
        ws = WebSocketApp(COINBASE_URL, on_open=_on_open, on_message=_on_message)
        ws.run_forever(ping_interval=20, ping_timeout=10)
        logger.warning("Coinbase WS disconnected; reconnect in 2s")
        time.sleep(2)

def start_price_feed() -> None:
    """Start RTDS Chainlink (primary). Fall over to Coinbase if RTDS is silent
    for STARTUP_TIMEOUT_S. RTDS continues retrying in the background and becomes
    the active source again once it recovers."""
    threading.Thread(target=_rtds_run, daemon=True).start()
    def _watch():
        if _rtds_alive.wait(timeout=STARTUP_TIMEOUT_S):
            return
        logger.warning(f"RTDS silent for {STARTUP_TIMEOUT_S}s , failing over to Coinbase")
        threading.Thread(target=_coinbase_run, daemon=True).start()
    threading.Thread(target=_watch, daemon=True).start()
    logger.info("Price feed: RTDS Chainlink primary, Coinbase ready for failover")

from dataclasses import dataclass

@dataclass
class Signal:
    direction: str        # 'UP' or 'DOWN'
    confidence: float     # 0.0 to 1.0
    up_mid: float        # current UP market price
    price_delta_pct: float

# Tunable thresholds , adjust based on backtesting
MOMENTUM_THRESHOLD_PCT = 0.15   # BTC must have moved at least 0.15% in 15 min
EDGE_THRESHOLD = 0.05       # We need at least 5% edge vs market price
MIN_CONFIDENCE = 0.55           # Don't trade below this confidence

def generate_signal(up_mid: float) -> Signal | None:
    """
    Generate a UP/DOWN trading signal for the BTC Up/Down 15M market.
    Returns None if no tradeable edge is detected.
    """
    delta = get_price_delta_pct(lookback_seconds=900)
    if delta is None:
        logger.info("Insufficient price history , skipping signal")
        return None

    if delta > MOMENTUM_THRESHOLD_PCT:
        # BTC is rising , UP is more likely than the market implies
        implied_up_prob = up_mid
        our_up_prob = min(0.95, implied_up_prob + abs(delta) * 0.1)
        edge = our_up_prob - implied_up_prob
        if edge >= EDGE_THRESHOLD:
            confidence = min(1.0, 0.5 + edge)
            if confidence >= MIN_CONFIDENCE:
                return Signal("UP", confidence, up_mid, delta)

    elif delta < -MOMENTUM_THRESHOLD_PCT:
        # BTC is falling , DOWN is more likely
        implied_down_prob = 1.0 - up_mid
        our_down_prob = min(0.95, implied_down_prob + abs(delta) * 0.1)
        edge = our_down_prob - implied_down_prob
        if edge >= EDGE_THRESHOLD:
            confidence = min(1.0, 0.5 + edge)
            if confidence >= MIN_CONFIDENCE:
                return Signal("DOWN", confidence, up_mid, delta)

    logger.info(f"No edge detected. delta={delta:.3f}%, up_mid={up_mid:.3f}")
    return None

from py_clob_client_v2 import ClobClient
from py_clob_client_v2 import OrderArgs, OrderType
from py_clob_client_v2 import BUY
from signal_engine import Signal
from utils import get_logger
import math

logger = get_logger(__name__)

def round_to_tick(price: float, tick: float = 0.01) -> float:
    """Round price to the nearest valid tick size."""
    return round(math.floor(price / tick) * tick, 10)

def place_limit_order(
    client: ClobClient,
    signal: Signal,
    market: dict,
    size_pusd: float,
) -> dict | None:
    """
    Place a limit order based on the signal direction.
    Returns the order response dict or None on failure.
    """
    token_id = (
        market["up_token_id"] if signal.direction == "UP"
        else market["down_token_id"]
    )
    # For UP: buy at or just below the ask to get filled quickly
    # For DOWN: the DOWN price is 1 - up_mid
    if signal.direction == "UP":
        limit_price = round_to_tick(signal.up_mid + 0.01)
    else:
        limit_price = round_to_tick((1.0 - signal.up_mid) + 0.01)

    limit_price = min(limit_price, 0.99)  # Never pay more than $0.99

    order_args = OrderArgs(
        token_id=token_id,
        price=limit_price,
        size=round(size_pusd, 2),
        side=BUY,
    )
    try:
        resp = client.create_and_post_order(order_args)
        logger.info(
            f"Order placed: {signal.direction} @ {limit_price} "
            f"size={size_pusd} order_id={resp.get('orderID')}"
        )
        return resp
    except Exception as e:
        logger.error(f"Order placement failed: {e}")
        return None

import time

def poll_order_status(client: ClobClient, order_id: str, timeout_seconds: int = 60) -> str:
    """
    Poll until order is FILLED, CANCELLED, or timeout is reached.
    Returns the final status string.
    """
    start = time.time()
    while time.time() - start < timeout_seconds:
        try:
            order = client.get_order(order_id)
            status = order.get("status", "UNKNOWN")
            logger.debug(f"Order {order_id} status: {status}")
            if status in ("MATCHED", "FILLED"):
                logger.info(f"Order {order_id} filled.")
                return "FILLED"
            if status in ("CANCELLED", "EXPIRED"):
                logger.info(f"Order {order_id} cancelled/expired.")
                return "CANCELLED"
        except Exception as e:
            logger.warning(f"Status poll error: {e}")
        time.sleep(5)
    logger.warning(f"Order {order_id} timed out , cancelling.")
    cancel_order(client, order_id)
    return "TIMEOUT"

def cancel_order(client: ClobClient, order_id: str) -> bool:
    """Cancel a specific open order. Returns True on success."""
    try:
        client.cancel(order_id)
        logger.info(f"Order {order_id} cancelled.")
        return True
    except Exception as e:
        logger.error(f"Cancel failed for {order_id}: {e}")
        return False

from utils import get_logger
import time

logger = get_logger(__name__)

class RiskManager:
    def __init__(
        self,
        starting_bankroll: float,
        kelly_fraction: float = 0.25,
        max_open_exposure_pct: float = 0.15,
        daily_loss_limit_pct: float = 0.07,
        min_trade_pusd: float = 1.0,
        max_trade_pusd: float = 50.0,
    ):
        self.starting_bankroll = starting_bankroll
        self.current_bankroll = starting_bankroll
        self.kelly_fraction = kelly_fraction
        self.max_open_exposure = starting_bankroll * max_open_exposure_pct
        self.daily_loss_limit = starting_bankroll * daily_loss_limit_pct
        self.min_trade_pusd = min_trade_pusd
        self.max_trade_pusd = max_trade_pusd
        self.daily_pnl = 0.0
        self.day_start = time.strftime("%Y-%m-%d")
        self.open_exposure = 0.0
        self.circuit_open = False

    def _reset_daily_if_needed(self):
        today = time.strftime("%Y-%m-%d")
        if today != self.day_start:
            logger.info(f"New day. Resetting daily PnL. Previous: {self.daily_pnl:.2f}")
            self.daily_pnl = 0.0
            self.day_start = today
            self.circuit_open = False

    def kelly_size(self, edge: float, odds: float) -> float:
        """Calculate fractional Kelly bet size in pUSD."""
        if odds <= 0 or edge <= 0:
            return 0.0
        full_kelly = self.current_bankroll * (edge / odds)
        size = full_kelly * self.kelly_fraction
        return max(self.min_trade_pusd, min(size, self.max_trade_pusd))

    def can_trade(self, proposed_size: float) -> tuple[bool, str]:
        """Returns (True, '') if trade is allowed, else (False, reason)."""
        self._reset_daily_if_needed()
        if self.circuit_open:
            return False, "Daily loss circuit-breaker is open"
        if self.daily_pnl <= -self.daily_loss_limit:
            self.circuit_open = True
            logger.warning("Daily loss limit hit. Circuit-breaker opened.")
            return False, "Daily loss limit reached"
        if self.open_exposure + proposed_size > self.max_open_exposure:
            return False, f"Open exposure cap reached ({self.open_exposure:.2f} open)"
        return True, ""

    def record_trade_open(self, size: float):
        self.open_exposure += size
        logger.info(f"Trade opened. Open exposure: {self.open_exposure:.2f}")

    def record_trade_close(self, size: float, pnl: float):
        self.open_exposure = max(0.0, self.open_exposure - size)
        self.daily_pnl += pnl
        self.current_bankroll += pnl
        logger.info(f"Trade closed. PnL: {pnl:.2f}. Daily PnL: {self.daily_pnl:.2f}")

import schedule
import time
import signal as sys_signal
import sys
# build_client and run_trading_cycle are defined in this file (added in Steps 3 and 6).
from risk import RiskManager
from utils import get_logger, get_active_btc_15m_market

logger = get_logger("main")

# Global shutdown flag
_shutdown = False

def handle_shutdown(signum, frame):
    global _shutdown
    logger.info("Shutdown signal received. Finishing current cycle...")
    _shutdown = True

def main():
    global _shutdown
    # Register SIGINT and SIGTERM handlers for clean shutdown
    sys_signal.signal(sys_signal.SIGINT, handle_shutdown)
    sys_signal.signal(sys_signal.SIGTERM, handle_shutdown)

    logger.info("=== Polymarket BTC 15M Bot Starting ===")

    client = build_client()
    risk = RiskManager(
        starting_bankroll=50.0, # Adjust to your actual pUSD balance
        kelly_fraction=0.10, # Conservative for first run
        daily_loss_limit_pct=0.05,
    )

    def cycle():
        if _shutdown:
            return
        try:
            market = get_active_btc_15m_market()
            if market is None:
                logger.warning("No active BTC 15M market found. Skipping cycle.")
                return
            logger.info(f"Cycle start. Market: {market['question']}")
            run_trading_cycle(client, risk, market)
        except Exception as e:
            logger.error(f"Unhandled error in cycle: {e}", exc_info=True)

    # Run immediately on start, then every 15 minutes
    cycle()
    schedule.every(15).minutes.do(cycle)

    logger.info("Scheduler running. Press Ctrl+C to stop.")
    while not _shutdown:
        schedule.run_pending()
        time.sleep(10)  # Check every 10 seconds

    logger.info("Bot shut down cleanly.")
    sys.exit(0)

if __name__ == "__main__":
    main()

[Unit]
Description=Polymarket BTC 15M Trading Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/polymarket-btc-bot
ExecStart=/home/ubuntu/polymarket-btc-bot/venv/bin/python main.py
Restart=on-failure
RestartSec=30
StandardOutput=journal
StandardError=journal
EnvironmentFile=/home/ubuntu/polymarket-btc-bot/.env

[Install]
WantedBy=multi-user.target

import os
import csv
from datetime import datetime, timezone

PAPER_TRADING = os.getenv("PAPER_TRADING", "false").lower() == "true"
PAPER_LOG_FILE = "paper_trades.csv"

def place_limit_order(client, signal, market, size_pusd):
    if PAPER_TRADING:
        simulated_fill_price = signal.up_mid if signal.direction == "UP" else (1 - signal.up_mid)
        simulated_pnl_if_correct = size_pusd * (1 - simulated_fill_price) / simulated_fill_price
        row = {
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "direction": signal.direction,
            "fill_price": simulated_fill_price,
            "size_pusd": size_pusd,
            "confidence": signal.confidence,
            "price_delta_pct": signal.price_delta_pct,
            "potential_pnl": round(simulated_pnl_if_correct, 4),
            "market": market["question"],
        }
        _append_paper_log(row)
        logger.info(f"[PAPER] Simulated {signal.direction} fill @ {simulated_fill_price:.3f}")
        return {"orderID": "PAPER-" + datetime.now().strftime("%H%M%S"), "status": "FILLED"}
    # ... real order placement code below ...

def _append_paper_log(row: dict):
    file_exists = os.path.exists(PAPER_LOG_FILE)
    with open(PAPER_LOG_FILE, "a", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=row.keys())
        if not file_exists:
            writer.writeheader()
        writer.writerow(row)