# Polymarket BTC Up/Down Lab

只读可行性验证项目，用来研究 Polymarket BTC Up/Down 5m 市场是否存在足够稳定的定价偏差。

当前版本不会连接钱包、不会签名、不会下单。它做三件事：

- 从 Gamma API 读取事件、market、token id、`priceToBeat`。
- 从 Polymarket CLOB WebSocket 读取 Up/Down 增量盘口。
- 从 Polymarket RTDS Chainlink BTC/USD 获取实时价格，估算 `P(end >= priceToBeat)` 和扣费后的 taker edge。
- 将实时观测和盘口事件写入 DuckDB。

## 安装

```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```

## 观察指定市场

```bash
.venv/bin/updown-lab observe --slug btc-updown-5m-1779347700 --duration 60
```

输出会写入 `data/observations.jsonl`，每行是一条可回放的 JSON 快照。

## 发现当前候选市场

```bash
.venv/bin/updown-lab discover --limit 10
```

Gamma 的 recurring series 有时会返回尚未启用订单簿的未来市场，所以实盘观察前要看 `acceptingOrders`、`enableOrderBook`、`priceToBeat` 是否存在。

## 启动实时监控网站

```bash
.venv/bin/updown-dashboard --host 127.0.0.1 --port 8765
```

然后打开：

```text
http://127.0.0.1:8765
```

监控台会按 5 分钟 Unix 时间边界自动切换当前 BTC Up/Down 市场，实时展示价格、盘口、fair value、taker edge 和最近日志。实时网站的数据源是 `data/updown.duckdb`。

如果 live 市场的 Gamma 元数据暂时没有 `priceToBeat`，仪表盘会优先使用 RTDS 边界 tick 作为 `rtds_boundary`。只有中途启动且缺少边界 tick 时才会临时显示 `proxy_start`，这种样本不会计入可信回测。

## 策略口径

第一版 fair value 使用短期布朗运动近似：

```text
z = (current_price - price_to_beat) / (sigma * sqrt(seconds_remaining))
fair_prob = normal_cdf(z)
```

其中 `sigma` 由最近价格收益率滚动估算，并设置了下限，避免临近结算时概率过度极端。

扣 taker fee 后的近似 edge：

```text
buy_up_edge = fair_prob - up_ask - fee(up_ask)
buy_down_edge = (1 - fair_prob) - down_ask - fee(down_ask)
```

Polymarket crypto fee 近似：

```text
fee = 0.07 * price * (1 - price)
```

## 下一步

- 用 DuckDB 回放页分析入场时机、滑点、手续费后 edge 和窗口胜率。
- 增加进程锁/单实例启动保护，避免多个 dashboard 同时写一个 DuckDB 文件。
- 用海外 VPS 长时间采集，比较 RTDS 延迟、边界 tick 命中率和 CLOB 盘口年龄。

## 海外 VPS 部署

部署脚本在 `deploy/` 目录。推荐美国东部 Ubuntu VPS，通过 SSH tunnel 访问本地绑定的 dashboard：

```bash
deploy/sync_to_server.sh user@YOUR_SERVER_IP /opt/updown-dashboard
ssh user@YOUR_SERVER_IP
cd /opt/updown-dashboard
sudo bash deploy/install_ubuntu.sh
sudo bash deploy/install_systemd.sh
sudo systemctl start updown-dashboard
```

本地访问：

```bash
ssh -L 8765:127.0.0.1:8765 user@YOUR_SERVER_IP
```