gavindiaz/PolymarketDocumentation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: sync Polymarket docs updates 2026-07-13 - add 90 new pages incl. Perps section

Browse Source
This commit is contained in:
GLaDOS
2026-07-13 01:40:25 +02:00
parent 714c66e5b3
commit 2d608bd891
91 changed files with 31279 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/perps/learn-about-trading/architecture.md
+49
View File
@@ -0,0 +1,49 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture
> High-level architecture of the Polymarket Perps exchange
Polymarket Perps is a hybrid exchange: matching happens offchain for speed, while
custody and settlement live on Polygon. Exchange state is periodically committed
onchain so offchain activity remains verifiable.
## Offchain Matching
When a trader places an order, the matching engine maintains the order book,
applies risk checks, matches orders, and updates balances, positions, margin, and
funding offchain. This gives the exchange its latency profile because matching
does not wait on block times.
Orders are authorized by the trader, so the system can only act on trades the
trader approved.
## Onchain Components
The following operations are onchain and settle on Polygon:
* Deposits move funds from a user's Polymarket wallet into the exchange and
credit their Perps account.
* Withdrawals move funds out of the exchange back to a user's Polymarket wallet.
Deposits and withdrawals are the only way assets enter or leave the exchange.
Trading itself does not produce per-trade onchain transactions.
## State Root Commitments
The exchange periodically commits its trading state onchain in the form of state
root commitments. A state root summarizes the offchain ledger at a point in time,
including account balances, and lets observers verify that reported exchange
state matches what Polymarket has committed to Polygon.
## Data Flow
1. A trader deposits collateral from their Polymarket wallet into the exchange,
crediting their Perps account.
2. The engine credits the deposit and opens the account for trading.
3. The trader authorizes and places orders.
4. The engine matches orders and updates state offchain.
5. The engine publishes state root commitments onchain on a recurring cadence.
6. The trader authorizes a withdrawal, and funds move back to their Polymarket wallet on Polygon.
docs/perps/learn-about-trading/fees.md
+78
View File
@@ -0,0 +1,78 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fees
> Tiered maker and taker trading fees for Polymarket Perps
Perps trading fees are tiered by an account's trailing 30-day trading volume.
Higher-volume accounts pay lower taker fees, and the top tier earns a maker
rebate instead of paying a maker fee.
## Fee Calculation
For each fill, the fee is calculated on the notional value of the trade:
```text theme={null}
Fee = abs(Price * Quantity) * Rate
```
Fees are denominated in the instrument's quote asset (pUSD). The rate applied
to a fill is set by the account's current volume tier.
| 30-Day Volume ≥ | Taker | Maker |
| --------------- | ------- | -------- |
| \$0 | 0.0400% | 0.0125% |
| \$1M | 0.0370% | 0.0100% |
| \$5M | 0.0350% | 0.0080% |
| \$25M | 0.0300% | 0.0050% |
| \$100M | 0.0270% | 0.0020% |
| \$500M | 0.0250% | 0.0000% |
| \$1B | 0.0200% | -0.0050% |
New accounts start at the \$0 tier and move up as trailing 30-day volume crosses
each threshold.
A negative maker fee is a rebate: the maker receives the rebate amount, and the
fee recipient's internal ledger is debited by the same amount.
<Note>
A subset of accounts created during the Perps beta are temporarily on the
top-tier fee schedule regardless of trailing 30-day volume. Standard
volume-based tiering applies to these accounts once the transition period
ends.
</Note>
If you're integrating Perps, read the current fee schedule from
[Trading Fees](/perps/trading#trading-fees).
## Fee Metrics
Trailing 7-day activity metrics are available for visibility. They are a
rolling view of recent activity and do not, on their own, determine the volume
tier used to set fees.
| Metric | Meaning |
| ------------------- | ------------------------------------------------------------------------------ |
| Total volume | Total Perps trading volume |
| Taker volume | Perps volume that removed liquidity |
| Maker volume | Perps volume that added liquidity |
| Account maker share | Account maker volume divided by total exchange volume |
| Entity maker share | Entity maker volume divided by total exchange volume, when the account has one |
These metrics are cached by UTC day and may be stale by up to 24 hours.
If you're integrating Perps, read account metrics from
[Account Stats](/perps/account-management#account-stats).
## Fee Accounting
Every fill's fee flows through a single fee-recipient account on the internal
ledger:
* Taker fees credit the recipient.
* Maker fees credit the recipient at every tier where the maker rate is
non-negative.
* At the top tier the maker rate is a rebate, so it debits the recipient and
credits the maker.
docs/perps/learn-about-trading/funding.md
+99
View File
@@ -0,0 +1,99 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Funding
> Funding rate calculation and settlement
Unlike futures contracts, perpetuals have no expiry date. Funding is the
mechanism that keeps the perpetual price anchored to the underlying's fair value.
When the perpetual trades above Index, longs pay shorts. When it trades below
Index, shorts pay longs.
Funding runs continuously across all sessions, regardless of whether the
underlying reference market is open. This keeps the convergence incentive active
and prevents positions from being left unanchored from fair value.
## How Funding Works
Funding is computed in three stages:
1. A premium index is sampled from the order book every 5 seconds.
2. Samples are averaged over the 1-hour charge window to produce an hourly rate.
3. The rate is settled against every open position at the end of the window.
### Premium Index
Every 5 seconds, the protocol takes one snapshot per market of how far the book
has drifted from Index. It walks the book for a fixed quote notional on each side.
```text theme={null}
bid_impact = VWAP of top bids filling 1,000 quote notional
ask_impact = VWAP of top asks filling 1,000 quote notional
```
If one side of the book cannot fill the notional because it is too thin or empty,
that side falls back to Index, which zeros its contribution.
The impact price difference and premium index are:
```text theme={null}
IPD = max(bid_impact - Index, 0) - max(Index - ask_impact, 0)
PremiumIndex = IPD / Index
```
A positive premium means the perpetual is trading rich versus Index. A negative
premium means it is trading cheap.
### Funding Rate
At the end of each charge window, premium samples are averaged, passed through the
8-hour funding formula, divided by 8 to get an hourly rate, and capped.
```text theme={null}
mean_P = average of PremiumIndex samples over the window
scale = 1.0 for crypto markets; 0.5 otherwise
F_8h = scale * (mean_P + clamp(0.0001 - mean_P, +/-0.0005))
FR_hour = clamp(F_8h / 8, +/-0.04)
```
* The 0.01% term is a fixed interest leg per 8 hours.
* The +/-0.05% clamp bounds the interest-versus-premium adjustment.
* Crypto markets use a 1.0 scale.
* Non-crypto markets use a 0.5 scale.
* The 4% per hour cap prevents extreme funding during sustained dislocation.
### Payment
At the end of each charge window, every open position in the market settles a
funding payment proportional to position size and the hourly rate.
| Condition | Longs | Shorts |
| ------------------------------------- | ------- | ------- |
| Hourly rate > 0, perp rich vs Index | Pay | Receive |
| Hourly rate \< 0, perp cheap vs Index | Receive | Pay |
Funding is a direct transfer between longs and shorts. The protocol takes no cut.
Settlement credits or debits the quote balance, and realized funding is tracked
separately from trading PnL.
### Interval
The charge window is 1 hour. Samples are averaged over the hour, and the hourly
rate is applied once at the end.
Between settlements, rolling premium samples and implied rates are published so
traders can see funding pressure build in real time.
## Parameters
| Parameter | Default | Description |
| ---------------- | ------------------------- | ----------------------------------------- |
| Sample interval | 5 seconds | Cadence of premium index samples |
| Impact notional | 1,000 quote notional | Quote notional used for impact VWAP |
| Interest leg | 0.01% per 8 hours | Fixed component in the 8-hour formula |
| Interest clamp | +/-0.05% | Symmetric clamp on interest minus premium |
| Funding scale | 1.0 crypto; 0.5 otherwise | Multiplier applied to the 8-hour formula |
| Charge window | 1 hour | Interval between funding settlements |
| Funding rate cap | 4% per hour | Maximum absolute hourly funding rate |
docs/perps/learn-about-trading/geographic-restrictions.md
+43
View File
@@ -0,0 +1,43 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Geographic Restrictions
> Jurisdictions where Polymarket Perps order placement is not permitted
Polymarket restricts order placement from certain geographic locations to comply
with regulatory requirements and international sanctions. Users in restricted
jurisdictions cannot place Perps orders.
## Restricted Jurisdictions
Order placement is not permitted from:
* United States
* Canada
* Cuba
* Iran
* North Korea
* Syria
* Crimea
* Donetsk
* Luhansk
<Warning>
This list can change. Additional restrictions may apply under Polymarket
notices or applicable law.
</Warning>
## For Builders
If you're integrating Perps, enforce these restrictions before submitting orders
for a user:
* Verify the end user's location before [placing orders](/perps/trading#place-orders).
* Block order submission entirely for users in any of the listed jurisdictions.
Do not only display a warning.
* Apply the same check to any flow that results in a new position, including
programmatic strategies that act on behalf of a user.
Read-only market data is not subject to these restrictions.
docs/perps/learn-about-trading/index-price.md
+33
View File
@@ -0,0 +1,33 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Index Price
> How the Index Price is computed for Perps
Index Price is Polymarket's estimate of the underlying asset's fair value. It is
computed from external price feeds, aggregated to resist stale or anomalous
inputs, and published every 200 milliseconds per market.
## Feed Sources
Index Price can use feeds from external sources such as:
* Pyth
* Chainlink Data Streams
* Hyperliquid
## Feed Selection
The system selects different feeds based on the current market session so it can
use the most accurate feed set for each market. See [Market Sessions](/perps/learn-about-trading/market-sessions).
## Aggregation
Index Price is computed as a weighted average across the selected feeds after
dropping stale prices and filtering outliers. This prevents any single stale or
anomalous feed from moving the Index.
The same aggregation approach is used to build the [C3 candidate in Mark Price](/perps/learn-about-trading/mark-price),
using a separate mark feed set.
docs/perps/learn-about-trading/liquidation-mechanics.md
+94
View File
@@ -0,0 +1,94 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Liquidation Mechanics
> Detection, execution, and insurance-fund backstop
When a trader's equity drops below maintenance margin, the system closes the
position before it becomes insolvent. Normal liquidations route through the order
book as reduce-only immediate-or-cancel orders. If the breach is severe, the
position is absorbed directly by the insurance fund instead.
## Trigger
An account or isolated position is at risk when:
```text theme={null}
MarginRatio = Equity / MaintenanceMargin
```
Liquidation starts when `MarginRatio < 1.0`, which means `Equity < MM`.
Cross and isolated positions are checked independently:
* Cross uses the account's cross equity and combined cross maintenance margin.
* Isolated evaluates each isolated position using its own equity and maintenance margin.
Margin health is re-evaluated continuously, so the system reacts as soon as a new
Mark Price, fill, or deposit moves the account across the threshold.
## While Liquidating
When liquidation starts, the affected scope is flagged:
* Cross liquidation blocks new orders on every market for the account.
* Isolated liquidation blocks new orders only on the affected market.
Order submissions from the account are rejected while the flag is set. Existing
resting orders remain on the book.
## Execution
The system closes flagged positions with reduce-only immediate-or-cancel orders.
These orders execute immediately against available liquidity and cancel any
unfilled quantity. Margin health is re-evaluated between orders, so partial fills
that restore the account naturally stop the process.
### Target Selection
Cross liquidation closes one position at a time. After each fill settles, the
system re-evaluates and picks again from the remaining cross positions, so a
trader with multiple cross positions is unwound across several cycles rather than
all at once.
Isolated liquidation closes the flagged position in full.
### Order Shape
Liquidation orders are IOC, reduce-only, and market-priced. They sweep whatever
liquidity is resting on the book at the moment they land. There is no protective
spread off Mark.
## Recovery
When a liquidating account's equity recovers to or above its recovery initial
margin, the flag clears and normal order submission resumes.
If a position is fully closed during liquidation, the flag is also cleared because
the market no longer has a position to liquidate.
## Insurance-Fund Backstop
If equity falls far enough below maintenance margin that order-book liquidation is
unlikely to recover value, the system skips the order book and absorbs the
position into the insurance fund.
* Cross backstop absorbs all of the trader's cross positions plus their quote-asset balance into the insurance-fund account.
* Isolated backstop absorbs the specific isolated position and its allocated isolated margin.
Once absorbed, the insurance fund holds the position and manages it like any other
account.
## Fees
The liquidating account pays an extra liquidation fee on every fill while flagged,
on top of its normal maker or taker rate.
```text theme={null}
FillFee = Notional * (MakerOrTakerRate + LiquidationFeeRate)
```
Liquidation fee rates vary by market. If you're integrating Perps, read current
values from [Market Data](/perps/market-data#fetch-instruments).
docs/perps/learn-about-trading/margin.md
+86
View File
@@ -0,0 +1,86 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Margin
> Initial margin, maintenance margin, and equity calculations
Margin is the collateral required to open and maintain leveraged positions. It
ensures traders have enough collateral to cover potential losses and gives the
system a buffer to close positions before they become insolvent.
There are two thresholds. **Initial margin (IM)** is the collateral required to
open or increase a position. **Maintenance margin (MM)** is the minimum
collateral required to keep a position open. When equity drops below maintenance
margin, the position is [liquidated](/perps/learn-about-trading/liquidation-mechanics).
## Equity
Equity is the real-time value of an account, incorporating all open positions at
current Mark Price.
```text theme={null}
Equity = Collateral + UnrealizedPnL(Mark) - FeesDue - FundingDue
```
### Unrealized PnL
```text theme={null}
Long PnL = PositionSize * (Mark - EntryPrice)
Short PnL = PositionSize * (EntryPrice - Mark)
```
Because equity depends on Mark Price, equity follows live mark updates. See
[Mark Price](/perps/learn-about-trading/mark-price).
## Margin Requirements
```text theme={null}
IM = Notional / L_max
MM = Notional / L_maint
```
Margin requirements scale with position size through leverage tiers. Larger
positions require proportionally more margin. Margin is calculated incrementally
across tiers, so a position spanning two tiers uses the lower tier's rate on
notional up to its upper bound and the next tier's rate on the remainder.
Margin requirements are static across sessions.
## Margin States
An account is always in one of three states.
| State | Condition | What Happens |
| ----------- | ------------------- | ---------------------------------------------- |
| Healthy | `Equity >= IM` | Normal trading |
| Margin call | `MM <= Equity < IM` | Can only reduce exposure or deposit collateral |
| Liquidation | `Equity < MM` | The system begins closing the position |
## Margin Checks
### Pre-Trade
Before any order executes, the system verifies the account can afford it:
1. Compute the new position after the order fills.
2. Calculate required initial margin using the market's leverage tiers.
3. Reject the order if equity is below required initial margin.
This prevents accounts from entering a margin-call state through new trades.
### Continuous Monitoring
The system continuously evaluates accounts:
* If equity falls below maintenance margin, liquidation begins.
* If equity is between maintenance margin and initial margin, the account may enter reduce-only mode.
## Deposits and Withdrawals
Deposits increase equity. A deposit during margin call can restore the account to
healthy status immediately.
Withdrawals require the account to remain above required initial margin after the
withdrawal. You cannot withdraw yourself into a margin call.
docs/perps/learn-about-trading/mark-price.md
+92
View File
@@ -0,0 +1,92 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mark Price
> How the Mark Price is computed for Perps
Mark Price is the price used across the system for margin, unrealized PnL,
liquidation triggers, funding premium computation, and risk checks. It is updated
every 200 milliseconds.
Mark Price is computed as the median of three candidates, each capturing a
different view of fair value.
```text theme={null}
Mark = median(C1, C2, C3)
```
## C1: Smoothed Order Book Mid
C1 anchors to Index and adjusts gradually based on where the local order book mid
is trading relative to it.
```text theme={null}
C1 = Index + EMA(Mid - Index)
```
* `Mid = (BestBid + BestAsk) / 2` when both sides of the book exist.
* The EMA uses a 150-second window, so C1 moves slowly and resists short-term manipulation.
* If the order book mid is unavailable, C1 falls back to Index.
## C2: Local Market Activity
C2 reflects what is actually trading on the local book.
```text theme={null}
C2 = median(BestBid, BestAsk, LastTrade)
```
* Last trade is only included if it is recent.
* Stale trades are excluded so one old print cannot anchor the price.
* If no usable values exist, C2 falls back to Index.
## C3: Aggregated External Mark
C3 is built from external mark feeds, separate from Index feeds, that provide an
independent view of fair value outside the local order book.
For each market, the system:
1. Selects active mark feeds from eligible external sources.
2. Drops stale samples.
3. Computes the candidate median and filters outliers beyond the allowed tolerance.
4. Returns the weighted average of the remaining samples.
If no valid external mark data is available, C3 falls back to Index.
## Why Three Candidates?
Using the median of three independent price signals provides resilience:
* C1 is slow-moving and resistant to sudden order book manipulation, but can lag during fast moves.
* C2 is responsive to real local trading activity, but can be influenced by thin liquidity.
* C3 is independent of the local book, but depends on external feed availability.
The median ensures that no single signal can unilaterally move Mark Price. At
least two of the three candidates must agree for the mark to shift.
## Finalization
After computing `median(C1, C2, C3)`, the raw mark is normalized before being
published:
* Snapped to the nearest tick size
* Rounded to the market's price precision
## Fallback Summary
Every input degrades gracefully to [Index Price](/perps/learn-about-trading/index-price).
| Condition | Behavior |
| ------------------------------- | ----------------------------------------------------------- |
| Index input stale | Falls back to last known market index |
| Order book mid unavailable | C1 falls back to Index |
| No recent trades or quotes | C2 falls back to Index |
| External mark feeds unavailable | C3 falls back to Index |
| All inputs missing | Mark tracks Index because all candidates fall back to Index |
In the worst case, when there is no local book, no recent trades, and no external
mark feeds, all three candidates converge to Index and Mark Price tracks Index
directly.
docs/perps/learn-about-trading/market-sessions.md
+46
View File
@@ -0,0 +1,46 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Market Sessions
> How session state affects pricing feed selection
Perps trade 24/7, but the underlying markets do not. Liquidity and external price
feed availability vary by time of day and day of week. Sessions are the system's
categorization of these conditions.
## What Sessions Affect
Sessions affect one thing: which set of external feeds is used to compute [Index Price](/perps/learn-about-trading/index-price) and the [C3 candidate in Mark Price](/perps/learn-about-trading/mark-price).
Each category can use its own feed set. For example, primary venue feeds may be
used during regular hours and after-hours venue feeds may be used overnight. If
the current category has no dedicated feed set, the system falls back to the
overnight feed set.
## What Sessions Do Not Affect
Sessions do not change:
* Funding
* Margin and leverage tiers
* Order matching
* Liquidation triggers
Those systems run identically around the clock.
## Categories
* Regular: the underlying is open and primary feeds are available.
* Overnight: the underlying is closed but some external feeds may still exist.
* Weekend: a calendar-based closed period with thin or absent external data.
* Disrupted: external feeds are unavailable or failing sanity checks.
* Halted: a trading halt or corporate-action freeze on the underlying.
## How the Category Is Determined
Each market has a schedule that defines its time windows and exceptions. The
system evaluates the schedule on time boundaries to produce the current category.
When the category changes, subsequent Index and Mark updates use the feed set
assigned to the new category.
docs/perps/learn-about-trading/markets.md
+48
View File
@@ -0,0 +1,48 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Markets
> Listed perpetual markets and trading parameters
Polymarket Perps markets track underlying assets across indices, commodities,
crypto assets, and equities. Each market has its own trading parameters.
## Instruments
Perps markets are represented by instruments, which are the listed perpetual
contracts available to trade.
| ID | Symbol | Category | Base Asset | Max Leverage |
| -- | ------------ | ----------- | ---------- | ------------ |
| 1 | `SP500-USD` | `index` | `SP500` | 20x |
| 2 | `GOLD-USD` | `commodity` | `GOLD` | 20x |
| 3 | `WTIOIL-USD` | `commodity` | `WTIOIL` | 20x |
| 4 | `NAS100-USD` | `index` | `NAS100` | 20x |
| 5 | `SILVER-USD` | `commodity` | `SILVER` | 20x |
| 6 | `BTC-USD` | `crypto` | `BTC` | 20x |
| 7 | `ETH-USD` | `crypto` | `ETH` | 20x |
| 8 | `SOL-USD` | `crypto` | `SOL` | 20x |
| 9 | `SPCX-USD` | `equity` | `SPCX` | 10x |
Each instrument also includes details that shape how it trades:
* Underlying asset
* Collateral and quote asset
* Price and quantity precision
* Tick size
* Minimum order size
* Risk tiers and leverage caps
* Mark, index, and funding configuration
<Note>
Market parameters can change as markets evolve. Builders should read live
instrument details from [Market Data](/perps/market-data#fetch-instruments)
before submitting orders.
</Note>
## Price Feeds
Each market tracks an underlying market through external price feeds. Those
feeds drive the [Index Price](/perps/learn-about-trading/index-price), and the Index Price helps anchor the [Mark Price](/perps/learn-about-trading/mark-price).
docs/perps/learn-about-trading/overview.md
+53
View File
@@ -0,0 +1,53 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> The market mechanics behind Perps trading
Perps markets follow a small set of system rules. This section explains how
those rules work so you can anticipate how positions are valued, when they are
at risk, and why account balances change.
<CardGroup cols={2}>
<Card title="Architecture" icon="sitemap" href="/perps/learn-about-trading/architecture">
How offchain matching and onchain settlement fit together.
</Card>
<Card title="Markets" icon="list" href="/perps/learn-about-trading/markets">
Available Perps markets and the parameters that shape trading.
</Card>
<Card title="Fees" icon="percent" href="/perps/learn-about-trading/fees">
What each fill costs and how the volume-based fee tiers work.
</Card>
<Card title="Margin" icon="scale-balanced" href="/perps/learn-about-trading/margin">
Equity, initial margin, maintenance margin, and margin states.
</Card>
<Card title="Liquidation Mechanics" icon="triangle-exclamation" href="/perps/learn-about-trading/liquidation-mechanics">
How liquidation is detected, executed, and backstopped.
</Card>
<Card title="Funding" icon="repeat" href="/perps/learn-about-trading/funding">
How funding rates are computed and settled against open positions.
</Card>
<Card title="Mark Price" icon="chart-line" href="/perps/learn-about-trading/mark-price">
How the price used for margin, PnL, and liquidation is computed.
</Card>
<Card title="Index Price" icon="crosshairs" href="/perps/learn-about-trading/index-price">
How the underlying's fair value is sourced and aggregated.
</Card>
<Card title="Market Sessions" icon="clock" href="/perps/learn-about-trading/market-sessions">
How session state affects pricing feed selection.
</Card>
<Card title="Geographic Restrictions" icon="globe" href="/perps/learn-about-trading/geographic-restrictions">
Where order placement is restricted.
</Card>
</CardGroup>