Concepts
Plain-English explanations of perps, leverage, margin, marks, API keys, and rate limits.
New to perps or to APIs? Open any of these for a plain-English explanation. If the terms are familiar, skip straight past.
New to this?What is a perp?
A perpetual future ("perp") is a contract that tracks an asset's price without ever expiring. You take a long (betting the price rises) or a short (betting it falls), and your profit or loss follows the price move times your position size. Perps Fund settles everything in simulated dollars against real marks.
New to this?What is leverage?
Leverage multiplies your exposure relative to the margin you put up. At 5x, $1,000 of margin controls $5,000 of position, so a 1% price move is a 5% move on your margin - in both directions. Each market has a firm maximum; ask for more and the API clamps you to the cap.
New to this?What is margin?
Margin is the slice of your balance set aside to hold a position open. Higher leverage means less margin per unit of exposure, and less room before a loss forces the position closed (a liquidation). marginRequired on each position tells you how much is reserved.
New to this?What is a mark price?
The mark is the reference price the platform uses to value your positions and trigger take-profit, stop-loss, and liquidation. Reads give you a recent mark; the exact fill price comes from a fresh fetch at order time, which is why the fill can differ slightly from the last read.
New to this?What is an API key?
An API key is a secret string that identifies your agent to the API, sent in the X-API-Key header. A pk_test_ key acts on your sandbox; a pk_live_ key acts on your real accounts. Anyone holding one can act as you, so keep it in an environment variable and revoke it from Settings if it leaks.
New to this?What is a rate limit?
A cap on how many requests you can send in a window - here, 600 per minute per key. Go over and you get a 429 with a Retry-After header telling you how long to wait. Poll on a sensible interval (a few seconds) rather than in a tight loop and you will not see this one.
On a live key, orders also count against the limit the terminal applies to you: 150 per minute for each of market orders, limit orders, closes, cancels and TP/SL changes, and 20 per minute for each Pro order type. That budget is per person, not per key, so your own clicks in the terminal and every key you hold draw on the same one.
There is one more limit you should know about even though it is unlikely to affect you: a per-IP throttle on failed authentication, which exists to stop someone spamming invented keys. It counts only failures, and once your key has authenticated successfully it is exempt - so a working agent is not throttled by traffic it did not send, even from a shared address. The case that can still bite is a brand-new key whose very first request arrives from an address someone else has recently been failing from: retry after the Retry-After window and it will go through. All of these return 429 rate_limited, so back off on Retry-After whichever one you hit.