Solana Perps AI Agent Protocol — autonomous agents that monitor funding rates, price momentum, and liquidation clusters across Hyperliquid, dYdX, and Solana DEXes. Signals delivered via REST API and Telegram.

---

What it does

Zetaperps runs three specialized AI agents continuously:

Agent	What it finds
Funding	Cross-exchange funding rate spreads — when Hyperliquid and dYdX diverge far enough to run a delta-neutral carry
Momentum	Solana tokens with strong buy pressure and volume surges in the last hour
Liquidation	High open-interest clusters that act as price magnets and liquidation cascade zones

All agents run concurrently, results are aggregated and ranked by signal strength, then served via a REST API. Optionally send top signals to a Telegram chat.

---

Quick Start

Option 1 — Source

Prerequisites: Python 3.11+

git clone https://github.com/Zetaperps/Zetaperps.git
cd Zetaperps
pip install -r requirements.txt
cp .env.example .env        # configure Telegram if you want alerts
uvicorn api.main:app --reload --port 8000

Open http://localhost:8000/docs for the interactive API docs.

Option 2 — Docker

git clone https://github.com/Zetaperps/Zetaperps.git
cd Zetaperps
cp .env.example .env
docker-compose up -d

---

API

Base URL: http://localhost:8000

GET /signals                  — all signals, sorted by strength
GET /signals?direction=long   — filter by direction (long/short/neutral)
GET /signals?min_strength=0.5 — filter by minimum strength
GET /signals/funding          — funding arb signals only
GET /signals/momentum         — momentum signals only
GET /signals/liquidation      — liquidation clusters only
GET /agents/markets           — raw market data from all exchanges
GET /health                   — service health

Example response:

{
  "count": 3,
  "signals": [
    {
      "agent": "funding",
      "symbol": "SOL",
      "direction": "long",
      "strength": 0.74,
      "reason": "Funding spread 0.041%/hr — long Hyperliquid (-0.01%) / short dYdX (+0.031%)",
      "data": { "hl_rate": -0.01, "dy_rate": 0.031, "spread": 0.041 },
      "ts": 1718000000.0
    }
  ]
}

---

Configuration

Copy .env.example to .env and edit:

# Telegram (optional)
TELEGRAM_BOT_TOKEN=your_token
TELEGRAM_CHAT_ID=your_chat_id

# Agent tuning
AGENT_INTERVAL=60          # seconds between runs
FUNDING_THRESHOLD=0.02     # minimum funding spread % to generate a signal
MIN_LIQUIDITY=10000        # USD liquidity filter for momentum agent
MIN_OI_USD=5000000         # USD OI floor for liquidation agent

---

Architecture

Orchestrator (60s loop)
├── FundingAgent     → Hyperliquid API + dYdX API
├── MomentumAgent    → DexScreener API
└── LiquidationAgent → Hyperliquid API
         ↓
  Signal Aggregator (sorted by strength)
         ↓
  ┌──────┴──────────┐
  FastAPI REST    Telegram

See docs/architecture.md for full schema and endpoint reference.

---

Development

pip install -r requirements.txt
pytest tests/ -v          # run tests
ruff check .              # lint

---

License

MIT — see LICENSE