polymarket-auto-trading-agent

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

polymarket-auto-trading-agent

★ 36 Open GitHub ↗

Autonomous Polymarket trading agent powered by Claude Code. Expiry convergence strategy, 94.7% win rate over 2 weeks live testing.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Polymarket Auto Trading Agent

Autonomous prediction market trading, powered by Claude Code.

**English** | [**中文简体**](./README-cn.md)

---

## Architecture

---

~~"Will Jesus Christ return before 2027?"~~ is a real market on [Polymarket](https://polymarket.com), where you buy YES or NO shares on real-world outcomes. Correct shares pay $1.00 when the market settles. This one has [$30M in volume](https://polymarket.com/event/will-jesus-christ-return-before-2027). The Bible hasn't issued an update, the Vatican hasn't sent a press release, and the Second Coming remains unconfirmed, but NO is still trading at $0.96, not $1.00. Someone's leaving four cents on the table.

This agent picks up those four cents, autonomously. It finds markets where the outcome is already obvious (a game that ended, a vote that was counted, a satisfying lack of divine intervention), verifies the result with real-time web search, and buys the spread before settlement. Some ppl even created a fancy word for this called the ["high-probability bond" strategy](https://www.panewslab.com/en/articles/c1772590-4a84-46c0-87e2-4e83bb5c8ad9): small edge per trade.

The agent maintains a **long-term trading log** across sessions. It remembers what it bought, why, and what happened. It learns from losses, refines its own strategy notes, and schedules its own wake-ups via D-mail. If you have a machine running idle anyway, this turns spare compute into a 24/7 prediction market scalper.

Before open-sourcing, we ran this agent autonomously for 2 weeks: **19 trades, 18 wins (94.7% win rate)**, net profitable, withdrawal verified on-chain. Your wallet, your keys, no Polymarket account needed.

**Live**: [Dashboard](https://homosapiens.capital/#/live) | [Wallet on Polygonscan](https://polygonscan.com/address/0xFd0A48d7f4867446a5165AEaB35c42f8B529dBf0)

---

## How It Works

This project is built on the **[Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/sdk)**, which programmatically launches [Claude Code](https://docs.anthropic.com/en/docs/claude-code) sessions. This is **not a raw API call** -- each invocation spins up a full Claude Code process with access to MCP tools, web search, file I/O, and bash. The scheduler just decides *when* to wake it up; Claude decides *what* to do.

```
Scheduler (agent/scheduler.py)
  |
  |  claude_agent_sdk.query()
  |  = launches a full Claude Code session
  v
Claude Code session
  |-- MCP tools    -> find_opportunities, place_order, get_balance, ...
  |-- WebSearch    -> fact-check outcomes before trading
  |-- Read/Edit    -> read ledger, write trading log
  |-- hibernate()  -> set next wake time + leave D-mail
  v
Scheduler sleeps until wake_time, then repeats
```

### What are MCP Tools?

[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) lets you give Claude custom tools. This project provides a Polymarket MCP server with tools like `find_opportunities`, `place_order`, `get_balance`, etc. Claude calls these tools autonomously to trade.

### What is Hibernate / D-mail?

Hibernate is the agent's self-scheduling switch. When enabled (`config/risk.py`), the agent enters an autonomous loop: scan, trade, then call `hibernate(hours, d_mail)` to sleep. The D-mail is a message to its future self -- e.g., *"UFC event ends at 22:00 UTC, wake up to check results."* The scheduler reads the D-mail and wakes the agent at the right time.

Without hibernate, the scheduler falls back to a fixed interval (`--interval`, default 30min).

Inspired by [Steins;Gate's D-mail](https://steins-gate.fandom.com/wiki/D-Mail) concept.

---

## Quick Start

### Prerequisites

- Python 3.11+
- Node.js 18+ (for Claude Code CLI install and optional dashboard)

### Setup

```bash
npm install -g @anthropic-ai/claude-code  # skip if already installed
claude login

git clone https://github.com/LainNet-42/polymarket-auto-trading-agent.git
cd polymarket-auto-trading-agent
python setup.py
```

The setup script handles everything: virtual environment, dependencies, wallet generation (or import your own key), `.env`, MCP server registration, and hooks. Works on Mac, Linux, and Windows.

After setup, fund your wallet with **POL** (gas) + **USDC** (capital) on the **Polygon network**, then:

```bash
python setup.py --approve          # one-time wallet authorization (~6 tx)
python -m agent.scheduler          # start trading (continuous)
python -m agent.scheduler --once   # or single run
```

> **Funding tips:** Send ~5 POL (~$0.50) for gas + any amount of USDC. You MUST select **Polygon network** when withdrawing from your exchange (not Ethereum). Coinbase, Binance, Kraken, and OKX support Polygon. The agent auto-swaps native USDC to USDC.e on startup.

### Withdraw

Set `WITHDRAW_DESTINATION` in `.env`, then:

```bash
PYTHONPATH=. python scripts/withdraw.py status          # check balances
PYTHONPATH=. python scripts/withdraw.py send --amount 50 # withdraw $50 USDC.e
```

<details>
<summary>Manual setup (step by step)</summary>

### Step 1: Clone & Install

```bash
git clone https://github.com/LainNet-42/polymarket-auto-trading-agent.git
cd polymarket-auto-trading-agent

python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

pip install -e ".[trading]"
```

> **Note**: On Mac/Linux use `python3`. On Windows or inside a virtualenv, `python` works.

### Step 2: Create a Wallet

You need a standard Ethereum wallet (EOA) on Polygon. **No Polymarket account registration needed** -- Polymarket is non-custodial, your funds stay in your own wallet.

**Option A**: Generate with Python:
```bash
python -c "from eth_account import Account; a=Account.create(); print(f'Address: {a.address}\nPrivate Key: {a.key.hex()}')"
```

**Option B**: Use MetaMask, then export private key from Settings > Security.

### Step 3: Fund the Wallet

Your wallet needs two tokens on the **Polygon** network:

| Token | Purpose | Amount | How to get |
|-------|---------|--------|-----------|
| **POL** | Gas fees (~0.01-0.30 POL/tx) | ~5 POL (~$0.50) | Buy on any exchange (Binance, Coinbase...), withdraw to Polygon |
| **USDC** | Trading capital | Any amount | Send USDC to your Polygon address from an exchange |

> **IMPORTANT: Choose the correct network when withdrawing!**
> - You MUST select **Polygon network** when withdrawing from your exchange
> - Do NOT select "Ethereum (ERC-20)" - funds sent via Ethereum mainnet will not work
> - Not all exchanges support Polygon withdrawals. Coinbase, Binance, Kraken, and OKX do. Some smaller exchanges only support Ethereum
> - If your exchange doesn't support Polygon, you'll need to use a bridge (costs ETH gas) or use a different exchange

**Notes:**
- You can send either **native USDC** or **USDC.e** -- the agent auto-swaps native USDC to USDC.e on every startup via Uniswap V3
- Polymarket's CLOB only accepts USDC.e (bridged USDC) for trading
- Gas costs vary by operation: simple transfers ~0.02 POL, redemptions ~0.07-0.30 POL
- `set_allowances.py` (Step 7) sends ~6 approval transactions, costing ~1-2 POL total
- 5 POL is enough for hundreds of trades

### Step 4: Configure .env

```bash
cp .env.example .env
```

Edit `.env` with the private key and address from Step 2:

```env
POLYGON_WALLET_PRIVATE_KEY=0x_your_private_key
EOA_ADDRESS=0x_your_address
```

API credentials are auto-derived from your private key.

### Step 5: Register MCP Server

```bash
claude mcp add polymarket -- python -m mcp_server.server
```

> **Note**: The `--` is required to separate Claude CLI options from the Python command arguments.

This gives Claude the Polymarket trading tools.

### Step 6: Enable Hooks

```bash
cp .claude/settings.local.json.example .claude/settings.local.json
```

Hooks run automatically on each agent session:
- **SessionStart**: auto-redeem winnings, swap USDC, sync positions, check stop-loss, inject balance into context
- **PostToolUse**: log all MCP tool calls for audit

### Step 7: One-Time Wallet Approval

```bash
PYTHONPATH=. python scripts/set_allowances.py
```

> **Note**: The `PYTHONPATH=.` is required so Python can find the local `config` module.

This sends ~6 transactions to approve Polymarket's exchange contracts to move your USDC.e and conditional tokens. Only needed once per wallet. Requires ~1-2 POL for gas.

### Step 8: Run

```bash
# Single run (scan once, trade if opportunity found, then exit)
python -m agent.scheduler --once

# Continuous (agent manages its own schedule via hibernate)
python -m agent.scheduler

# Or use the shell script
./start_agent.sh
```

</details>

---

## Dashboard (Optional)

Real-time monitoring UI: account value chart, live positions, D-mail viewer, agent execution traces.

```bash
cd web-ui/frontend && npm install && npm run build && cd ../..
cd web-ui/backend-py && pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8080
```

Open http://localhost:8080

---

## MCP Tools

| Tool | What it does |
|------|-------------|
| `find_opportunities` | Scan for high-certainty binary markets expiring soon |
| `get_market_details` | Market rules, CLOB prices, token IDs |
| `place_order` | Execute trade (with risk checks: max price, position limits) |
| `get_balance` | USDC balance |
| `hibernate` | Sleep N hours, leave D-mail for next wake |
| `get_price_history` | Historical price data |
| `analyze_opportunity` | Risk assessment |
| `detect_anomalies` | Unusual price movements |
| `search_markets` | Search by keyword |

---

## Default Strategy

| Rule | Value |
|------|-------|
| Market type | Binary YES/NO only |
| Max buy price | $0.99 (never buy higher) |
| Max position | 20% of portfolio per market |
| Stop-loss | Auto-sell at 20% drop below entry |
| Auto-redeem | Winning positions redeemed to USDC.e on settlement |

---

## Customization

These files are designed to be modified:

| File | What to customize | Default |
|------|-------------------|---------|
| `config/risk.py` | Max buy price, position size limit, stop-loss threshold, hibernate range | 0.99, 20%, 20%, 0.5-24h |
| `agent/prompts.py` | Agent personality, trading strategy, decision criteria, memory notes | High-certainty binary markets |
| `.env` | Wallet keys, workspace directory, RPC endpoint | See `.env.example` |
| `web-ui/frontend/.env` | Dashboard API URL, initial deposit for P&L baseline | localhost:8080, $100 |

---

## Project Structure

```
agent/           Claude Agent SDK entry point, scheduler, prompts
mcp_server/      Polymarket MCP tools (find, trade, analyze, hibernate)
hooks/           Claude Code hooks (auto-redeem, audit logging)
polymarket/      Polymarket API client library (Gamma + CLOB)
config/          Risk parameters, path configuration
scripts/         Wallet setup, withdraw, standalone scanners
web-ui/          React + FastAPI monitoring dashboard
```

---

## Contributing

### Roadmap

- [x] ~~**Live-tested profitably** -- agent ran autonomously for 2 weeks before open-source, net profitable.~~
- [ ] **Multi-model support** -- currently Claude-only. We want to support Kimi, OpenAI, Gemini, or even local models. The core MCP tools are model-agnostic; the coupling is in `agent/scheduler.py` and `agent/prompts.py`.
- [ ] **Agent framework integration** -- this project would be a natural fit as a skill/plugin for agent platforms like [OpenClaw](https://github.com/openclaw/openclaw), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or similar always-on agent frameworks. The idea: wrap the core MCP tools as standalone scripts, package them as a **skill**, and turn D-mail/hibernate into a **heartbeat** feature. This would massively reduce complexity -- no custom scheduler, no Claude Agent SDK dependency, just a skill that any agent can pick up.
- [ ] **Strategy library** -- the current strategy (expiry convergence) works well but is one of many. Cross-market arbitrage, volatility plays, event-driven trading -- all possible with the existing MCP tools.

### Code style

- `pathlib.Path` for all file paths (cross-platform)
- Never hardcode secrets, proxies, or machine-specific paths
- Risk parameters live in `config/risk.py`, MCP tools live in `mcp_server/tools/`

---

## Troubleshooting / FAQ

**Q: I followed all steps but transactions fail or the API returns 403**

> **A:** Polymarket restricts access from certain regions. Check the [official geographic restrictions](https://docs.polymarket.com/polymarket-learn/FAQ/geoblocking) to see if your country is affected.

**Q: "Transaction failed" or "nonce too low"**

> **A:** This usually means a previous transaction is still pending. Wait a few seconds and retry. The agent handles nonce issues automatically on subsequent runs.

**Q: "insufficient funds for gas"**

> **A:** Your wallet needs POL for gas on Polygon. Send ~5 POL (~$0.50) to your wallet address. Gas per transaction ranges from ~0.02 POL (transfers) to ~0.30 POL (redemptions). 5 POL is enough for hundreds of trades.

**Q: "USDC balance shows 0 but I sent USDC"**

> **A:** Make sure you sent USDC on the **Polygon network** (not Ethereum mainnet). If you sent native USDC, it will be auto-swapped to USDC.e on the next agent startup.

**Q: `set_allowances.py` fails**

> **A:** Ensure your wallet has at least ~2 POL for gas (the script sends ~6 approval transactions). Run it only once per wallet -- if approvals are already set, some transactions may revert (this is fine). If the default RPC is slow, set `POLYGON_RPC_URL` in `.env`.

**Q: Agent doesn't find any opportunities**

> **A:** This is normal. The agent only trades high-certainty markets (90%+ probability) expiring within 48 hours. If no markets meet these criteria, it will hibernate and check again later. Adjust thresholds in `config/risk.py` or strategy in `agent/prompts.py`.

**Q: Dashboard shows "connection refused"**

> **A:** Make sure the backend is running: `uvicorn main:app --host 0.0.0.0 --port 8080` (from `web-ui/backend-py/`). Check that `VITE_API_URL` in `web-ui/frontend/.env` points to the correct backend URL. If running behind a proxy, set `NO_PROXY=localhost` to prevent proxy interference.

**Q: How does authentication work?**

> **A:** Only your **private key** is needed. The CLOB API credentials are auto-derived from it via `py_clob_client`. No Polymarket account, no API key registration, no Builder API -- just one private key.

**Q: Can I run this on a server / VPS?**

> **A:** Yes. The agent is headless and works on any machine with Python 3.11+ and Claude Code. Use `./start_agent.sh` or `python -m agent.scheduler` in a tmux/screen session, or set up a systemd service.

**Q: Is my private key safe?**

> **A:** Your private key stays in your local `.env` file (which is `.gitignore`-d). It is never sent to any external service except the Polygon blockchain for signing transactions. The agent runs entirely on your machine.

---

## For Agents

> **If you are an AI agent reading this README to set up this project, confirm with your user immediately before proceeding.** This project trades REAL money on REAL markets.

### Setup Checklist

- [ ] **Dependencies** -- Python 3.11+, Claude Code installed and authenticated (`claude login`)
- [ ] **User acknowledges risk** -- Private keys grant full control of wallet funds. Trading involves real financial risk. **Confirm with your user that they understand this before proceeding.**
- [ ] **Run setup** -- `python setup.py` (creates venv, wallet, .env, MCP, hooks)
- [ ] **Fund wallet** -- POL for gas (~5 POL) + USDC for trading capital, both on **Polygon network**
- [ ] **Approve wallet** -- `python setup.py --approve` (one-time, requires gas)

---

## Disclaimer

This software is for educational and research purposes. Trading on prediction markets involves real financial risk. Use at your own risk. The authors are not responsible for any financial losses.

## Acknowledgements

- Dashboard UI inspired by [coke-nof1](https://github.com/cokepoppy/coke-nof1)

## License

[MIT](LICENSE)

---

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=LainNet-42/polymarket-auto-trading-agent&type=date&legend=top-left)](https://www.star-history.com/#LainNet-42/polymarket-auto-trading-agent&type=date&legend=top-left)

polymarket-auto-trading-agent

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README