alpha-drift/README at main · hyperdrift-io/alpha-drift · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
AlphaDrift

HyperDrift‑grade, AI‑powered crypto‑trading bot

Momentum · Carry · Arbitrage — all wrapped in risk guard‑rails and driven by predictive ML.

⸻

✨ Why AlphaDrift?
	•	Compoundable edge – momentum + perp‑funding carry + MEV rebates.
	•	Predictive selector – Allora + LightGBM forecast Sharpe every 5 min.
	•	Fail‑safe – max‑DD, gas sentinel, oracle gap veto.
	•	DeFi‑native – on‑chain execution via 0x RFQ + Titan builder rebates.

⸻

🚀 Quick start (dev, paper mode)

# clone & install
git clone https://github.com/hyperdrift-io/alphadrift.git
cd alphadrift
pnpm i

# copy env template and add your RPC / API keys
cp .env.example .env

# run database (Timescale)
docker compose up -d db

# start the agent (5‑min paper loop)
pnpm dev

You should see a log line every five minutes:

[ProviderPool] FeatureVector { ts: … price: … }
[Selector] momentum scored 1.34 Sharpe → TradeIntent emitted
[RiskGuard] OK ✔


⸻

🗺 Project map

Folder	Purpose
src/providers/	Pyth, Dexscreener, Chainbase, BirdEye adapters
src/store/	Timescale FeatureStore
src/strategy/	momentum, mean‑rev, funding‑harvest, arbitrage
src/selector/	predictive selector & LLM veto
src/execution/	router + 0x / CoW / Paraswap + MEV builder
python-quant/	DriftBrain (FastAPI + Optuna + LightGBM)
migrations/	SQL schema for Timescale tables

Full architecture diagram lives in architecture.md; build order in roadmap.md.

⸻

⚙️ Environment variables (.env.example)

ALCHEMY_KEY=
ZEROX_API_KEY=
PARASWAP_API_KEY=
MEV_BUILDER_URL=https://rpc.titanbuilder.xyz
OPENAI_API_KEY=
ALLORA_API_KEY=
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=
PAPER=true                # false = live trading
DB_URL=postgres://user:pass@db:5432/alphadrift # password is pass


⸻

🧪 Tests & lint

pnpm test    # Jest (Node)
pytest       # DriftBrain tests
pnpm lint    # ESLint strict

Coverage gate ≥90 %.

⸻

📦 Docker compose

docker compose up --build    # Node agent + DriftBrain + Postgres

Set PAPER=false and add wallet key via Docker secret to trade live.

⸻

🕹 Usage

### 1  Run in paper mode (default)

```bash
pnpm dev                     # 5‑minute paper loop
tail -f logs/agent.log       # stream structured logs
```

The bot logs every FeatureVector, selector decision, and TradeIntent without signing any transaction.

### 2  Switch to live trading

```bash
export PAPER=false           # or set in .env
docker secret create WALLET_KEY /path/privkey.hex
docker compose up            # hot‑reloads with live signing
```

> **Reminder** – fund the wallet with native gas (ETH) and turn on a hardware wallet for size ≥ $10 k.

### 3  Pause / resume

```bash
curl -X POST http://localhost:8080/admin/pause    # stop new trades
curl -X POST http://localhost:8080/admin/resume   # resume loop
```

### 4  Retrain DriftBrain

```bash
docker compose exec driftbrain python train.py --n_trials 10000
# New model saved to /models and auto‑reloaded by the Node agent
```

### 5  Customise strategies

Edit any file in `src/strategy/`, then:

```bash
pnpm test && pnpm dev
```

The agent hot‑reloads modules on change (ts-node-dev).

⸻

⸻

🛡 Safety first
	•	Max draw‑down 5 % intraday → auto‑pause.
	•	Gas usage >1 % equity/day → throttle.
	•	Oracle gap 1 % vs DEX mid → veto.

⸻

🤝 Contributing (solo‑friendly!)
	•	Follow diff‑first in PRs: git patch then full file.
	•	Run pnpm test && pytest before pushing.
	•	Significant design changes require an ADR added to /docs/adr/.

⸻

License

MIT