Polymarket Trading Bot

Autonomous trading agent for prediction markets integrating the Seren ecosystem.

⚠️ IMPORTANT LEGAL DISCLAIMERS

READ THIS BEFORE USING

Geographic Restrictions - CRITICAL

⚠️ Polymarket access depends on jurisdiction, account eligibility, and current network environment. ⚠️ You are responsible for verifying that prediction market trading is legal in your jurisdiction.

Regulatory Status

Prediction markets exist in a regulatory gray area in many jurisdictions
Some governments classify them as gambling, others as financial instruments
Some jurisdictions prohibit them entirely
Consult local laws and seek professional advice if uncertain

Not Financial Advice

This bot is provided for informational and educational purposes only
It does NOT constitute financial, investment, legal, or tax advice
AI-generated estimates are not guarantees and may be inaccurate
You are solely responsible for your trading decisions and any resulting gains or losses

Risk of Loss

Trading prediction markets involves substantial risk of loss
Only risk capital you can afford to lose completely
Past performance does not indicate future results
Market conditions can change rapidly and unpredictably

Tax Obligations

Trading profits may be subject to taxation in your jurisdiction
Consult a tax professional regarding your reporting obligations

Age Restriction

You must be at least 18 years old (or the age of majority in your jurisdiction) to use this bot

No Warranty

This software is provided "as is" without warranty of any kind
The developers assume no liability for trading losses, technical failures, or regulatory consequences

When to Use This Skill

Activate this skill when the user mentions:

"trade on Polymarket"
"set up polymarket trading"
"start prediction market trading"
"check my polymarket positions"
"autonomous trading"

For Claude: How to Invoke This Skill

Immediately run a dry-run scan without asking. Do not present a menu or ask the user to choose between scan/trade/setup. Execute the paper scan by default. Only after results are displayed, present available next steps (live trading setup, position management). If the user explicitly requests a specific action in their invocation message, run that action instead.

When the user asks to scan Polymarket or find trading opportunities, run the bot:

Prerequisites Check

First, verify the skill is set up:

ls ~/.config/seren/skills/polymarket-bot/.env ~/.config/seren/skills/polymarket-bot/config.json

If files are missing, guide user through setup (see Phase 1-2 below).

Scanning for Opportunities (Paper Trading)

Run a single scan to find mispriced markets:

cd ~/.config/seren/skills/polymarket-bot && python3 scripts/agent.py --config config.json --dry-run 2>&1

What this does:

Scans 20-50 active Polymarket markets
Uses Perplexity to research each market
Uses Claude to estimate fair values
Identifies opportunities where edge > threshold
Calculates Kelly position sizes
Does NOT place actual trades (dry-run mode)
Costs ~$1 in SerenBucks per scan

How to present results to user:

Parse output for lines starting with ✓ Opportunity found!
Extract: market question, fair value, market price, edge, recommended position size
Summarize in a table format:

Found 3 opportunities:

| Market | Fair Value | Market Price | Edge | Position |
|--------|-----------|--------------|------|----------|
| "Will BTC hit $100k?" | 67% | 54% | 13% | $15.20 |
| "Trump wins 2024?" | 48% | 55% | -7% | $8.40 SELL |

Remind user these are paper trades - no real orders placed
Suggest running setup if they want to enable live trading

Checking Paper Trading History

View recent scan logs:

tail -50 ~/.config/seren/skills/polymarket-bot/logs/trading_*.log

Running Live Trading (Advanced)

⚠️ Only if user has:

Completed paper trading validation (50+ scans)
$100+ budget ($75 USDC + $25 SerenBucks)
Real Polymarket API credentials

cd ~/.config/seren/skills/polymarket-bot && python3 scripts/setup_cron.py create --config config.json --schedule "0 */2 * * *" --live --run-type scan
cd ~/.config/seren/skills/polymarket-bot && python3 scripts/setup_cron.py create --config config.json --schedule "15 * * * *" --live --run-type monitor

Then start the local-pull runner on the machine that should execute jobs:

python3 scripts/run_local_pull_runner.py --config config.json

Important:

Always confirm user has adequate budget before suggesting live mode
Emphasize paper trading first
Live trading requires a schedule created with --live

Trade Execution Contract

When the user gives a direct exit instruction (sell, close, exit, unwind, flatten), execute the exit path immediately. Do not editorialize or argue against recovering remaining funds. If the user request is ambiguous, ask only the minimum clarifying question needed to identify the positions to exit.

CLOB Execution Rules

py-clob-client via DirectClobTrader from scripts/polymarket_live.py is the canonical live execution path.
For immediate sells, fetch the live order book, use the market tick_size, and submit a marketable sell priced at that market's minimum tick.
Never place a passive sell above the best bid when the user asked for an immediate exit.
Estimate recovery by sweeping visible bid levels (price x size) across the full book, not just the best bid.
If visible bid depth cannot cover the full exit size, report the partial-depth estimate and remaining unfilled size.

Pre-Trade Checklist (Mandatory)

Before any live buy, sell, or unwind:

Fetch the live order book for every token involved.
Snap prices to the market tick_size and compute visible-book recovery or cost across all levels.
Verify the current environment can legally and technically reach the Polymarket CLOB API. If access is blocked, stop and report the restriction; do not suggest bypasses.
Verify py-clob-client is installed and POLY_PRIVATE_KEY or WALLET_PRIVATE_KEY, POLY_API_KEY, POLY_PASSPHRASE, and POLY_SECRET are loaded.
If any dependency check fails, fail closed with a concrete remediation message.

Live Safety Opt-In

Default mode should be --dry-run. Live trading requires:

python scripts/agent.py --config config.json --yes-live
or a wrapper that omits --dry-run and sets --yes-live for that process

The --yes-live flag is a startup-only live opt-in. It is not a per-order approval prompt.

Overview

This skill helps users set up and manage an autonomous trading agent that:

Scans Polymarket for active prediction markets
Researches opportunities using Perplexity AI
Estimates fair value with Claude (Anthropic)
Identifies mispriced markets (edge > threshold)
Executes trades using Kelly Criterion for position sizing
Runs autonomously on seren-cron schedule
Monitors positions and reports P&L

Architecture

Pure Python Implementation

Python agent calls Seren publishers via HTTP
Desktop sidecar/keychain publisher auth is the default path
Legacy direct POLY_* headers remain as fallback
Logs written to JSONL files
Seren-cron stores the schedule and a skill-local runner executes scripts/agent.py locally

Components:

scripts/agent.py - Main trading loop
scripts/seren_client.py - Seren API client (calls publishers)
scripts/polymarket_client.py - Polymarket CLOB API wrapper
scripts/setup_cron.py - skill-local seren-cron local-pull schedule management
scripts/run_local_pull_runner.py - local seren-cron polling runner
scripts/kelly.py - Position sizing calculator
scripts/position_tracker.py - Position management
scripts/logger.py - Trading logger

Seren Publishers Used:

polymarket-data - Real-time Polymarket market data (prices, volumes, liquidity)
- Endpoint: GET /markets returns active prediction markets
- Response includes: market IDs, questions, token IDs, prices, liquidity
- Verified working with 100+ markets returned
Trading uses py-clob-client (via DirectClobTrader from scripts/polymarket_live.py)
- Local EIP-712 signing — no publisher intermediary
- Requires: POLY_PRIVATE_KEY, POLY_API_KEY, POLY_PASSPHRASE, POLY_SECRET
perplexity - Perplexity AI research (via OpenRouter)
- Model: sonar for fast research
- Returns AI-generated summaries with citations
- Used to research market questions before trading
seren-models - Multi-model LLM inference (via OpenRouter)
- 200+ models available (Claude, GPT, Gemini, Llama, etc.)
- Used model: anthropic/claude-sonnet-4.5
- Estimates fair value probabilities from research
seren-cron - Autonomous local-pull scheduling
- Stores runner registration and cron schedules in Seren
- Lets a skill-local polling process claim due work and run scripts/agent.py locally
- Pause/resume/delete jobs and runners programmatically

API Key Setup

Before running this skill, check for an existing Seren API key in this order:

Seren Desktop auth — if the skill is running inside Seren Desktop, the runtime injects API_KEY automatically. Check: echo $API_KEY. If set, no further action is needed.
Existing .env file — check if SEREN_API_KEY is already set in the skill's .env file. If set, no further action is needed.
Shell environment — check if SEREN_API_KEY is exported in the current shell. If set, no further action is needed.

Only if none of the above are set, register a new agent account:

curl -sS -X POST "https://api.serendb.com/auth/agent" \
  -H "Content-Type: application/json" \
  -d '{"name":"polymarket-bot"}'

Extract the API key from the response at .data.agent.api_key — this key is shown only once. Write it to the skill's .env file:

SEREN_API_KEY=<the-returned-key>

Verify:

curl -sS "https://api.serendb.com/auth/me" \
  -H "Authorization: Bearer $SEREN_API_KEY"

Do not create a new account if a key already exists. Creating a duplicate account results in a $0-balance key that overrides the user's funded account.

Reference: https://docs.serendb.com/skills.md

Setup Workflow

Phase 1: Install Dependencies

Check Python version and install requirements:

cd skills/polymarket-bot

# Check Python version (need 3.9+)
python3 --version

# Install dependencies
pip3 install -r requirements.txt

Phase 2: Configure Credentials

Create .env file from template:

cp .env.example .env

Edit .env and add:

# Seren API key (standalone mode) - create/manage from https://console.serendb.com
SEREN_API_KEY=your_seren_api_key_here

# Desktop sidecar/keychain mode (recommended)
SEREN_DESKTOP_PUBLISHER_AUTH=true

Desktop sidecar flow (recommended):

Open Seren Desktop
Go to Settings > Publisher MCPs
Configure Polymarket publisher credentials
Ensure publisher is enabled

Legacy fallback mode (optional): Set SEREN_DESKTOP_PUBLISHER_AUTH=false and provide: POLY_API_KEY, POLY_PASSPHRASE, POLY_SECRET, POLY_ADDRESS

How to derive Polymarket credentials (legacy mode):

Visit polymarket.com
Connect your wallet
Navigate to Settings > API Keys
Click "Derive API Key"
Save your credentials securely

Security Note:

Never commit .env to git (already in .gitignore)
Keep credentials secure
Credentials grant access to your Polymarket wallet

Phase 3: Configure Risk Parameters

Copy the example config and customize:

cp config.example.json config.json

Edit config.json to set your risk parameters:

{
  "bankroll": 100.0,
  "mispricing_threshold": 0.08,
  "max_kelly_fraction": 0.06,
  "scan_interval_minutes": 10,
  "max_positions": 10,
  "stop_loss_bankroll": 0.0
}

Parameter Guide:

bankroll

Total capital available for trading (in USDC).

Testing: $50-100
Serious: $500+
Only risk what you can afford to lose

mispricing_threshold

Minimum edge required to trade (as decimal, e.g., 0.08 = 8%).

0.05: Aggressive (more trades, smaller edges)
0.08: Balanced (recommended)
0.12: Conservative (fewer trades, larger edges)

max_kelly_fraction

Maximum % of bankroll per trade (as decimal, e.g., 0.06 = 6%).

0.03: Very conservative
0.06: Balanced (recommended)
0.10: Aggressive (higher variance)

scan_interval_minutes

How often to scan for opportunities.

5 minutes: High frequency (~$5-10/day in API costs)
10 minutes: Balanced (~$2-5/day)
30 minutes: Conservative (~$0.50-1.50/day)

max_positions

Maximum concurrent open positions.

Small bankroll (<$100): 5-10
Medium bankroll ($100-500): 10-20
Large bankroll (>$500): 20-50

stop_loss_bankroll

Stop trading if bankroll drops to this amount.

0: Stop only if completely depleted
50% of initial: Stop if down 50%

Phase 4: Fund Your Wallets

Minimum Starting Budget: $100

The config default bankroll is $100. Start small to test the strategy with real capital before scaling up.

Item	Amount	Purpose
Polygon USDC	$75	Trading capital (allows $3-6 positions)
SerenBucks	$25	API costs (~25 scans at ~$1/scan)
Total	$100	Minimum to start live trading

With a $100 bankroll and quarter-Kelly sizing (max_kelly_fraction: 0.06):

Position sizes: $3-6 each
At lower scan frequency (1-2 scans/day), API costs stay at $1-2/day
Enough runway to validate whether the strategy finds real edge before committing more capital

The key variable is scan frequency, not bankroll size. Reduce scan_interval_minutes to control API costs:

Scan interval	Scans/day	API cost/day	Best for
Manual/daily	1-2	$1-2	Testing with $100 budget
120 min	12	$12	Active trading with $500+ budget
60 min	24	$24	Experienced traders scaling up
30 min	48	$48	High conviction, large bankroll

Scaling Up

Once you have validated edge through paper trading and small live trades, increase your bankroll and scan frequency together:

Budget tier	USDC	SerenBucks	Recommended scan interval
Starter	$75	$25	Manual or daily
Active	$500	$50-100	120 min
Experienced	$1,000+	$100-200	60 min
Serious	$2,000+	$200+	30 min

Paper Trading (RECOMMENDED FOR EVERYONE)

Before deploying real capital, paper trade for 1-2 weeks to validate your edge.

Paper trading uses real market data and real AI analysis, but simulates trades instead of placing actual orders. This lets you:

Validate the strategy actually finds mispriced markets
Measure real win rate and average edge
Test different risk parameters (Kelly fraction, mispricing threshold)
Build confidence before risking capital

How to paper trade:

python3 scripts/agent.py --config config.json --dry-run

What happens in dry-run mode:

✅ Scans real Polymarket markets
✅ Researches opportunities with Perplexity (real API calls)
✅ Estimates fair values with Claude (real API calls)
✅ Calculates Kelly position sizes
✅ Logs paper trades to logs/trading_*.log
❌ Does NOT place actual Polymarket orders
❌ Does NOT require Polymarket API credentials

Important: Paper trading still costs ~$1 per scan in API fees (Perplexly + Claude analysis). With $25 SerenBucks, you can run 25 paper trades over 1-2 weeks to validate the strategy.

Recommended paper trading plan:

Fund $25 SerenBucks (covers ~25 scans)
Set "scan_interval_minutes": 120 in config.json (2-hour intervals)
Run paper trading for 5-7 days (60-84 scans)
Analyze results in log files:
- Win rate: % of paper trades that would have been profitable
- Average edge: mean expected value per trade
- Sharpe ratio: risk-adjusted returns
If paper trading shows consistent edge, move to live trading with $100+ budget

Manual paper trading (if <$25 SerenBucks):

Run scans one at a time when you want:

python3 scripts/agent.py --config config.json --dry-run --once

You control when to spend API credits ($1 per scan)
With $20 SerenBucks: run 20 scans over weeks/months
Scout for opportunities at your own pace
No autonomous scheduling

Moving from Paper to Live Trading

Once paper trading validates your edge (recommended: 50+ scans with positive expected value), you're ready for live trading.

Requirements for live trading:

✅ Successful paper trading period (1-2 weeks, 50+ scans)
✅ Minimum $100 budget ($75 USDC + $25 SerenBucks)
✅ Polymarket API credentials (see Phase 2)
✅ Understanding of Kelly Criterion risk management

If you don't have $100 yet:

Continue paper trading to refine strategy
Use manual --once scans to conserve SerenBucks
Start with the minimum $5 Stripe deposit to test a few scans

How to Fund SerenBucks

Visit: https://serendb.com/serenbucks or https://console.serendb.com
Choose deposit method:
- Credit card (instant)
- Crypto transfer (USDC, ETH, BTC)
Minimum recommended: $25 for getting started

Current Seren funding flow:

Stripe deposits start at $5
A verified email is required before Stripe deposits
API-first users can fund with POST /wallet/deposit

Cost breakdown per scan cycle (~$1.00 total):

Market data fetch: $0.10
Perplexity research: $0.01 × 20 markets = $0.20
Claude fair value estimation: $0.035 × 20 markets = $0.70

Daily costs by scan interval:

30 min intervals: 48 scans/day × $1.00 = $48/day
60 min intervals: 24 scans/day × $1.00 = $24/day
120 min intervals: 12 scans/day × $1.00 = $12/day

How to Fund Polymarket (Polygon USDC)

Bridge USDC to Polygon PoS using:
- Polygon Bridge (official)
- Hop Exchange (faster)
- Connext (alternative)
Send to your Polymarket wallet address:
- Find your address: https://polymarket.com/wallet
- Send bridged USDC to this address
- Wait for confirmation (~2-5 minutes)
Verify balance:
- Check on Polymarket: https://polymarket.com/wallet
- Or check on PolygonScan: https://polygonscan.com/address/YOUR_ADDRESS

Trading capital recommendations:

Minimum: $20 (allows small positions for testing)
Conservative: $50-100 (better position sizing)
Serious: $500+ (optimal Kelly Criterion sizing)

Checking Your Balances

Before running the bot, verify both balances:

Check SerenBucks:

# If you have Seren MCP connected
# The bot will display balance when it starts

Check Polymarket USDC:

Visit: https://polymarket.com/wallet
Or the bot will show balance at startup

Phase 5: Dry-Run Test (STRONGLY RECOMMENDED)

Test the bot without placing real trades:

python3 scripts/agent.py --config config.json --dry-run

Dry-run mode:

✅ Scans markets (when implemented)
✅ Researches opportunities using Perplexity
✅ Estimates fair values using Claude
✅ Calculates position sizes using Kelly Criterion
✅ Logs everything to files
❌ Does NOT place actual trades

Expected output:

============================================================
🔍 Polymarket Scan Starting - 2026-02-12 14:35:00 UTC
============================================================

Balances:
  SerenBucks: $23.45
  Polymarket: $100.00

Scanning markets...
  Found 23 markets

Evaluating: "Will BTC hit $100k by March 2026?"
  Current price: 54.0%
  🧠 Researching: "Will BTC hit $100k by March 2026?"
  💡 Estimating fair value...
     Fair value: 67.0% (confidence: medium)
    ✓ Opportunity found!
      Edge: 13.0%
      Side: BUY
      Size: $3.24 (5.4% of available)
      Expected value: +$0.42

    [DRY-RUN] Would place BUY order:
      Market: "Will BTC hit $100k by March 2026?"
      Size: $3.24
      Price: 54.0%
      Expected value: +$0.42

============================================================
Scan complete!
  Markets scanned: 23
  Opportunities: 8
  Trades executed: 0 (dry-run)
  Capital deployed: $0.00
  API cost: ~$0.46 SerenBucks
============================================================

Phase 6: Live Trading Confirmation

⚠️ CRITICAL - You must explicitly confirm before enabling live trading

Before going live, ask yourself:

Have I tested in dry-run mode?
Do I understand the risks?
Can I afford to lose this capital?
Is prediction market trading legal in my jurisdiction?
Have I funded both SerenBucks and Polymarket?

Display this warning:

⚠️  LIVE TRADING CONFIRMATION

You're about to enable LIVE TRADING with real money.

Configuration:
  • Bankroll: $100.00
  • Max per trade: 6% ($6.00)
  • Scan interval: Every 10 minutes
  • Stop loss: $0.00 (stop when depleted)
  • Max positions: 10

Estimated Costs:
  • SerenBucks: ~$2-5 per day (for API calls)
  • Trading capital: Up to $100.00 (your bankroll)

Risks:
  ⚠️  You can lose money - prediction markets are uncertain
  ⚠️  Only risk what you can afford to lose
  ⚠️  Past performance doesn't guarantee future results
  ⚠️  The agent makes autonomous decisions based on AI estimates
  ⚠️  Market conditions can change rapidly
  ⚠️  Slippage and fees may reduce returns

The agent will run on schedule until you stop it.

Type exactly: START LIVE TRADING
(or 'cancel' to abort)

Wait for EXACT confirmation. Do not proceed unless user types "START LIVE TRADING".

Phase 7: Run Live

Once confirmed, run the agent:

# Run once
python3 scripts/agent.py --config config.json

# Or create a seren-cron local-pull schedule for autonomous operation

Setting up seren-cron (for autonomous scheduling):

python3 scripts/setup_cron.py create --config config.json --schedule "0 */2 * * *" --live --run-type scan
python3 scripts/setup_cron.py create --config config.json --schedule "15 * * * *" --live --run-type monitor
python3 scripts/run_local_pull_runner.py --config config.json

The schedule lives in Seren, but the local polling process must stay online on the machine that should execute trades. Use scan for new entries and monitor for stale-order cleanup, live reconciliation, and automated guard exits.

Control Commands

Show Status

Read current positions and display status:

import json

# Read positions
with open('skills/polymarket-bot/logs/positions.json', 'r') as f:
    data = json.load(f)

# Display
print("📊 Polymarket Trading Status\n")
print(f"Positions: {data['position_count']}")
print(f"Total unrealized P&L: ${data['total_unrealized_pnl']:.2f}")

for pos in data['positions']:
    pnl_symbol = '+' if pos['unrealized_pnl'] >= 0 else ''
    print(f"\n  {pos['market']}")
    print(f"  {pos['side']} ${pos['size']:.2f} @ {pos['entry_price'] * 100:.1f}%")
    print(f"  Now: {pos['current_price'] * 100:.1f}% ({pnl_symbol}${pos['unrealized_pnl']:.2f})")

Show Recent Trades

Read and display trade history:

import json

# Read last 20 trades
with open('skills/polymarket-bot/logs/trades.jsonl', 'r') as f:
    lines = f.readlines()

trades = [json.loads(line) for line in lines[-20:]]

print("📝 Recent Trades (Last 20)\n")

for i, trade in enumerate(reversed(trades), 1):
    pnl_symbol = '' if trade['pnl'] is None else ('+' if trade['pnl'] >= 0 else '')
    status_emoji = '🟢' if trade['status'] == 'open' else '✓' if trade['pnl'] and trade['pnl'] > 0 else '✗'

    print(f"{i}. {status_emoji} {trade['side']} ${trade['size']:.2f} @ {trade['price'] * 100:.1f}%")
    print(f"   \"{trade['market']}\"")
    if trade['pnl'] is not None:
        print(f"   P&L: {pnl_symbol}${trade['pnl']:.2f}")
    print()

Pause/Resume Trading

Pause (stop scheduled scans, keep positions):

python3 scripts/setup_cron.py pause --job-id <job_id>

Resume:

python3 scripts/setup_cron.py resume --job-id <job_id>

Stop Trading

Stop completely (delete the cron job):

python3 scripts/setup_cron.py delete --job-id <job_id>

Monitoring & Logs

All activity is logged to JSONL files in logs/:

trades.jsonl

One line per trade (opened or closed):

{"timestamp": "2026-02-12T14:35:00Z", "market": "Will BTC hit $100k by March?", "market_id": "0x123...", "side": "BUY", "size": 3.24, "price": 0.54, "fair_value": 0.67, "edge": 0.13, "status": "open", "pnl": null}

scan_results.jsonl

One line per scan cycle:

{"timestamp": "2026-02-12T14:35:00Z", "dry_run": false, "markets_scanned": 500, "opportunities_found": 23, "trades_executed": 3, "capital_deployed": 9.45, "api_cost": 1.12, "serenbucks_balance": 48.88, "polymarket_balance": 103.45}

positions.json

Current state (updated after each trade):

{
  "positions": [
    {
      "market": "Will BTC hit $100k by March?",
      "market_id": "0x123...",
      "token_id": "0x456...",
      "side": "BUY",
      "entry_price": 0.54,
      "current_price": 0.58,
      "size": 3.24,
      "unrealized_pnl": 0.84,
      "opened_at": "2026-02-12T14:35:00Z"
    }
  ],
  "total_unrealized_pnl": 0.84,
  "position_count": 1,
  "last_updated": "2026-02-12T18:00:00Z"
}

notifications.jsonl

Critical events for user notification:

{"timestamp": "2026-02-12T15:00:00Z", "level": "warning", "title": "Low SerenBucks Balance", "message": "Current: $1.23, Recommended: $20.00"}

How It Works (Technical Details)

Fair Value Estimation

The bot uses Claude to estimate true probabilities:

def estimate_fair_value(market_question, current_price, research):
    prompt = f"""You are an expert analyst estimating the true probability of prediction market outcomes.

Market Question: {market_question}

Current Market Price: {current_price * 100:.1f}%

Research Summary:
{research}

Based on the research and your analysis, estimate the TRUE probability of this outcome occurring.

Provide your response in this exact format:
PROBABILITY: [number between 0 and 100]
CONFIDENCE: [low, medium, or high]
REASONING: [brief explanation]"""

    # Call Claude via seren-models
    response = seren.call_publisher(
        publisher='seren-models',
        method='POST',
        path='/chat/completions',
        body={
            'model': 'anthropic/claude-sonnet-4-20250514',
            'messages': [{'role': 'user', 'content': prompt}],
            'temperature': 0.3
        }
    )

    # Parse and return
    # (parsing logic extracts PROBABILITY and CONFIDENCE from response)

Position Sizing (Kelly Criterion)

def calculate_position_size(fair_value, market_price, bankroll, max_kelly=0.06):
    """
    Calculate optimal position size using Kelly Criterion

    Formula: kelly = (fair_value - price) / (1 - price) for BUY
    Uses quarter-Kelly (divide by 4) for conservatism
    Caps at max_kelly of bankroll
    """
    kelly = (fair_value - market_price) / (1 - market_price)
    kelly_adjusted = kelly / 4  # Quarter-Kelly
    kelly_capped = min(kelly_adjusted, max_kelly)

    position_size = bankroll * kelly_capped
    return round(position_size, 2)

Implementation Status

✅ Fully Implemented & Working

Core Trading Engine:

✅ Market scanning via polymarket-data publisher (100+ active markets)
✅ AI research via perplexity publisher (Perplexity AI integration)
✅ Fair value estimation via seren-models publisher (Claude Sonnet 4.5)
✅ Kelly Criterion position sizing
✅ Order placement via py-clob-client (DirectClobTrader with local EIP-712 signing)
✅ Position tracking with unrealized P&L calculation
✅ Comprehensive JSONL logging (trades, scans, positions)

Infrastructure:

✅ Seren API client with publisher routing
✅ Desktop sidecar/keychain publisher auth support
✅ Legacy environment-variable credential fallback
✅ Dry-run mode (simulation without placing trades)
✅ Configuration system (JSON-based risk parameters)
✅ Cron-backed monitor mode for stale-order cleanup and guard exits

Seren Publishers Used:

polymarket-data - Real-time market data (prices, liquidity, volumes)
py-clob-client - Order placement with local EIP-712 signing (via DirectClobTrader)
perplexity - AI-powered market research
seren-models - LLM inference (Claude, GPT, Gemini, etc.)
seren-cron - Autonomous local-pull scheduling

⚠️ Limitations

Not Automated (Manual Only):

Bankroll rebalancing after profits/losses

Not Implemented:

Web dashboard (command-line only)
Email/webhook notifications (file logs only)
Backtesting with historical data

Cost Estimation

SerenBucks (API Calls)

Per scan cycle:

Perplexity research: $0.01 × markets researched
Claude fair value: $0.01 × markets evaluated
Total: ~$0.50-2.00 per scan (depends on markets scanned)

Daily costs:

Every 5 min: $5-10/day
Every 10 min: $2-5/day
Every 30 min: $0.50-1.50/day

Polymarket Trading

Order placement: $0.005 per order
Order cancellation: $0.002 per cancellation
Price queries: $0.001 per request

Troubleshooting

"SEREN_API_KEY/API_KEY is required"

Create .env file from .env.example
Add SEREN_API_KEY for standalone runs
For desktop-launched runs, ensure runtime API_KEY is injected

"Polymarket credentials required"

Recommended: enable desktop keychain mode in .env with SEREN_DESKTOP_PUBLISHER_AUTH=true
Then configure Polymarket publisher credentials in Seren Desktop Settings > Publisher MCPs
Legacy mode only: add POLY_API_KEY, POLY_PASSPHRASE, POLY_ADDRESS to .env

"Low SerenBucks balance"

Buy SerenBucks at: https://serendb.com/serenbucks or https://console.serendb.com
Maintain at least $20 for smooth operation

"Publisher call failed: 401"

In desktop mode: verify Polymarket publisher credentials are configured/enabled in Seren Desktop
In legacy mode: check POLY_* values and verify credentials haven't expired

Best Practices

For Users

Start small: Test with $50-100 before scaling up
Use dry-run first: Always test before going live
Monitor regularly: Check logs and positions daily
Adjust conservatively: Increase bankroll gradually
Understand the risks: Only trade what you can afford to lose
Keep funded: Maintain sufficient SerenBucks balance

For Developers

Always validate inputs: Check config parameters are in valid ranges
Never skip confirmation: Live trading requires explicit user consent
Log everything: All trades, scans, errors go to log files
Handle errors gracefully: Never crash - log and notify
Protect credentials: Use environment variables, never log secrets
Estimate costs proactively: Warn users about SerenBucks costs

Seren-Cron Integration

Use the skill-local seren-cron local-pull runner for scheduling. The schedule lives in Seren, but a local polling process must stay online on the machine that will execute the bot.

Requirements: Seren Desktop login or a valid SEREN_API_KEY. Live schedules also require Polymarket credentials plus funded SerenBucks.

Current Seren funding flow:

Buy SerenBucks at https://serendb.com/serenbucks or https://console.serendb.com
Stripe deposits start at $5
A verified email is required before Stripe deposits
API-first users can fund with POST /wallet/deposit

Step 1 — Check seren-cron is available

publisher: seren-cron
path:      /api/health
method:    GET

Step 2 — Create or update the local pull schedule

Create or upsert the runner plus the local-pull job:

python3 scripts/setup_cron.py create --config config.json --schedule "0 */2 * * *" --run-type scan
python3 scripts/setup_cron.py create --config config.json --schedule "15 * * * *" --run-type monitor

For live mode, include --live after you have confirmed credentials, budget, and risk parameters.

Step 3 — Start the local pull runner

Start the polling process that claims due work and runs scripts/agent.py locally:

python3 scripts/run_local_pull_runner.py --config config.json

Leave this process running on the machine that should execute trades.

Step 4 — Manage the schedule and runner

python3 scripts/setup_cron.py list
python3 scripts/setup_cron.py list-runners
python3 scripts/setup_cron.py pause --job-id <job_id>
python3 scripts/setup_cron.py resume --job-id <job_id>
python3 scripts/setup_cron.py delete --job-id <job_id>
python3 scripts/setup_cron.py delete-runner --runner-id <runner_id>

Insufficient Funds Guard

If a live trade or cycle fails because the trading balance or SerenBucks balance is too low to execute, immediately pause the cron job:

Pause the job immediately if live execution fails because trading funds or SerenBucks are exhausted.

Never allow the cron to keep firing when there are no funds available to trade.

AgentSkills.io Standard

This skill follows the AgentSkills.io open standard for agent skills, ensuring compatibility across:

Claude Code
OpenAI Codex
Google Gemini
Any compatible LLM tool

Taariq Lewis, SerenAI, Paloma, and Volume at https://serendb.com Email: hello@serendb.com

polymarket-bot

Polymarket Trading Bot

⚠️ IMPORTANT LEGAL DISCLAIMERS

Geographic Restrictions - CRITICAL

Regulatory Status

Not Financial Advice

Risk of Loss

Tax Obligations

Age Restriction

No Warranty

When to Use This Skill

For Claude: How to Invoke This Skill

Prerequisites Check

Scanning for Opportunities (Paper Trading)

Checking Paper Trading History

Running Live Trading (Advanced)

Trade Execution Contract

CLOB Execution Rules

Pre-Trade Checklist (Mandatory)

Live Safety Opt-In

Overview

Architecture

API Key Setup

Setup Workflow

Phase 1: Install Dependencies

Phase 2: Configure Credentials

Phase 3: Configure Risk Parameters

bankroll

mispricing_threshold

max_kelly_fraction

scan_interval_minutes

max_positions

stop_loss_bankroll

Phase 4: Fund Your Wallets

Minimum Starting Budget: $100

Scaling Up

Paper Trading (RECOMMENDED FOR EVERYONE)

Moving from Paper to Live Trading

How to Fund SerenBucks

How to Fund Polymarket (Polygon USDC)

Checking Your Balances

Phase 5: Dry-Run Test (STRONGLY RECOMMENDED)

Phase 6: Live Trading Confirmation

Phase 7: Run Live

Control Commands

Show Status

Show Recent Trades

Pause/Resume Trading

Stop Trading

Monitoring & Logs

trades.jsonl

scan_results.jsonl

positions.json

notifications.jsonl

How It Works (Technical Details)

Fair Value Estimation

Position Sizing (Kelly Criterion)

Implementation Status

✅ Fully Implemented & Working

⚠️ Limitations

Cost Estimation

SerenBucks (API Calls)

Polymarket Trading

Troubleshooting

"SEREN_API_KEY/API_KEY is required"

"Polymarket credentials required"

"Low SerenBucks balance"

"Publisher call failed: 401"

Best Practices

For Users

For Developers

Seren-Cron Integration

Step 1 — Check seren-cron is available

Step 2 — Create or update the local pull schedule

Step 3 — Start the local pull runner

Step 4 — Manage the schedule and runner

Insufficient Funds Guard

AgentSkills.io Standard

More from serenorg/seren-skills

polymarket-maker-rebate-bot