ORMR_BOROS_PREDICTIVE_BOT

KO | EN

gitlite — search

#hacktoberfest #react #ai #rust #linux #docker #nodejs #macos #awesome #kubernetes #awesome-list #vue #security #pytorch

ORMR_BOROS_PREDICTIVE_BOT

(★ 19)

Automated Trading On Boros Using Synth Predictive API To Gain Your Edge - Check Out The Backtest Dashboard

ORMR_BOROS_PREDICTIVE_BOT Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

```
   ____  _____  __  __ _____
  / __ \|  __ \|  \/  |  __ \
 | |  | | |__) | \  / | |__) |
 | |  | |  _  /| |\/| |  _  /
 | |__| | | \ \| |  | | | \ \
  \____/|_|  \_\_|  |_|_|  \_\

オルムル ~ Funding Rate Serpent
  ─────────────────────────────
  By @DraculaPresley
```

[![X (Twitter)](https://img.shields.io/badge/@DraculaPresley-000000?style=flat&logo=x&logoColor=white)](https://x.com/draculapresley)

# ORMR

**Automated funding rate trading on [Boros](https://boros.pendle.finance) powered by [Synth](https://synthdata.co) volatility intelligence.**

ORMR (Old Norse for *serpent*) is a Python trading bot that captures yield from interest rate swaps on the Boros protocol. It uses Synth's AI-driven volatility forecasts, price predictions, and liquidation cascade detection to time entries, manage risk, and optimize hold duration across multiple assets.

---

## How It Works

ORMR trades **Yield Units (YU)** on Boros — on-chain interest rate swaps where you exchange a fixed APR for a floating funding rate (or vice versa). The bot identifies moments when the rate differential creates profitable carry opportunities, enters positions through an on-chain SDK bridge, and manages them through a multi-layered risk system.

### The Synth Edge

Raw funding rate data is noisy and reactive. ORMR integrates three Synth data streams to see around corners:

| Synth Signal | What It Tells Us | How ORMR Uses It |
|---|---|---|
| **Volatility Forecast** | 24h predicted vs realized vol ratio | Detects vol regime shifts — expansion means funding spikes ahead, contraction means carry conditions |
| **Price Predictions** | Percentile fan (p5 through p95) at 5-min resolution | Direction bias gates entries, percentile spread gauges conviction, terminal forecast filters opposing trades |
| **Liquidation Cascades** | Cluster probability at price thresholds | Predicts funding rate dislocations from forced liquidations — high-conviction spike events |

These signals feed into a **4-case decision engine**:

```
  Synth Vol Expanding (>1.3x)  -->  Funding spike expected   -->  Position for rate rise
  Synth Vol Contracting (<0.8x) -->  Rates compressing        -->  Position for rate fall
  Liquidation Cascade (>65%)    -->  Extreme dislocation       -->  Directional spike trade
  Stable Vol                    -->  Carry conditions          -->  Harvest rate differential
```

Direction bias acts as a **hard gate** — if Synth's price prediction opposes the carry direction, the trade is blocked entirely, not just penalized.

---

## Architecture

```
watchdog.py                 Process supervisor — auto-restart on crash
  +-- run_bot.py            Main loop (5-min cycles, 24/7)
        |
        +-- src/strategies/
        |     vol_regime_trader.py     Strategy engine — scanning, entry, exit, flip
        |
        +-- src/core/
        |     signal_generator.py      Synth-powered 4-case signal logic
        |     risk_manager.py          Position sizing, 10 stop types, cooldowns
        |     telegram_reporter.py     Periodic portfolio + trade reports
        |     logger.py                Session CSV/JSON logging
        |
        +-- src/api/
        |     synth_client_lite.py     Synth API — vol, predictions, liquidations
        |     hl_websocket.py          Hyperliquid WebSocket — live funding + prices
        |     funding_rate_fetcher.py  Multi-exchange funding rate aggregation
        |     boros_sdk_wrapper.py     HTTP bridge to SDK + Boros REST reads
        |
        +-- src/config/
              settings.py              All tunable parameters
```

The **SDK bridge** (`sdk/src/server.ts`) is a lightweight Express server wrapping `@pendle/sdk-boros` for on-chain order execution on Arbitrum.

---

## Strategies

### Carry Trade (Primary)

Harvest the spread between Boros fixed APR and Hyperliquid floating funding rate. SHORT YU = receive fixed, pay floating. Profitable when floating stays below fixed.

- **Entry**: Rate edge exceeds threshold + cost gates + Synth direction confirms
- **Hold**: 24-48h target, minimum hold floor prevents premature exits
- **Exit**: Time stop, carry take-profit, or absolute loss stop

### Vol Regime Flip

When Synth forecasts volatility expansion, funding rates are likely to spike. Position ahead of the move.

- **Entry**: Synth `vol_ratio > 1.3x` with hysteresis to prevent flicker
- **Direction**: LONG YU during expansion (pay fixed, receive spiking float)

### Liquidation Catalyst

Synth detects liquidation cascade clusters near current price. Forced liquidations create predictable funding rate dislocations.

- **Entry**: Cascade probability > 65% within proximity threshold
- **Direction**: Based on which side faces liquidation pressure
- **Hold**: Short duration (6-12h) — capture the spike, exit before normalization

---

## Risk Management

| Control | Description |
|---|---|
| **Absolute loss stop** | 8% of collateral — always active, no minimum hold |
| **Time stop** | Hard exit after configurable hours |
| **Carry take-profit** | Exit at Nx daily carry (configurable multiplier) |
| **Funding reversal** | Exit if underlying rate reverses significantly against entry |
| **Edge decay** | Exit if rate advantage drops below threshold |
| **Emergency drawback** | Exit if unrealized P&L drops 60%+ from peak |
| **Daily circuit breaker** | No new trades if daily loss exceeds limit |
| **Per-asset cooldowns** | Prevent rapid re-entry after stops |
| **Velocity interrupt** | HL WebSocket detects >1% price move in 2 min — triggers early cycle |
| **Oracle wind-down** | Closes positions if Synth/HL data goes stale for >2h |

---

## Setup

### Prerequisites

- Python 3.10+
- Node.js 18+ (for SDK bridge)
- Arbitrum wallet with USDT deposited on [Boros](https://app.boros.finance)
- [Synth API key](https://synthdata.co)

### 1. Clone & Install

```bash
git clone https://github.com/PotluckProtocol/ORMR_BOROS_PREDICTIVE_BOT.git
cd ORMR_BOROS_PREDICTIVE_BOT

# Python dependencies
pip install -r requirements.txt

# SDK bridge
cd sdk && npm install && npm run build && cd ..
```

### 2. Configure

```bash
cp .env.example .env
# Edit .env with your keys
```

| Variable | Required | Description |
|---|---|---|
| `SYNTH_API_KEY` | Yes | Synth API key |
| `WALLET_PRIVATE_KEY` | Yes | Arbitrum wallet private key (0x...) |
| `ARBITRUM_RPC_URL` | Yes | Arbitrum RPC endpoint |
| `TELEGRAM_BOT_TOKEN` | Recommended | Telegram bot for notifications |
| `TELEGRAM_CHAT_ID` | Recommended | Your Telegram chat ID |
| `INITIAL_CAPITAL` | No | Starting capital in USD (default: 1000) |
| `DRY_RUN` | No | `true` for paper trading (default: `false`) |

### 3. Start the SDK Bridge

```bash
cd sdk && npm start
# Runs on localhost:3001 — handles on-chain Boros transactions
```

### 4. Run

```bash
# Paper trading (no real orders)
DRY_RUN=true python run_bot.py

# Live trading
python run_bot.py

# With watchdog (auto-restart on crash)
python watchdog.py
```

### Deploy to Railway

```bash
# Railway auto-detects the Dockerfile
# Set environment variables in the Railway dashboard
# The watchdog process starts automatically
```

---

## Monitoring

- **Telegram** — Portfolio snapshots every 30 minutes, trade events, health alerts
- **CSV Logs** — Signals, trades, funding rates, portfolio state per session in `data/boros_logs/`
- **Status Snapshot** — `data/status_snapshot.json` with live positions, P&L, bridge health, Synth budget

---

## Markets

| Asset | Boros Market | HL Coin | Side |
|---|---|---|---|
| BTC | YU-BTC-HL | BTC | SHORT/LONG |
| XAU | YU-XAU-HL | PAXG | SHORT/LONG |

Additional markets (ETH, SOL, etc.) can be enabled in `src/config/settings.py`.

---

## Project Structure

```
.
+-- run_bot.py              Main entry point
+-- watchdog.py             Process supervisor
+-- requirements.txt        Python dependencies
+-- .env.example            Environment template
+-- Dockerfile              Container build
+-- sdk/
|   +-- src/server.ts       Boros SDK bridge (TypeScript)
|   +-- package.json        Node dependencies
+-- src/
|   +-- api/                External data & execution clients
|   +-- config/             Settings & parameters
|   +-- core/               Signal generation, risk, logging
|   +-- strategies/         Trading strategy implementations
+-- data/                   Runtime logs & state (gitignored)
```

---

## Configuration Reference

All parameters live in `src/config/settings.py`. Here are the key tunables:

### Entry Thresholds

| Parameter | Default | Description |
|---|---|---|
| `BOROS_MIN_EDGE_BPS` | 100 | Minimum rate edge (bps) to consider any trade |
| `LONG_YU_MIN_EDGE_BPS` | 600 | Higher bar for directional LONG YU entries (noisier) |
| `CARRY_ENTRY_THRESHOLD_BPS` | 700 | BTC carry entry — fixed vs floating spread required |
| `CARRY_ENTRY_THRESHOLD_BPS_XAU` | 800 | XAU carry entry — wider due to thinner order book |
| `BOROS_MAX_ENTRY_SPREAD_BPS` | 50 | Skip market if bid/ask spread exceeds this |
| `VOL_EXPANSION_THRESHOLD` | 1.3 | Synth forecast/realized ratio to trigger vol flip |
| `LIQUIDATION_PROB_THRESHOLD` | 0.65 | Cascade probability to trigger liq catalyst |

### Position Sizing

| Parameter | Default | Description |
|---|---|---|
| `BOROS_MAX_POSITION_USD` | 500 | Hard cap per position (USD) |
| `BOROS_DEFAULT_LEVERAGE` | 2 | Default leverage (overridden per-asset) |
| `CARRY_POSITION_SIZE_PCT` | 0.33 | % of capital per carry trade |
| `MAX_TOTAL_EXPOSURE_PCT` | 1.32 | Max total exposure across all positions |
| `DYNAMIC_SIZING_ENABLED` | True | Scale position size with account growth |

### Risk / Stop Losses

| Parameter | Default | Description |
|---|---|---|
| `MAX_UNREALIZED_LOSS_PCT` | 8.0 | Hard stop — close if loss exceeds 8% of collateral |
| `STOP_LOSS_TIME_HOURS` | 48 | Max hold time before forced exit |
| `DAILY_MAX_LOSS_PCT` | 5.0 | Circuit breaker — no new trades after this daily loss |
| `TRAILING_TP_DRAWBACK_PCT` | 20.0 | Close if P&L drops 20% from peak |
| `EMERGENCY_PNL_DRAWBACK_PCT` | 60.0 | Emergency exit if P&L drops 60% from peak |
| `STOP_LOSS_EDGE_DECAY_BPS` | 50 | Close carry if edge drops below 50bps |
| `FUNDING_REVERSAL_THRESHOLD` | 0.5 | Close if funding reverses 50% against entry |

### Hold Time Gates

| Parameter | Default | Description |
|---|---|---|
| `BOROS_MIN_HOLD_HOURS_BEFORE_TP` | 2.0 | No TP/trailing exit before 2h (recover opening fee) |
| `MIN_HOLD_HOURS_BEFORE_RATE_STOP` | 5.0 | No rate-based stop before 5h (funding noise filter) |
| `MIN_HOLD_HOURS_BEFORE_EDGE_DECAY` | 3.0 | No edge-decay stop before 3h |
| `FLIP_GRACE_PERIOD_HOURS` | 6.0 | Wide stop allowance for flip/liq trades during grace |

### Cooldowns

| Parameter | Default | Description |
|---|---|---|
| `EDGE_DECAY_COOLDOWN_HOURS` | 2.0 | Block re-entry after edge-decay stop |
| `FUNDING_STOP_COOLDOWN_HOURS` | 1.5 | Block re-entry after funding stop |
| `REENTRY_COOLDOWN_AFTER_STOP_HOURS` | 1.0 | Block re-entry after any hard stop |
| `FLIP_COOLDOWN_HOURS` | 4.0 | Minimum time between position flips |
| `PRED_STOP_COOLDOWN_HOURS` | 2.0 | Block re-entry after prediction stop |

### Synth API Budget

| Parameter | Default | Description |
|---|---|---|
| `SYNTH_DAILY_CALL_LIMIT` | 750 | Max Synth API calls per day |
| `SYNTH_SCANNING_REFRESH_SEC` | 3600 | Vol/prediction refresh while scanning (1h) |
| `SYNTH_LIQ_ACTIVE_REFRESH_SEC` | 300 | Liquidation refresh with active position (5min) |
| `SYNTH_CACHE_TTL_STABLE_HOURS` | 1.0 | Cache TTL for 24h vol forecast |
| `SYNTH_CACHE_TTL_HIGH_HOURS` | 0.5 | Cache TTL for 1h vol forecast |

### Failsafes

| Parameter | Default | Description |
|---|---|---|
| `ORACLE_MAX_FAILURES` | 3 | Consecutive oracle failures before wind-down |
| `SDK_MAX_FAILURES` | 3 | Consecutive SDK failures before pausing opens |
| `WIND_DOWN_FORCE_CLOSE_HOURS` | 2.0 | Force-close positions after oracle outage (hours) |
| `WS_VELOCITY_EXIT_PCT_CARRY` | 1.5 | Close carry on 1.5% adverse price move in 2min |
| `WS_VELOCITY_EXIT_PCT_DIRECTIONAL` | 2.5 | Close flip/liq on 2.5% adverse move |

### Execution

| Parameter | Default | Description |
|---|---|---|
| `DRY_RUN` | True | Paper trading mode — set `false` for live |
| `TRADABLE_ASSETS` | `["BTC", "XAU"]` | Active markets |
| `PREFERRED_VENUES` | `["Hyperliquid"]` | Permitted Boros settlement venues |
| `TELEGRAM_NOTIFICATIONS` | True | Enable Telegram alerts |
| `TELEGRAM_INTERVAL_MINUTES` | 30 | Portfolio snapshot frequency |

---

## Disclaimer

This software is provided as-is for educational and research purposes. Trading cryptocurrency derivatives involves substantial risk of loss. Past performance does not guarantee future results. Use at your own risk.

---

*Built with [Synth](https://synthdata.co) intelligence and [Pendle Boros](https://boros.pendle.finance) infrastructure.*

ORMR_BOROS_PREDICTIVE_BOT

ORMR_BOROS_PREDICTIVE_BOT Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ORMR_BOROS_PREDICTIVE_BOT

ORMR_BOROS_PREDICTIVE_BOT Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README