falcon-polymarket-agent 0.1.0

Autonomous Polymarket trading agent — runs on your machine, tethered to Falcon AI

Falcon AI Agent

Autonomous trading agent for Polymarket — powered by the Falcon AI signal platform.

The Falcon AI Agent runs on your own machine. It connects to the Falcon AI signal server, applies your personal risk settings, and autonomously executes trades on Polymarket using your own wallet. Your private key never leaves your device.

---

How it works

Falcon AI Platform (server)          Your Machine (agent)
─────────────────────────            ──────────────────────────────
Signal Engine                        ws_listener.py
 └─ Bayesian inference        ──►     └─ Risk Filter (your settings)
 └─ Kelly sizing (server)              └─ Trade Executor
 └─ Edge filtering                      └─ Polymarket CLOB API
 └─ WebSocket broadcast                 └─ Local dashboard (localhost:8080)
                                        └─ Dry-run log (CSV)

---

Requirements

• Python 3.11+ or Docker
• A Falcon AI account with an API key
• A Polygon wallet with USDC (for live trading) — or just run in dry-run mode first

Live trading uses Polymarket CLOB V2 (py-clob-client-v2). If you see order_version_mismatch, reinstall deps with pip install -r requirements.txt. After Polymarket’s V2 cutover, place at least one small manual trade on polymarket.com with the same wallet so contract approvals migrate.

Install Python (if not installed)

If python is not available on your machine yet:

1. Download Python 3.11+ from python.org/downloads
2. Run the installer and enable "Add python.exe to PATH" You might have to restart your windows computer for this to work.
3. Verify installation:

   python --version
   pip --version
   

4. (Recommended) Upgrade pip:

   python -m pip install --upgrade pip
   

---

Quick start (Python)

Windows

1. install.bat — creates .venv and installs deps
2. check.bat — tests API key + WebSocket (python main.py --check)
3. run.bat — starts agent + opens http://localhost:8080
4. Use Setup in the dashboard to paste your API key and test connection

Mac / Linux

chmod +x install.sh run.sh check.sh
./install.sh
./check.sh
./run.sh

Manual

python -m venv .venv && source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt
cp .env.example .env
python main.py --check
python main.py

Then open http://localhost:8080 (Setup wizard opens automatically on first run).

Quick start (pip / PyPI)

Install from PyPI (Python 3.11+). Config and logs live in your current working directory (or set FALCON_AGENT_HOME).

pip install falcon-polymarket-agent
cp .env.example .env   # or download from the Falcon app
falcon-polymarket-agent-check
falcon-polymarket-agent

Optional Node bootstrap (installs the PyPI package on first run):

npx @falconai/agent-client --check
npx @falconai/agent-client

---

Quick start (Docker / VPS)

cp .env.example .env
# Edit .env — FALCON_API_KEY required; POLYMARKET__PK only for live trading

docker compose up -d
# Dashboard: http://localhost:8080

Ubuntu VPS bootstrap: bash scripts/setup-vps.sh (after copying this folder to the server).

Windows executable (no Python)

build-windows.bat    REM once, on a dev machine
install-exe.bat      REM end users — runs dist\falcon-ai-agent.exe

Ship dist\falcon-ai-agent.exe with .env.example beside it. Publish to the app via scripts\package-release.ps1.

OpenClaw + MCP

• Skill bundled under integrations/openclaw/ (also on the dashboard Downloads panel)
• ClawHub: openclaw skills install falcon-polymarket (after you publish)
• See docs/OpenClaw-Falcon-Integration.md

---

Configuration (.env)

Full reference: docs/CLIENT-ENV-REFERENCE.md — every setting, recommended profiles, and troubleshooting.

Copy .env.example to .env and edit. Key variables:

Variable	Description	Default
FALCON_API_KEY	Your Falcon AI API key (from platform)	required
FALCON_WS_URL	Signal WebSocket URL	wss://api.falconai.pro/ws/signals
FALCON_API_BASE	REST API for reports + strategy sync	https://api.falconai.pro/api/polymarket
POLYMARKET__PK	Your Polygon wallet private key	required for live
POLYMARKET__CLOB_SIGNATURE_TYPE	0 EOA, 1 email proxy, 2 Gnosis Safe	2 in .env.example
POLYMARKET__CLOB_FUNDER	Safe/proxy funder address	(empty)
POLYMARKET__DERIVE_CLOB_API_CREDS	Auto-derive CLOB API creds from PK	true
SIGNAL_CATEGORIES	Categories to trade or all	all
SIGNAL_TYPES	Optional allowlist: whale_copy, user_whale_copy, …	(empty)
SIGNAL_MIN_EDGE	Optional client gate; min edge (0–1); 0 = off	0
SIGNAL_MIN_CONFIDENCE	Optional client gate; min confidence (0–1)	0
SYNC_STRATEGIES_ON_START	Fetch Strategy Lab strategies on boot	true
POLYMARKET__CHAIN_ID	Polygon chain (137 mainnet, 80002 Amoy)	137
RISK_LEVEL	conservative / balanced / aggressive	balanced
TRADING__BANKROLL_USDC	Your total trading bankroll	1000
TRADING__MAX_POSITION_USDC	Max single trade size (USD)	50
TRADING__MAX_DAILY_SPEND_USDC	Daily spend circuit-breaker	200
TRADING__MAX_OPEN_POSITIONS	Max concurrent open positions (unresolved)	10
Advanced risk	Drawdown, daily loss, exposure caps, hours, stop-loss, etc.	See CLIENT-ENV-REFERENCE.md
DRY_RUN	true = log trades only, never execute	true
REPORT_STATS_TO_PLATFORM	Send anonymised performance stats	true
DASHBOARD_PORT	Local dashboard port	8080
LOG_LEVEL	DEBUG / INFO / WARNING / ERROR	INFO

Falcon environments

	Production	Test (staging)
Domain	falconai.pro	falconai.bot
App	app.falconai.pro	app-test.falconai.bot
API / WebSocket	api.falconai.pro	api-test.falconai.bot

Defaults target production. For staging, create a test API key on app-test.falconai.bot and set the test FALCON_WS_URL / FALCON_API_BASE values (see .env.example comments). Never mix a prod key with test URLs, or vice versa.

Where to get required keys

• FALCON_API_KEY

  • Log in at app.falconai.pro
  • Open your API key area in the app dashboard
  • Copy key into .env as FALCON_API_KEY=...

• POLYMARKET__PK (EOA/private key for MetaMask wallet)

  • In MetaMask: Account menu → Account details → Show private key
  • Paste into .env as POLYMARKET__PK=...
  • Keep this key secret; do not commit .env

• POLYMARKET__CLOB_FUNDER (only for Polymarket email wallet flow)

  • In your Polymarket profile, copy the proxy/funder address
  • Set POLYMARKET__CLOB_SIGNATURE_TYPE=1
  • Set POLYMARKET__CLOB_FUNDER=0x...

---

Risk levels

Level	Kelly multiplier	Max per trade
conservative	10% of server suggestion	2% of bankroll
balanced (default)	25% of server suggestion	5% of bankroll
aggressive	50% of server suggestion	10% of bankroll

The Falcon AI server already applies quarter-Kelly sizing before broadcasting. Your local multiplier scales on top of that, so balanced means you're effectively trading at ~6.25% Kelly — a cautious, long-term approach.

Start with DRY_RUN=true and observe the dashboard for at least a week before switching to live.

---

Local dashboard

Once running, visit http://localhost:8080 to see:

• Live signal feed (as they arrive from the platform)
• Trade log with outcomes
• 7-day performance stats (win rate, ROI, drawdown)
• One-click send of anonymised stats to the community leaderboard

---

Community stats (opt-in)

When REPORT_STATS_TO_PLATFORM=true, the agent sends a fully anonymised weekly summary to the Falcon AI platform. This powers the community performance dashboard on the platform.

What is sent:

• Aggregated counts (signals received, trades executed, win rate, ROI)
• Performance by category
• Your RISK_LEVEL setting

What is never sent:

• Your private key
• Your wallet address
• Individual trade details
• Your API key (only a double-hash fingerprint is used as an anonymous client ID)

---

Security

• Your private key is read from .env on your machine and used only to sign CLOB orders directly against the Polymarket API
• The Falcon AI server never receives your private key
• All WebSocket communication is over wss:// (TLS encrypted)
• The agent connects outbound only — no inbound ports required (dashboard is localhost only)

---

Wallet setup (Polymarket)

1. Create a Polymarket account at polymarket.com and connect your wallet
2. Create or use a Polygon wallet (MetaMask recommended for EOA, CLOB_SIGNATURE_TYPE=0)
3. Bridge USDC to Polygon via Polygon Bridge
4. Deposit USDC into your Polymarket account
5. Export your private key from MetaMask and paste into .env as POLYMARKET__PK

For Polymarket email wallets (signature_type=1): get your proxy address from your Polymarket profile page and set POLYMARKET__CLOB_FUNDER and POLYMARKET__CLOB_SIGNATURE_TYPE=1.

Metrics note (important)

• In DRY_RUN=true, dashboard win rate is an estimate, not true settled outcome accuracy.
• Current estimate uses a heuristic (edge > 0.05) as proxy for "win".
• Use this for relative strategy checks, not final realized performance.

---

License

MIT — you are free to run, modify and distribute this agent. The Falcon AI signal platform (backend) is proprietary and requires a valid API key.

---

Built by Falcon AI