CryptoFundingArb

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

CryptoFundingArb

★ 16 Open GitHub ↗

Scans funding rates between CEX and DEX and displays the best opportunities

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Funding-Rate Arbitrage Scanner

Scans six major crypto derivatives venues — **Binance, Bybit, OKX, KuCoin, Kraken, and Hyperliquid** — for **funding-rate arbitrage**: market-neutral trades that harvest the difference in perpetual funding rates for the same asset across exchanges. Unlike a naive spread scanner, it models **real trading costs** (fees, funding intervals, holding period) to report the **net** annualized return you could actually keep.

![Top funding-rate arbitrage opportunities: gross vs. net APR](https://raw.githubusercontent.com/hamood1337/CryptoFundingArb/main/docs/hero_chart.png)

> Gross APR (blue) is the raw funding spread. Net APR (green) is what survives after round-trip trading fees — the gap widens the shorter you hold, which is exactly the trade-off this tool makes explicit.

---

## What is funding-rate arbitrage?

Perpetual futures ("perps") have no expiry, so exchanges use a **funding rate** — a periodic payment between longs and shorts — to tether the perp price to spot. When funding is positive, longs pay shorts; when negative, shorts pay longs.

The same asset can have very different funding on different venues. If BTC funding is **+30% annualized** on Exchange A but **−10%** on Exchange B, you can:

- **Short** the high-funding leg (Exchange A) → *earn* funding
- **Long** the low-funding leg (Exchange B) → *pay less* funding

Your net exposure to BTC's price is roughly zero (**delta-neutral**), so you pocket the **funding spread** — here, ~40% annualized — regardless of which way BTC moves. This tool finds and ranks those spreads across venues, then tells you what's left after costs.

---

## Why this implementation is different

The interesting engineering is in turning a noisy, multi-venue data problem into a decision you can trust:

| Concern | How it's handled |
| --- | --- |
| **Net profit, not just spread** | Models per-venue maker/taker fees, computes **net APR** after a full round trip (open + close, both legs) and the **break-even holding time**. |
| **Interval-aware annualization** | Funding is charged on different cadences (Hyperliquid hourly, Binance every 8h). The same raw rate annualizes to wildly different APRs, so the interval is resolved per market — not assumed. |
| **Speed** | Uses each venue's **bulk** funding endpoint (one call for hundreds of symbols) where available, with a threaded per-symbol fallback for venues (KuCoin) that lack it. |
| **Cross-venue symbol matching** | Normalizes contract-size multipliers (`1000PEPE`, `1MBONK`, `kSHIB` → `PEPE`/`BONK`/`SHIB`) so the same underlying lines up across exchanges. |
| **Liquidity filtering** | Filters out thin markets by 24h quote volume so opportunities are actually tradeable. |
| **Resilience** | A venue that is down, rate-limited, or serving a malformed symbol is skipped with a warning — the scan still completes with the rest. |

---

## Architecture

The finance logic is completely decoupled from the network I/O, so the math is deterministic and unit-testable without ever hitting an exchange.

```
                 ┌─────────────┐
   ccxt / net ──▶│ exchanges.py│  I/O boundary: bulk + per-symbol fetch, retries
                 └──────┬──────┘
                        │ FundingSnapshot (immutable)
                 ┌──────▼──────┐
                 │  scanner.py │  orchestrate venues, degrade gracefully
                 └──────┬──────┘
                        │
        ┌───────────────┼────────────────┐
   ┌────▼────┐    ┌─────▼─────┐     ┌─────▼─────┐
   │funding  │    │arbitrage  │     │ fees.py   │   pure, no network
   │.py      │    │.py        │     │           │
   │annualise│    │pair+rank  │     │net PnL    │
   └─────────┘    └─────┬─────┘     └───────────┘
                        │ Opportunity (immutable)
                 ┌──────▼──────┐
                 │  render.py  │  rich tables · chart · JSON/CSV export
                 └─────────────┘
```

Every domain model is an immutable frozen dataclass; transformations return new objects rather than mutating in place.

---

## Installation

```bash
git clone https://github.com/hamood1337/CryptoFundingArb.git
cd CryptoFundingArb

python -m venv .venv && source .venv/bin/activate
pip install -e .          # installs the `fundingarb` command
```

Requires Python 3.10+. No API keys are needed — only public market data is used.

---

## Usage

```bash
# Default scan across all six venues
fundingarb

# Focus on the tradeable band and assume a 3-day hold (fees bite harder)
fundingarb --min-spread 20 --max-spread 300 --holding-days 3

# Only the fastest (bulk) venues, exporting results
fundingarb --exchanges binanceusdm bybit okx hyperliquid \
           --chart opportunities.png --export opps.csv
```

Everything also works without installing, via the compatibility shim:

```bash
python main.py --min-spread 10
```

### Options

| Flag | Default | Description |
| --- | --- | --- |
| `--min-spread` | `5.0` | Minimum gross APR spread (%) to report |
| `--max-spread` | none | Optional cap to hide ephemeral new-listing spikes |
| `--min-volume` | `1_000_000` | Minimum 24h quote volume (USD) per leg |
| `--holding-days` | `30` | Assumed holding period for net-APR amortization |
| `--exchanges` | all six | ccxt exchange ids to scan |
| `--maker-fees` | off | Cost with maker instead of taker fees (optimistic) |
| `--chart PATH` | — | Save a gross-vs-net bar chart |
| `--export PATH` | — | Export all opportunities to `.json` or `.csv` |
| `-v/--verbose` | off | Per-exchange logging |

### Sample output

```
146 opportunities  672 assets  6 venues  54.1s
              Top Funding-Rate Arbitrage Opportunities
┏━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Asset   ┃ Long(pay) ┃ Short(earn)┃ Gross APR┃ Net APR ┃ Break-even┃ Min Vol  ┃
┡━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━┩
│ TAC     │ binance   │ bybit     │    283.1% │  257.5% │     0.3d  │  $47.6M  │
│ POWER   │ bybit     │ kucoin    │    246.8% │  218.8% │     0.3d  │   $1.6M  │
│ VANRY   │ kucoin    │ binance   │    232.4% │  205.6% │     0.3d  │  $22.3M  │
└─────────┴───────────┴───────────┴───────────┴─────────┴───────────┴──────────┘
```

An asset marked with `*` settles in different currencies on the two legs (e.g. USDT vs USDC) — a small extra basis risk worth noting.

---

## Methodology

For a raw funding rate `f` charged every `h` hours:

```
gross_apr   = f × (8760 / h) × 100                     # simple annualization, %
gross_spread = short_apr − long_apr                    # captured before costs
round_trip   = 2 × (taker_long + taker_short) × 100    # open + close, both legs, %
net_apr      = gross_spread − round_trip × (365 / holding_days)
break_even   = round_trip / (gross_spread / 365)       # days of funding to repay costs
```

**Notes & honest caveats.** APR is a *snapshot* annualization of the current funding print, so freshly-listed tokens can show enormous, short-lived numbers — use `--max-spread` to focus on the persistent, tradeable band. Fees default to public **taker** rates (conservative) and are configurable per account tier. The model doesn't include slippage, borrow costs, or the capital cost of margin on both legs.

---

## Testing

```bash
pip install -e ".[dev]"
pytest --cov=fundingarb
```

**87 tests, ~97% coverage.** The pure finance logic (annualization, fee math, pairing, ranking, symbol normalization) is exhaustively unit-tested; the ccxt adapter and orchestrator are tested against fakes so the suite runs offline in under a second.

---

## Roadmap

- [x] Filter out low-volume / illiquid tickers
- [x] Account for maker/taker fees across exchanges
- [x] Faster fetching (bulk endpoints + threaded fallback)
- [x] Test suite with high coverage
- [ ] Backtesting against historical funding series
- [ ] Entry/exit signals (e.g. funding mean-reversion bands)
- [ ] Live monitoring mode with alerts

---

## Credits

Huge thanks to [TheQuantStack](https://www.algos.org/) and [HangukQuant](https://hangukquant.com/) for invaluable information, tips, and code snippets. Highly recommended resources for anyone getting into the quant world.

## Disclaimer

This tool is for educational and informational purposes only. It is not financial advice. Funding-rate arbitrage carries real risks — execution slippage, funding-rate reversals, liquidation on either leg, and exchange counterparty risk. Always do your own research. The author is not responsible for any financial losses incurred from using this tool.

CryptoFundingArb

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README