polymarket-edge

# Polymarket Edge

A locally-running FastAPI skill that wraps the Polymarket Gamma + CLOB APIs with
a built-in EMA(5/20) crossover strategy and SkillPay.me billing.

## Setup

```bash
# Install dependencies
pip install -r requirements.txt

# Set required environment variables
export SKILL_BILLING_API_KEY=sk_your_skillpay_api_key_here
export SKILL_ID=polymarket-edge

# Start the skill server (port 8080)
python main.py
```

The interactive docs are available at `http://localhost:8080/docs`.

## Environment variables

| Variable | Required | Description |
|---|---|---|
| `SKILL_BILLING_API_KEY` | ✅ | From your skillpay.me dashboard |
| `SKILL_ID` | ✅ | Your skill slug, e.g. `polymarket-edge` |
| `POLYMARKET_PRIVATE_KEY` | optional | EVM private key for live order placement |

## Billing

Every billed endpoint requires `?user_id=<id>` in the query string.
If the user has no tokens the API returns **HTTP 402** with a `top_up_url`.

```
GET  /balance?user_id=alice          → current token balance
GET  /topup?user_id=alice&amount=10  → BNB Chain USDT payment link
```

1 USDT = 1 000 tokens · 1 call = 1 token · min top-up 8 USDT · SkillPay takes 5 %

## Key endpoints (all require `?user_id=`)

### Market data
```
GET /markets/search?q=bitcoin    Search all Polymarket markets
GET /markets/btc                 List active BTC/Bitcoin markets
GET /market/{id}                 Single market details
GET /market/{token_id}/book      Full order book (bids + asks)
GET /market/{token_id}/price     Mid-price, spread, implied probability
GET /market/{token_id}/history   5-min OHLCV candles
```

### Strategy signals
```
POST /signal                     Run EMA crossover on top BTC markets
                                 Returns BUY_YES / BUY_NO / HOLD / SKIP per market
```

### Auto-trader
```
GET  /autotrader/status          Is the auto-trader running?
POST /autotrader/start           Start 5-min BTC cycle (background task)
POST /autotrader/stop            Stop auto-trader
GET  /auto...

# Polymarket Edge

An OpenClaw skill that lets any AI agent browse Polymarket prediction markets, run a 5-minute BTC EMA crossover strategy, and optionally place live trades — with every API call billed via **SkillPay.me** (0.001 USDT / call).

> **Polymarket Edge** gives your agent a systematic, always-on trading edge on prediction markets — no manual research, no babysitting.

---

## Quick Start

```bash
cd polymarket-edge
cp .env.example .env          # edit SKILL_BILLING_API_KEY if needed
pip install -r requirements.txt
python main.py                # starts on http://localhost:8080
```

Open `http://localhost:8080/docs` for the interactive Swagger UI.

---

## Billing model

| Item | Value |
|------|-------|
| Platform | SkillPay.me (BNB Chain USDT) |
| Rate | 1 token per call |
| Token price | 1 USDT = 1000 tokens |
| Minimum top-up | 8 USDT |
| Withdrawal fee | 5% |

Every billed endpoint requires `?user_id=<your_id>`. If tokens run out the API returns `HTTP 402` with a `top_up_url`.

```
GET /balance?user_id=alice          → { balance: 3200, usdt_equivalent: 3.2 }
GET /topup?user_id=alice&amount=10  → { payment_url: "https://..." }
```

---

## Endpoints

### Free
| Method | Path | Description |
|--------|------|-------------|
| GET | `/` | Health check |
| GET | `/balance` | Token balance |
| GET | `/topup` | Get USDT top-up link |

### Billed (1 token each)
| Method | Path | Description |
|--------|------|-------------|
| GET | `/markets/search?q=bitcoin` | Search all markets |
| GET | `/markets/btc` | List active BTC markets |
| GET | `/market/{id}` | Single market details |
| GET | `/market/{token_id}/book` | Full order book |
| GET | `/market/{token_id}/price` | Mid-price + spread |
| GET | `/market/{token_id}/history` | 5-min OHLCV candles |
| POST | `/signal` | Run EMA crossover on BTC markets |
| GET | `/autotrader/status` | Is auto-trader running? |
| POST | `/autotrader/start` | Start 5-min BTC cycle |
| POST | `/autotrader/stop` | Stop auto-trade...