Metadata-Version: 2.4
Name: falcon-polymarket-agent
Version: 0.1.2
Summary: Autonomous Polymarket trading agent — runs on your machine, tethered to Falcon AI
Project-URL: Homepage, https://app.falconai.pro
Project-URL: Documentation, https://api.falconai.pro/api/docs/sdks#agent-client
Project-URL: Agent setup (app), https://app.falconai.pro/app/agents/client
Project-URL: Source, https://github.com/Falcon-AI-Pro/falcon-ai-client
Author: Falcon AI
License-Expression: MIT
Keywords: falcon,polymarket,prediction-markets,trading-agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Requires-Dist: colorlog<7,>=6.8
Requires-Dist: falcon-agent-webui>=0.1.0
Requires-Dist: flask-cors<6,>=4.0
Requires-Dist: flask<4,>=3.0
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pandas<3,>=2.0
Requires-Dist: py-clob-client-v2<2,>=1.0
Requires-Dist: pydantic-settings<3,>=2.0
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: python-dotenv<2,>=1.0
Requires-Dist: waitress<4,>=3.0
Requires-Dist: websockets<16,>=12.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: hatchling>=1.24; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# Falcon AI Agent

> Autonomous trading agent for [Polymarket](https://polymarket.com) — powered by the [Falcon AI](https://falconai.pro) 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:8050)
                                        └─ Dry-run log (CSV)
```

---

## Requirements

- Python 3.11+  **or**  Docker
- A [Falcon AI](https://app.falconai.pro) 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](https://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](https://www.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:
   ```bash
   python --version
   pip --version
   ```
4. (Recommended) Upgrade pip:
   ```bash
   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:8050  
4. Use **Setup** in the dashboard to paste your API key and test connection  

**Mac / Linux**

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

**Manual**

```bash
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:8050** (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`).

```bash
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):

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

---

## Quick start (Docker / VPS)

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

docker compose up -d
# Dashboard: http://localhost:8050
```

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

## Windows executable (no Python)

```bat
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`](../../docs/OpenClaw-Falcon-Integration.md)

---

## Configuration (`.env`)

**Full reference:** [docs/CLIENT-ENV-REFERENCE.md](docs/CLIENT-ENV-REFERENCE.md) — every setting, recommended profiles, and troubleshooting.

Copy [`.env.example`](.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](docs/CLIENT-ENV-REFERENCE.md#advanced-risk-controls-optional) |
| `DRY_RUN` | `true` = log trades only, never execute | `true` |
| `REPORT_STATS_TO_PLATFORM` | Send anonymised performance stats | `true` |
| `DASHBOARD_PORT` | Local dashboard port | `8050` |
| `LOG_LEVEL` | `DEBUG` / `INFO` / `WARNING` / `ERROR` | `INFO` |

### Falcon environments

| | Production | Test (staging) |
|---|---|---|
| **Domain** | `falconai.pro` | `falconai.bot` |
| **App** | [app.falconai.pro](https://app.falconai.pro) | [app-test.falconai.bot](https://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](https://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:8050** 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](https://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](https://portal.polygon.technology/)
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](https://falconai.pro)*
