Ivy Documentation

Everything under the hood of a perpetual-futures DEX that is structurally incapable of insolvency — the balance sheet, the three invariants, the trading mechanics, and the honest line between what runs today and what ships after audit.

#What is Ivy

Ivy is a permissionless perpetual-futures DEX on Robinhood Chain. You long or short any listed token with leverage. What makes Ivy different is not the trading — it's the settlement layer underneath it.

Most perp exchanges are one bad wick away from a hole in the balance sheet: winners are owed money the exchange doesn't have, and the fix is an ADL queue that picks victims, an "insurance fund" black box, or a socialized-loss email. Ivy ports the percolator risk-engine architecture (originally authored by Anatoly Yakovenko), which makes that entire failure class unrepresentable:

#Quickstart

1. Enter the testnet — hit Enter Testnet. No signup, no wallet signature, no risk.
2. Load an account — paste any 0x… wallet address. Your paper account is seeded with 10,000 USDC.
3. Pick a market — 10 live markets in the left rail, each marked to a real oracle price (Pyth for majors, pinned DEX pairs for Robinhood-native tokens).
4. Open a position — choose Long or Short, set size and leverage, review entry / margin / est. liquidation / fee, execute.
5. Manage it — watch live PnL, ROE, your liquidation price, your ADL index, and your haircut-adjusted withdrawable value. Close whenever.

tip — the Solvency Engine panel at the bottom of the terminal shows the live balance
sheet: vault V, capital C, insurance I, residual, and the haircut H. Everything in the
docs below is visible there, live, while you trade.

#The engine — structural solvency

Every account and every market settles against one global balance sheet:

The entire design follows from one rule: profit can only be paid out of the residual. Capital is always senior to profit. If the residual can't cover every open winner at once, winners are paid at a discount — the haircut — rather than the exchange writing a check it can't cash.

#Invariant 1 · the haircut H

When the system is healthy, H = 100% and profits are fully backed — withdrawing a winner pays out in full. If a violent move creates more paper profit than residual (the exact scenario that bankrupts normal exchanges), H drops below 1 and every winner's withdrawable profit scales by H. Losers and capital are untouched.

• It's a guarantee, not a penalty. H exists so that the statement "you can never withdraw more than exists" is always true — for everyone, simultaneously, at any instant.
• H recovers. As fees accrue, positions close, or the market normalizes, the residual refills and H returns to 100%.
• Fresh profit matures. New profit lands in a per-account reserve R and unlocks over a warm-up window (25 ticks) before it counts as withdrawable — so a one-tick wick can't be printed and instantly extracted.

#Invariant 2 · queue-free ADL (A / K / F)

Every market keeps two side-states — one for longs, one for shorts. Each side carries three lazy indices, updated in O(1) per event no matter how many accounts exist:

When a liquidated account leaves a deficit the insurance buffer can't absorb, the loss socializes into the opposing side's K index — spread pro-rata across every winner on that side:

• No ADL queue. Traditional exchanges rank winners and force-close the top of the queue at a price they didn't choose. Ivy has no queue — deleveraging is a uniform, pro-rata index update.
• No admin discretion. There is no operator deciding who eats the loss. The math is the same for every account, every time.
• Snapshot accounting. Your position stores (basis, A, K, F) at entry; settlement just diffs the current indices against your snapshot. That's why it stays O(1).

#Invariant 3 · bounded cranks

Marks move by crank — a permissionless tick that folds the newest oracle price into K. The crank is bounded:

A flash wick on the oracle therefore can't teleport the mark through a canyon of liquidations in one step — the price walks there tick by tick, each tick settling PnL, liquidations and funding inside a bounded loss budget. Combined with H, this is what makes the worst case slow and solvent instead of instant and bankrupt. It also doubles as a bad-tick guard against oracle glitches.

#Side recovery

If cascading liquidations grind one side's A factor down, that side walks a state machine instead of dying:

#Markets & leverage

Listing is permissionless by design — any token with a reliable live price can carry a market, because the engine never takes directional risk it can't socialize safely. Majors mark to Pyth; Robinhood-native tokens with no Pyth feed mark to a pinned, deep-liquidity DEX pair (a fixed pool address, not a token search — so a thin copycat pool can never become the price). Robinhood natives carry tighter max leverage to reflect their oracle thinness. More markets ship as feeds are added.

#Positions, PnL & liquidation

Positions are isolated sub-accounts: each carries its own collateral C, entry snapshot, and liquidation price. One position blowing up never touches your others.

• Margin — opening a position moves size / leverage from your account into the position as collateral.
• PnL — settled continuously from the K/F index deltas against your entry snapshot, marked to the live oracle.
• Maintenance margin — 0.50% of current notional. You are liquidatable when max(0, C + PnL) ≤ maintenance.
• Liquidation — permissionless. The position is closed, a liquidation fee goes to insurance, the side's A shrinks, and any uninsured deficit socializes into the opposing K (see ADL).
• ADL badge — your positions table shows ADL −x% when your side's A has shrunk: that's the fraction of your effective size that liquidations have already deleveraged, transparently.

#Fees & funding

There is no fee switch pointed at a team wallet in the engine: fees exist to keep the balance sheet solvent. Fee capture for $IVY is a protocol-layer decision that ships with mainnet.

#Withdrawals & H

Your withdrawable balance is always computed under the haircut:

• At H = 100% this is simply capital + PnL.
• Below 100%, your capital and your losses are honored in full — only the profit leg scales. The stress banner and the gold H readout make this state impossible to miss.
• Fresh profit sits in the warm-up reserve R for 25 ticks before it becomes withdrawable.

#The oracle

• Source — Pyth price feeds via Hermes, fetched every ~2.5 seconds per market.
• Marking — each new price enters through the bounded crank (Invariant 3), which also acts as a bad-tick guard.
• Restart safety — after a redeploy, the first tick re-anchors price without marking, so downtime gaps can't print phantom PnL.
• Funding rate — model-based on the paper market (labeled as such in the UI); on-chain funding ships with the program.

#API reference

The testnet exposes a public read/write JSON API — the same one the terminal uses. Base URL: https://ivyrobinhood.xyz

# watch the balance sheet live
curl -s https://ivyrobinhood.xyz/api/metrics | jq '{residual, haircut, oi}'

# open a paper long: 2,500 USDC at 10× on WIF
curl -s -X POST https://ivyrobinhood.xyz/api/open \
  -H 'content-type: application/json' \
  -d '{"wallet":"0xYourAddress","sym":"WIF","side":"long","size":2500,"lev":10}'

#$IVY token

• $IVY is the governance and fee token of the Ivy protocol.
• It is separate from trading collateral — the engine settles in USDC terms; $IVY never backs positions.
• Planned utility: fee capture routing, listing governance (which markets/feeds get added), and insurance-buffer staking — finalized alongside the mainnet program.
• The contract address appears in the site header the moment it's live. Anything else claiming to be $IVY is fake.

#Trust & status — what's real today

#Road to mainnet

Enter the testnet →  Read the FAQ