# Perpetual Futures — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Knowledge Base Index" type: index updated: 2026-06-19 --- # Knowledge Base Index Master catalog of all wiki pages. Every page in the wiki must have an entry here. ## Concepts | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [what-are-perpetual-futures](concepts/what-are-perpetual-futures.md) | perps, derivatives, basics | high | 2026-06-19 | | [funding-rates](concepts/funding-rates.md) | funding, premium, mark-price | high | 2026-06-19 | | [mark-and-oracle-price](concepts/mark-and-oracle-price.md) | mark-price, index-price, oracle | high | 2026-06-19 | | [margin-and-leverage](concepts/margin-and-leverage.md) | margin, leverage, imf, mmf | high | 2026-06-19 | | [liquidations-and-deleveraging](concepts/liquidations-and-deleveraging.md) | liquidation, adl, insurance-fund | high | 2026-06-19 | | [cross-vs-isolated-margin](concepts/cross-vs-isolated-margin.md) | cross-margin, isolated-margin | high | 2026-06-19 | | [basis-contango-backwardation](concepts/basis-contango-backwardation.md) | basis, contango, backwardation | high | 2026-06-19 | | [positions-long-short-hedging](concepts/positions-long-short-hedging.md) | long, short, hedging, speculation | high | 2026-06-19 | | [order-types-and-execution](concepts/order-types-and-execution.md) | orders, tif, order-book, slippage | high | 2026-06-19 | | [open-interest](concepts/open-interest.md) | open-interest, positioning | high | 2026-06-19 | | [perps-vs-dated-futures-vs-spot](concepts/perps-vs-dated-futures-vs-spot.md) | futures, spot, comparison | high | 2026-06-19 | ## Entities | Page | Tags | Updated | |------|------|---------| | [dydx-reference-venue](entities/dydx-reference-venue.md) | dydx, venue, exchange | 2026-06-19 | ## Summaries | Page | Source | Key Topics | Created | |------|--------|------------|---------| | [venue-api-catalog](summaries/venue-api-catalog.md) | dYdX docs | API surfaces + data objects map | 2026-06-19 | | [concept-map](summaries/concept-map.md) | WP + dYdX | how concepts connect + source catalog | 2026-06-19 | ## Syntheses | Page | Pages Compared | Created | |------|----------------|---------| | [risk-and-blowups-casebook](syntheses/risk-and-blowups-casebook.md) | liquidation/funding/ADL risk modes | 2026-06-19 | ## Statistics - **Total pages**: 15 - **Concepts**: 11 - **Entities**: 1 - **Summaries**: 2 - **Syntheses**: 1 - **Sources ingested**: 93 (22 Wikipedia articles + dYdX docs llms.txt: 1 index + 70 pages) - **High confidence**: 11 - **Medium confidence**: 4 --- title: "Basis, Contango & Backwardation" type: concept tags: [basis, contango, backwardation, funding-arbitrage, carry] updated: 2026-06-19 confidence: medium sources: [raw/web_community-contango-wikipedia.md, raw/web_community-normal-backwardation-wikipedia.md, raw/web_community-futures-contract-wikipedia.md, raw/llms_txt_doc-funding.md, raw/web_community-perpetual-futures-wikipedia.md] --- # Basis, Contango & Backwardation The **basis** is the gap between a futures/perp price and the spot price of the underlying. Its sign names the market state. ## Contango and backwardation - **Contango** — futures price is **above** the expected spot price (an upward-sloping forward curve). A dated contract in contango drifts *down* toward spot as it approaches maturity. - **(Normal) backwardation** — futures price is **below** the expected spot price. The contract drifts *up* toward spot at maturity. For dated futures the basis is mechanically pulled to zero at expiry. A **perpetual has no expiry**, so the basis is instead held near zero continuously by the [funding rate](funding-rates.md) — persistent positive basis shows up as persistently positive funding (longs pay), and vice versa. ## Why traders watch the basis - **Funding/basis arbitrage (cash-and-carry)** — hold spot and short the perp to harvest positive funding while remaining delta-neutral; reverse when funding is negative. This is the most common market-neutral perp strategy. - **Sentiment read** — heavy contango/positive funding signals crowded longs (and the cost of holding them); deep backwardation signals crowded shorts. - **Roll cost** — for dated futures, contango imposes a negative roll yield; perps replace roll cost with funding cost. The basis connects spot, dated futures, and perps — see [perps-vs-dated-futures-vs-spot](perps-vs-dated-futures-vs-spot.md). --- title: "Cross vs Isolated Margin" type: concept tags: [cross-margin, isolated-margin, margin-mode, risk] updated: 2026-06-19 confidence: high sources: [raw/llms_txt_doc-isolated-markets.md, raw/llms_txt_doc-isolated-positions.md, raw/llms_txt_doc-margining.md] --- # Cross vs Isolated Margin The **margin mode** decides how collateral backs your positions. ## Cross margin All positions share one collateral pool. Capital-efficient — gains on one position cushion losses on another — but a single bad position can drain the shared balance and liquidate everything. Default on most venues. ## Isolated margin Collateral is **confined to one position**. Its liquidation can lose at most the margin assigned to it; other positions are untouched. Safer compartmentalization at the cost of capital efficiency (you must top up each position separately). ## How venues implement it On dYdX Chain, **isolated positions** are held in **separate subaccounts** (subaccount numbers >127, up to 128,000), each carrying its own margin — so isolation is literally a separate account boundary. **Isolated markets** additionally let newer/riskier markets exist without endangering cross-margined collateral in the main markets. Implementations differ: some venues offer per-position isolation within one account; others (like dYdX) use subaccounts. ## Choosing - **Isolated** for high-leverage or speculative single bets you want to cap. - **Cross** for hedged or correlated books where shared collateral and netting help. Either way, margin thresholds (IMF/MMF) and [liquidation](liquidations-and-deleveraging.md) work the same within the chosen scope. --- title: "Funding Rates" type: concept tags: [funding, funding-rate, premium, mark-price] updated: 2026-06-19 confidence: high sources: [raw/llms_txt_doc-funding.md, raw/web_community-perpetual-futures-wikipedia.md] --- # Funding Rates Because perpetuals never expire, nothing forces the contract price to converge to spot. The **funding rate** does that job: a periodic payment exchanged **directly between longs and shorts** (on dYdX, longs and shorts pay each other rather than the venue) that incentivizes the perp price back toward the underlying. ## Direction - Perp trading **above** the index → funding is **positive** → **longs pay shorts** → incentivizes selling → price falls. - Perp trading **below** the index → funding is **negative** → **shorts pay longs** → incentivizes buying → price rises. ## How it's calculated (dYdX example) The dominant component is a **premium** measuring how far the book sits from the index: ``` Premium = ( max(0, ImpactBidPrice − IndexPrice) − max(0, IndexPrice − ImpactAskPrice) ) / IndexPrice ``` where the **impact bid/ask** are the average execution prices for a market order of a fixed "impact notional" size — so the premium reflects *real* executable depth, not just the top of book. Venues add an interest-rate component and apply the rate over a funding interval (commonly 8h on CEXs, often hourly on crypto-native venues). Exact formulas and intervals differ per venue. ## Why it matters to traders Funding is a real, recurring cash flow. In strong trends it can be large and persistent (the crowded side pays), so holding a high-funding position bleeds value even if price is flat — and **funding arbitrage** (hold spot, short the perp to collect funding) is a standard basis trade ([basis-contango-backwardation](basis-contango-backwardation.md)). Funding is computed against the [mark/oracle price](mark-and-oracle-price.md), not last trade. --- title: "Liquidations, Insurance Fund & Deleveraging" type: concept tags: [liquidation, deleveraging, insurance-fund, adl, risk] updated: 2026-06-19 confidence: high sources: [raw/llms_txt_doc-liquidations.md, raw/llms_txt_doc-contract-loss-mechanisms.md, raw/web_community-liquidation-wikipedia.md] --- # Liquidations, Insurance Fund & Deleveraging When an account's total value falls **below its maintenance margin** ([margin-and-leverage](margin-and-leverage.md)), the venue force-closes positions to keep the system solvent. ## Liquidation A **liquidation engine** closes the at-risk position — partially or fully — by generating a liquidation order priced at a calculated **"fillable price"** that matches against resting book liquidity. The losing account pays a **liquidation penalty** (dYdX default: up to **1.5%** of remaining value, governance-adjustable), which flows to the **insurance fund**. The engine tries to leave accounts with positive value where possible after the penalty. ## Insurance fund The **insurance fund** absorbs the profit/loss of liquidations. It exists so that when a liquidated position can't be closed at a price that keeps the account ≥ 0, the fund covers the shortfall rather than socializing it — up to a point. ## Auto-deleveraging (ADL) In extreme volatility an account's value can go **negative before it can be liquidated**. Then the **deleveraging system** kicks in: the protocol closes the bankrupt position against **randomly chosen offsetting positions** (profitable traders on the other side), which can reduce those traders' expected profits. ADL is the last-resort backstop that keeps the whole market solvent when the insurance fund is insufficient. ## Trader takeaways - Your **liquidation price** is set by leverage and the [mark/oracle price](mark-and-oracle-price.md), not the order-book price. - Even a winning trader can be **ADL'd** during a crash — it's not a penalty, it's systemic risk. - Mitigations: lower leverage, stop-losses, and watching funding/volatility. Failure modes are collected in [risk-and-blowups-casebook](../syntheses/risk-and-blowups-casebook.md). --- title: "Margin & Leverage" type: concept tags: [margin, leverage, initial-margin, maintenance-margin, collateral] updated: 2026-06-19 confidence: high sources: [raw/web_community-margin-finance-wikipedia.md, raw/web_community-leverage-finance-wikipedia.md, raw/llms_txt_doc-margining.md] --- # Margin & Leverage **Margin** is collateral posted to cover the credit risk of a leveraged position. **Leverage** is the multiple of notional exposure to collateral — higher leverage means a smaller price move wipes out the margin. ## Two margin thresholds Venues define two fractions per market (dYdX terms): - **Initial Margin Fraction (IMF)** — minimum collateral to *open or increase* a position. Determines max leverage (leverage ≈ 1 / IMF). - **Maintenance Margin Fraction (MMF)** — minimum collateral to *keep* a position open; falling below it triggers [liquidation](liquidations-and-deleveraging.md). MMF < IMF, so there's a buffer between opening and getting liquidated. ## Open-interest-based / tiered margin To contain risk from very large positions, the IMF often **scales up with open interest or position size** (tiered margin): the bigger your position relative to the market, the more collateral required and the lower your effective max leverage. This prevents one whale from holding an unliquidatable position. ## The leverage trade-off Leverage amplifies gains *and* losses symmetrically against your margin, and it shrinks the distance to your liquidation price. It also interacts with [funding](funding-rates.md): a leveraged position pays/receives funding on the full notional, not on your margin — so funding can dominate returns at high leverage. How collateral is shared or isolated across positions is the [cross-vs-isolated](cross-vs-isolated-margin.md) decision. --- title: "Mark Price & Oracle/Index Price" type: concept tags: [mark-price, index-price, oracle, valuation] updated: 2026-06-19 confidence: high sources: [raw/llms_txt_doc-oracle-prices.md, raw/web_community-mark-to-market-accounting-wikipedia.md] --- # Mark Price & Oracle/Index Price Perp accounting is **marked to market** continuously — positions are revalued against a reference price rather than their entry price, so unrealized PnL, margin health, and liquidation triggers update in real time. ## Index / oracle price The **index price** (dYdX: **oracle price**) is an aggregated, manipulation-resistant estimate of the underlying's true price, typically a weighted median across major spot venues. On dYdX Chain it is determined by the **validator set** each block. It is used to: - check each account stays **well-collateralized** after every trade, - decide **when to liquidate**, - trigger **stop-limit / take-profit** order types. ## Mark price vs last trade The **mark price** is what margin and liquidation are measured against. Using an external, aggregated reference (rather than the perp's own last trade) prevents a thin order book or a single wick from triggering cascades of unfair liquidations. The [funding rate](funding-rates.md) is also computed against this reference, not last trade. ## Why a trader cares Your liquidation happens at the **mark/oracle** price, which can differ from the price you see fill on the book — especially in fast markets. Two accounts with identical entry and size can have different liquidation distances only because of leverage and margin mode ([margin-and-leverage](margin-and-leverage.md), [cross-vs-isolated-margin](cross-vs-isolated-margin.md)). --- title: "Open Interest" type: concept tags: [open-interest, positioning, liquidity] updated: 2026-06-19 confidence: medium sources: [raw/web_community-open-interest-wikipedia.md, raw/llms_txt_doc-margining.md, raw/llms_txt_doc-funding.md, raw/web_community-perpetual-futures-wikipedia.md] --- # Open Interest **Open interest (OI)** is the total number of **outstanding (unsettled) contracts** in a market — positions opened but not yet closed. Unlike **volume** (contracts traded in a period), OI counts contracts currently *live*. A trade can raise OI (both sides opening), lower it (both closing), or leave it flat (one opening, one closing). ## Why it matters for perps - **Liquidity & conviction** — rising OI with rising price suggests new money backing the move; rising price with falling OI suggests short-covering rather than fresh longs. - **Crowding & funding** — high OI concentrated on one side tends to push [funding](funding-rates.md) and signals liquidation-cascade risk if price turns. - **Margin scaling** — venues tie **initial margin to open interest** (open-interest-based IMF, [margin-and-leverage](margin-and-leverage.md)): as a market's OI grows, required margin rises and max leverage falls, capping systemic risk. ## Reading OI OI is a positioning gauge, not a price predictor on its own — it's most useful combined with price and funding. Spikes in OI before high-volatility events often precede the largest [liquidation](liquidations-and-deleveraging.md) cascades. --- title: "Order Types, Time-in-Force & Execution" type: concept tags: [orders, time-in-force, order-book, slippage, market-maker] updated: 2026-06-19 confidence: high sources: [raw/llms_txt_doc-ordertype.md, raw/llms_txt_doc-time-in-force.md, raw/web_community-order-book-wikipedia.md, raw/web_community-slippage-finance-wikipedia.md, raw/web_community-bid-ask-spread-wikipedia.md, raw/web_community-market-maker-wikipedia.md] --- # Order Types, Time-in-Force & Execution ## Order types - **Limit** — executes at a specified price or better; rests on the book if not immediately marketable. - **Market** — executes immediately against resting liquidity at whatever prices are available (subject to slippage). - **Stop-Limit / Take-Profit** — "triggerable" orders that activate when the [mark/oracle price](mark-and-oracle-price.md) crosses a trigger, then submit a limit/market order. Used to cap losses or lock gains. ## Time-in-force (TIF) How long an order stays active: - **Default / GTT** — match against the book, rest the remainder as a maker order. - **IOC** (immediate-or-cancel) — fill what's available now, cancel the rest. - **FOK** (fill-or-kill) — fill entirely now or cancel completely. - **Post-only** — never take liquidity; cancel if it would (guarantees maker rebate / avoids taker fee). ## Execution and the order book The **order book** ranks resting bids and asks by price; the **bid–ask spread** is the gap between best bid and best ask — a direct cost of round-tripping a position. **Slippage** is the difference between expected and actual fill price when an order is larger than the available depth at the top of book. **Market makers** quote both sides to earn the spread and supply the liquidity takers consume; on perps their quoting is also what the [funding premium](funding-rates.md)'s "impact price" measures against. Thin books → wide spreads, more slippage, and more liquidation risk in fast markets. --- title: "Perps vs Dated Futures vs Spot" type: concept tags: [futures, spot, settlement, comparison, derivatives] updated: 2026-06-19 confidence: high sources: [raw/web_community-futures-contract-wikipedia.md, raw/web_community-futures-exchange-wikipedia.md, raw/web_community-settlement-finance-wikipedia.md, raw/web_community-derivative-finance-wikipedia.md] --- # Perps vs Dated Futures vs Spot Three ways to get exposure to an asset, with different settlement and leverage profiles. ## Spot Buy/sell the actual asset for immediate **settlement** (delivery of the asset against payment). You own it; no expiry, no funding, no liquidation — but no built-in leverage and capital is fully committed. ## Dated futures A standardized contract to buy/sell at a **fixed future date** at an agreed price, traded on a [futures exchange](order-types-and-execution.md) and marked to market daily. Key traits: - **Expiry & convergence** — price converges to spot at maturity; the [basis](basis-contango-backwardation.md) goes to zero. - **Roll** — to maintain exposure past expiry you must roll to the next contract, paying/earning the roll yield (contango/backwardation). - **Settlement** — physical delivery or cash settlement at expiry. ## Perpetual futures Like a dated future but **no expiry** ([what-are-perpetual-futures](what-are-perpetual-futures.md)). Convergence is maintained continuously by the [funding rate](funding-rates.md) instead of by maturity, eliminating rolls. This is why perps dominate crypto derivatives volume: continuous leveraged exposure with no expiry management. ## Quick comparison | | Spot | Dated future | Perpetual | |---|---|---|---| | Expiry | none | fixed date | none | | Leverage | no | yes | yes | | Price anchor | — | convergence at expiry | funding rate | | Ongoing cost | none | roll yield | funding | | Liquidation | no | yes | yes | All three are linked by the [basis](basis-contango-backwardation.md); arbitrage between them keeps prices consistent. --- title: "Positions: Long, Short, Hedging & Speculation" type: concept tags: [long, short, hedging, speculation, positions] updated: 2026-06-19 confidence: medium sources: [raw/web_community-long-finance-wikipedia.md, raw/web_community-short-finance-wikipedia.md, raw/web_community-hedge-finance-wikipedia.md, raw/web_community-speculation-wikipedia.md, raw/llms_txt_doc-funding.md, raw/web_community-perpetual-futures-wikipedia.md] --- # Positions: Long, Short, Hedging & Speculation ## Long and short - **Long** — you profit when price rises. In perps, going long means buying the contract; you pay/receive [funding](funding-rates.md) depending on its sign. - **Short** — you profit when price falls. Perps make shorting trivial and symmetric to longing (no borrow/locate as in equities short-selling) — a key reason crypto traders use them. Both are leveraged claims backed by [margin](margin-and-leverage.md); both can be [liquidated](liquidations-and-deleveraging.md). ## Hedging vs speculation - **Hedging** — taking a perp position to *offset* existing exposure (e.g. a miner or token-holder shorts a perp to lock in a price; a market maker hedges inventory). The goal is risk reduction, not profit. - **Speculation** — taking a position to profit from a price view, accepting risk for return. Most perp volume is speculative, but the two coexist: speculators provide the liquidity hedgers need. ## Delta-neutral structures Combining a spot holding with an offsetting short perp creates a **delta-neutral** position that isolates the [basis/funding](basis-contango-backwardation.md) — the canonical "earn funding without price risk" trade. Hedging plus the funding mechanism is what keeps perps anchored to spot. --- title: "What Are Perpetual Futures" type: concept tags: [perpetual-futures, perps, derivatives, basics] updated: 2026-06-19 confidence: high sources: [raw/web_community-perpetual-futures-wikipedia.md, raw/web_community-futures-contract-wikipedia.md, raw/web_community-derivative-finance-wikipedia.md, raw/llms_txt_doc-perpetuals-and-assets.md] --- # What Are Perpetual Futures A **perpetual future** (or **perpetual swap**, "perp") is a derivative contract that tracks an underlying asset's price **but has no expiry date** — so there is no final settlement or delivery, and a position can be held indefinitely. ## How they differ from dated futures A traditional [futures contract](perps-vs-dated-futures-vs-spot.md) obligates the parties to settle at a fixed expiry, and its price converges to spot at maturity. A perpetual has no maturity to force convergence, so it uses a **[funding rate](funding-rates.md)** instead: periodic payments between longs and shorts that pull the contract price toward the underlying ([mark/oracle price](mark-and-oracle-price.md)). This is the single defining mechanism of a perp. ## Why traders use them - **Indefinite exposure** — speculate on price (long or short) without holding the underlying token, and without rolling expiring contracts. - **Leverage** — post margin to control a larger notional ([margin-and-leverage](margin-and-leverage.md)). - **Continuous markets** — especially in crypto, perps trade 24/7 and are the dominant derivative by volume. ## The core machinery (rest of this wiki) A perp position is governed by: the [funding rate](funding-rates.md) (keeps price near index), [margin and leverage](margin-and-leverage.md) (collateral), [liquidation](liquidations-and-deleveraging.md) (forced close when collateral runs out), and the [mark/oracle price](mark-and-oracle-price.md) (what margin and liquidation are measured against). Concrete venue implementations vary; this wiki uses [dYdX](../entities/dydx-reference-venue.md) as a worked example, and the [Hyperliquid wiki] covers another. Trust note: concepts here are encyclopedic; venue specifics are dYdX's defaults and differ across exchanges. --- title: "dYdX (Reference Venue)" type: entity tags: [dydx, venue, exchange, perpetuals] updated: 2026-06-19 confidence: high sources: [raw/llms_txt_doc-perpetuals-and-assets.md, raw/llms_txt_doc-intro-to-dydx-chain-architecture.md] --- # dYdX (Reference Venue) This wiki uses **dYdX Chain (v4)** as a concrete, well-documented example of how the perpetual-futures concepts are actually implemented. dYdX is a decentralized perpetuals exchange; its public docs are the source for the venue-specific mechanics cited throughout (funding, margining, liquidations, oracle prices). ## Architecture (why it's a clean example) dYdX Chain ("v4") is a standalone **L1 blockchain** (built with Cosmos SDK + CometBFT) designed to be fully decentralized end-to-end. Three open-source components: - **Protocol / application** — the L1 chain running an in-protocol **order book and matching** (orders are matched off-chain in the validator mempool, settled on-chain), the [margining](../concepts/margin-and-leverage.md), [liquidation](../concepts/liquidations-and-deleveraging.md), and [funding](../concepts/funding-rates.md) logic. - **Indexer** — reads chain state and serves the REST/WebSocket APIs apps use. - **Front end** — the trading UI. None are run by dYdX Trading Inc.; the network is operated by validators who also supply the [oracle prices](../concepts/mark-and-oracle-price.md). ## Why a venue example matters The encyclopedic concept pages describe perps in general; real numbers (the 1.5% max liquidation penalty, IMF/MMF, impact-notional premium, subaccount-based isolation) are **dYdX's defaults** and differ across CEXs and other DEXs. Treat them as one worked implementation. Its API surface is mapped in [venue-api-catalog](../summaries/venue-api-catalog.md); other venues (e.g. the Hyperliquid wiki) implement the same concepts differently. --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion ### 2026-06-19 00:00 — Initial curation (medium rung) - **Source/Trigger**: 93 raw sources (22 Wikipedia articles + dYdX v4 docs llms.txt: 70 pages + index) - **Pages created**: 11 concepts, 1 entity (dydx-reference-venue), 2 summaries (venue-api-catalog, concept-map), 1 synthesis (risk-and-blowups-casebook) - **Pages updated**: index.md - **Notes**: Knowledge domain. Encyclopedic backbone (Wikipedia) + dYdX as one worked venue; trust level declared. basis-of-futures WP page was empty -> not cited. risk casebook confidence:medium. --- title: "Concept Map & Source Catalog" type: summary tags: [catalog, map, glossary, sources] updated: 2026-06-19 confidence: high sources: [raw/web_community-perpetual-futures-wikipedia.md, raw/llms_txt-llms-txt-index.md] --- # Concept Map & Source Catalog How the perpetual-futures concept space fits together and where each piece is sourced. Two source families in `raw/`: **Wikipedia** (`web_community-*-wikipedia.md`, encyclopedic backbone) and **dYdX docs** (`llms_txt_doc-*.md`, one worked venue). ## The mechanism, in one paragraph A perp tracks an asset with **no expiry** ([what-are-perpetual-futures](../concepts/what-are-perpetual-futures.md)); the **funding rate** ([funding-rates](../concepts/funding-rates.md)) keeps its price near the **mark/oracle price** ([mark-and-oracle-price](../concepts/mark-and-oracle-price.md)). You open it with **margin** at some **leverage** ([margin-and-leverage](../concepts/margin-and-leverage.md)), in **cross or isolated** mode ([cross-vs-isolated-margin](../concepts/cross-vs-isolated-margin.md)); if collateral falls below maintenance margin you're **liquidated**, with an insurance fund and **ADL** as backstops ([liquidations-and-deleveraging](../concepts/liquidations-and-deleveraging.md)). The **basis** vs spot ([basis-contango-backwardation](../concepts/basis-contango-backwardation.md)) drives funding and arbitrage; **open interest** ([open-interest](../concepts/open-interest.md)) gauges positioning; you trade via **orders** on a book ([order-types-and-execution](../concepts/order-types-and-execution.md)) going **long or short / hedging** ([positions-long-short-hedging](../concepts/positions-long-short-hedging.md)). Compare to [dated futures and spot](../concepts/perps-vs-dated-futures-vs-spot.md). ## Source families | Topic | Wikipedia sources | Venue (dYdX) sources | |---|---|---| | Core perp / futures | perpetual-futures, futures-contract, derivative-finance, futures-exchange | perpetuals-and-assets | | Funding & pricing | mark-to-market-accounting | funding, oracle-prices | | Margin & liquidation | margin-finance, leverage-finance, liquidation | margining, liquidations, contract-loss-mechanisms, isolated-markets/positions | | Basis | contango, normal-backwardation | (funding) | | Microstructure | order-book, market-maker, slippage, bid-ask-spread | ordertype, time-in-force | | Positioning | long-finance, short-finance, hedge-finance, speculation, open-interest, arbitrage, settlement-finance | — | ## Trust level Concepts are encyclopedic (stable, venue-neutral). Numeric specifics (penalties, margin fractions, funding formula details) are **dYdX defaults** and vary by venue — always confirm against the venue you actually trade on. Live prices, funding, and OI require a market data source, not this wiki. --- title: "Venue API Catalog (dYdX)" type: summary tags: [api, catalog, dydx, reference] updated: 2026-06-19 confidence: high sources: [raw/llms_txt-llms-txt-index.md, raw/llms_txt_doc-perpetualmarket.md, raw/llms_txt_doc-order.md, raw/llms_txt_doc-fundingpaymentresponseobject.md, raw/llms_txt_doc-perpetualpositionresponseobject.md, raw/llms_txt_doc-tradingperpetualmarket.md] --- # Venue API Catalog (dYdX) The dYdX docs (docs.dydx.xyz, ~70 pages mirrored in `raw/`) are this wiki's worked example of a perp venue's integration surface. This page maps that space so an agent fetches the exact reference page; the concept pages distill the trading mechanics. ## API surfaces - **HTTP / REST API** (`http-rest-api`, `node-api`, `public-api`, `private-api`) — query markets, account state, fills, funding payments. - **WebSocket API** (`websockets-api`) — streaming order book, fills, subaccount updates. - **Indexer** (`indexer-deep-dive`) — the read layer behind the APIs. - **Permissioned keys** (`permissioned-keys`, `permissioned-keys-api`) — scoped trading keys. ## Core data objects (one ref page each in raw/) - Markets: `PerpetualMarket`, `TradingPerpetualMarket`, `ClobPairId`, `quantums-and-subticks`. - Orders: `Order`, `OrderType`, `TimeInForce`, `OrderResponseObject`, `OrderSubaccountMessage`. - Positions/accounts: `accounts-and-subaccounts`, `PerpetualPositionResponseObject`, `AssetPositionSubaccountMessage`, `SubaccountResponseObject`. - Fills & funding: `FillResponseObject`, `FillType`, `FundingPaymentResponseObject`. - Advanced: `BuilderCodeParameters`, `TwapParameters`, `megavault` (pooled liquidity vault). ## Trading mechanics pages (distilled into this wiki) `funding` → [funding-rates](../concepts/funding-rates.md); `margining` → [margin-and-leverage](../concepts/margin-and-leverage.md); `liquidations` + `contract-loss-mechanisms` → [liquidations-and-deleveraging](../concepts/liquidations-and-deleveraging.md); `oracle-prices` → [mark-and-oracle-price](../concepts/mark-and-oracle-price.md); `isolated-markets` / `isolated-positions` → [cross-vs-isolated-margin](../concepts/cross-vs-isolated-margin.md). For exact request/response shapes, read the specific object page in `raw/`. Other venues expose different APIs for the same concepts. --- title: "Risk & Blow-ups Casebook" type: synthesis tags: [risk, liquidation, funding, casebook] updated: 2026-06-19 confidence: medium sources: [raw/llms_txt_doc-contract-loss-mechanisms.md, raw/llms_txt_doc-liquidations.md, raw/llms_txt_doc-funding.md, raw/web_community-perpetual-futures-wikipedia.md] --- # Risk & Blow-ups Casebook The recurring ways perp accounts lose money beyond simply being wrong on direction. Confidence medium — synthesis across the concept pages; venue specifics are dYdX defaults. ## 1. Liquidated by the mark price, not the last trade Liquidation triggers off the [mark/oracle price](../concepts/mark-and-oracle-price.md). In a fast move the book can wick far past the oracle, or the oracle can move while your limit sits unfilled — you get liquidated at a level you "never saw trade." Mitigation: lower leverage widens the gap to liquidation; use stop-losses that trigger before maintenance margin. ## 2. The liquidation penalty eats the remainder A liquidation isn't a clean close at your stop — it pays a **penalty** (dYdX: up to 1.5%) to the insurance fund and crosses the spread via the "fillable price" ([liquidations-and-deleveraging](../concepts/liquidations-and-deleveraging.md)). You almost always recover less than "margin minus the price move." ## 3. Auto-deleveraging takes your winning trade In a crash, bankrupt accounts can be **ADL'd against profitable opposite positions** chosen at random. A correct, in-profit position can be force-closed early — systemic risk, not a fee. More likely when the insurance fund is stressed and OI is one-sided ([open-interest](../concepts/open-interest.md)). ## 4. Funding bleed on a crowded trade Holding the crowded side pays [funding](../concepts/funding-rates.md) every interval. At high leverage funding is charged on full notional, so a flat-but-crowded position can bleed to liquidation. Persistent positive funding is also a crowding warning sign. ## 5. Leverage + thin liquidity = slippage cascades High leverage in a thin book ([order-types-and-execution](../concepts/order-types-and-execution.md)) means small moves trigger liquidations, whose forced market orders move price further, triggering more — the cascade. Avoid max leverage on illiquid markets; size to the book's depth. ## Standing checklist - Size to **liquidation distance**, not just margin. - Check **funding** before holding overnight. - Prefer **isolated margin** to cap single-position blow-ups ([cross-vs-isolated-margin](../concepts/cross-vs-isolated-margin.md)). - Remember even winners face **ADL** in extreme events.