Funding rate
intelligence for
Hyperliquid

Osprey scans every Hyperliquid perpetual every minute, scores funding rate opportunities, and helps you execute delta-neutral positions via MetaMask — in demo or live mode.

🚀 Quick Start

Demo mode works immediately with no wallet or API key. Takes under 2 minutes.

# Clone and install
git clone https://github.com/Xtley001/osprey.git
cd osprey
npm install

# Copy env and start dev server
cp .env.example .env.local
npm run devbash

Opens at http://localhost:5173. The scanner fetches live HL data immediately. No configuration needed for demo mode.

Production build

npm run build          # TypeScript compile + Vite bundle
npm run typecheck      # tsc --noEmit — must report 0 errors
npm test               # 71 unit tests across engine + math + utilitiesbash

Deploy to Vercel

npm i -g vercel
vercel --prod          # vercel.json SPA rewrites pre-configuredbash

⚙️ Local Setup

Environment variables

Copy .env.example to .env.local and configure:

Fee tiers

If your 30-day HL volume qualifies for a reduced fee tier, update src/utils/constants.ts: the backtester and all fee previews recalculate automatically.

export const DEFAULT_STRATEGY = {
  takerFee: 0.00035,   // ← update to match your volume tier
  makerFee: 0.0001,    // ← update to match your volume tier
  // ... other strategy defaults
};typescript

🧪 Testnet Guide

Before using live order execution on mainnet, always verify signing works on HL testnet. This is a 2–4 hour process.

1. 1
   Point at testnet

   In .env.local, set VITE_HL_REST_URL=https://api.hyperliquid-testnet.xyz

2. 2
   Get testnet funds

   Visit app.hyperliquid-testnet.xyz and request test USDC from the faucet.

3. 3
   Connect testnet wallet

   Connect MetaMask with a wallet that holds testnet funds. Osprey fetches your testnet balance automatically.

4. 4
   Place a minimum-size order

   Select a liquid pair (BTC recommended), enter the smallest allowable size, and submit. Watch the raw response from the /exchange endpoint in devtools — the error message will identify any signing issue precisely.

5. 5
   Confirm, then flip to mainnet

   Once the order appears in your testnet account, set VITE_HL_REST_URL back to the mainnet URL.

📡 Live Scanner

The scanner fetches the full metaAndAssetCtxs payload from Hyperliquid every 60 seconds and renders all active perpetual markets as a sortable, filterable heatmap.

Rate classification

TradFi pairs

Osprey covers HL's full TradFi listing — stocks, commodities, and private-company perps. These often carry elevated funding due to thinner liquidity and smaller trader base.

Stocks: NVDA, AAPL, GOOGL, TSLA, AMZN, MSFT, META, NFLX, AMD, COIN, MSTR, PLTR, UBER
Private: SPACEX
Commodities: GOLD, SILVER, WTIOIL, NATGAS, COPPER

🧠 Regime Detection

The regime engine computes a market-wide signal by aggregating the top 20 perpetuals by open interest (OI). This distinguishes between a market where funding is structurally elevated vs. isolated spikes on one pair.

🎯 Entry Signals

Each pair receives a per-pair signal requiring rate persistence — funding must remain elevated for at least 2 consecutive hours before an ENTER fires. This filters out transient spikes that don't persist long enough to cover fees.

Default thresholds

entryRateThreshold:  0.0004   // per-hour rate (≈ 0.04% / 8h equivalent)
exitRateThreshold:   0.0002   // exit when rate falls below this
minHoursElevated:    2        // consecutive hours above threshold requiredtypescript

📊 Backtester

A pure TypeScript simulation engine. Hour-by-hour replay using real HL historical data from the fundingHistory API endpoint. No external dependencies — fully deterministic and testable.

What it calculates

🤖 Auto-Trader

The auto-trader runs a decision cycle every 60 seconds. In demo mode it executes automatically with no confirmation. In live mode, it prompts MetaMask for each order.

Cycle logic

// Every 60 seconds:
1. Fetch live rates from HL
2. Compute regime signal
3. For each open position: check EXIT signal → close if triggered
4. Check rotation: if a better pair > ROTATION_THRESHOLD better, flag rotation
5. Scan for new ENTER signals (up to maxPositions limit)
6. Place orders for new entriestypescript

⚡ Live Trading Beta

Live order execution is functional but labeled Beta until signing has been verified on testnet. Everything else in Osprey is production-ready.

What works

Trading flow

1. 1
   Deposit USDC on Hyperliquid

   At app.hyperliquid.xyz — this is your trading capital.

2. 2
   Connect MetaMask in Osprey Settings

   Osprey fetches your real HL balance automatically. Your private key never leaves MetaMask.

3. 3
   Switch sidebar to Live mode

   The mode banner changes from demo to live. All signals now use your real balance as the ceiling for position sizing.

4. 4
   Click Enter on a pair with ENTER signal

   Modal shows real balance, size slider, fee preview, break-even hours, and projected hourly income.

5. 5
   Confirm → MetaMask prompt → order sent

   Osprey signs and submits the perp short to HL. MetaMask displays the EIP-712 typed data for your review before signing.

6. 6
   Execute spot hedge manually

   HL spot or a CEX for the long leg. This step is always manual — HL's spot market doesn't cover all perp pairs.

🔐 EIP-712 Signing

Osprey uses Hyperliquid's phantom agent signing scheme. The signer never sees the raw order — it signs a typed hash of a connectionId derived from the action.

// 1. Hash the serialised action JSON
const actionHash = ethers.keccak256(
  ethers.toUtf8Bytes(JSON.stringify(action))
);

// 2. Build the connectionId
const connectionId = ethers.keccak256(
  ethers.AbiCoder.defaultAbiCoder().encode(
    ['bytes32', 'uint64', 'address'],
    [actionHash, BigInt(nonce), vaultAddress ?? ethers.ZeroAddress]
  )
);

// 3. Sign the phantom agent — domain is always chainId 1337
const domain = {
  name: 'Exchange', version: '1',
  chainId: 1337,     // HL uses 1337 regardless of actual chain
  verifyingContract: '0x0000000000000000000000000000000000000000',
};
const types  = { Agent: [
  { name: 'source',       type: 'string'  },
  { name: 'connectionId', type: 'bytes32' },
]};
const value  = { source: 'a', connectionId };

const sig = await signer.signTypedData(domain, types, value);typescript

💰 Fee Model

Osprey v18 uses minimum-fee order routing by default. Entry orders use post-only maker (Alo), exits use immediate-or-cancel taker (Ioc).

Volume tiers

If an Alo order is rejected by the matching engine (fast market, would immediately cross), Osprey's error message will include "Would immediately cross" — retry with tif: 'Ioc'.

🏗️ Architecture

src/
├── api/
│   └── hyperliquid.ts      ← HL REST client, EIP-712 signing, order placement
├── engine/
│   ├── autotrader.ts       ← cycle engine: enter/exit/rotate decision logic
│   ├── backtester.ts       ← hourly simulation over historical funding + OHLCV
│   ├── regime.ts           ← HOT/NEUTRAL/COLD market regime classifier
│   └── signals.ts          ← per-pair ENTER/WAIT/EXIT/AVOID signal generator
├── store/
│   ├── appStore.ts         ← wallet, mode, regime state (Zustand)
│   ├── autoTraderStore.ts  ← auto-trader config + cycle runner
│   ├── positionStore.ts    ← open positions (demo + live)
│   └── scannerStore.ts     ← live funding rate cache
├── pages/                  ← Scanner · PairDetail · Backtester · Portfolio · Analytics · Settings
├── components/             ← EntryModal · PositionTicker · AutoTraderService · …
└── types/                  ← TypeScript interfaces for all domain objectstext

Tech stack

📋 Environment Reference

# .env.example — copy to .env.local

# Mainnet (default)
VITE_HL_REST_URL=https://api.hyperliquid.xyz
VITE_HL_WS_URL=wss://api.hyperliquid.xyz/ws

# Testnet — uncomment to test signing before mainnet
# VITE_HL_REST_URL=https://api.hyperliquid-testnet.xyz
# VITE_HL_WS_URL=wss://api.hyperliquid-testnet.xyz/ws

# Feature flags
VITE_ENABLE_REAL_TRADING=true   # set false to hide Live Mode toggle
VITE_ENABLE_TESTNET=true        # set false to disable testnet switchbash

🗺️ Roadmap

Immediate

Next 30 days

60–90 days