serenorg/bot

Polymarket 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:

1. Parse output for lines starting with ✓ Opportunity found!
2. Extract: market question, fair value, market price, edge, recommended position size
3. 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 |

4. Remind user these are paper trades - no real orders placed
5. 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:

1. Fetch the live order book for every token involved.
2. Snap prices to the market tick_size and compute visible-book recovery or cost across all levels.
3. 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.
4. Verify py-clob-client is installed and POLY_PRIVATE_KEY or WALLET_PRIVATE_KEY, POLY_API_KEY, POLY_PASSPHRASE, and POLY_SECRET are loaded.
5. 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:

1. Scans Polymarket for active prediction markets
2. Researches opportunities using Perplexity AI
3. Estimates fair value with Claude (Anthropic)
4. Identifies mispriced markets (edge > threshold)
5. Executes trades using Kelly Criterion for position sizing
6. Runs autonomously on seren-cron schedule
7. 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:

1. 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.
2. Existing .env file — check if SEREN_API_KEY is already set in the skill's .env file. If set, no further action is needed.
3. 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):

1. Open Seren Desktop
2. Go to Settings > Publisher MCPs
3. Configure Polymarket publisher credentials
4. 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):

1. Visit polymarket.com
2. Connect your wallet
3. Navigate to Settings > API Keys
4. Click "Derive API Key"
5. 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:

1. Fund $25 SerenBucks (covers ~25 scans)
2. Set "scan_interval_minutes": 120 in config.json (2-hour intervals)
3. Run paper trading for 5-7 days (60-84 scans)
4. 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
5. 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

1. Visit: https://serendb.com/serenbucks or https://console.serendb.com
2. Choose deposit method:
   • Credit card (instant)
   • Crypto transfer (USDC, ETH, BTC)
3. 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)

1. Bridge USDC to Polygon PoS using:

   • Polygon Bridge (official)
   • Hop Exchange (faster)
   • Connext (alternative)

2. 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)

3. 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:

1. Have I tested in dry-run mode?
2. Do I understand the risks?
3. Can I afford to lose this capital?
4. Is prediction market trading legal in my jurisdiction?
5. 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

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

For Developers

1. Always validate inputs: Check config parameters are in valid ranges
2. Never skip confirmation: Live trading requires explicit user consent
3. Log everything: All trades, scans, errors go to log files
4. Handle errors gracefully: Never crash - log and notify
5. Protect credentials: Use environment variables, never log secrets
6. 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: [email protected]