A perpetual derivatives API is not simply a spot trading API with leverage added. It must represent an instrument with no ordinary expiry, a mechanism that links contract pricing to an underlying index, collateral and margin rules, continuously changing position risk, and venue-specific liquidation behavior. Small differences in metadata can change the economics of a position, so the API contract must make those differences visible.
This guide focuses on systems design rather than trading advice. Regulatory treatment, product availability, and customer eligibility vary by jurisdiction and venue. A production integration should combine technical controls with qualified legal and compliance review rather than assuming that an endpoint implies permission to offer the product.
Identify the contract before processing a price
Create an immutable internal instrument ID and versioned metadata. Store venue product ID, underlying asset, quote currency, settlement asset, contract multiplier, linear or inverse payoff, tick size, quantity step, minimum size, margin modes, leverage limits, status, and funding interval. An apparently familiar symbol can hide a different settlement currency or contract size.
Distinguish perpetual futures, perpetual swaps, dated futures, options, and spot markets. The CFTC material on certain crypto asset perpetuals illustrates that classification and regulatory context can be product-specific. Your API should not collapse all “perps” into one generic type if the venue’s legal and operational treatment differs.
Version instrument rules with effective timestamps. A venue can change leverage tiers, position limits, funding calculations, or tick sizes. Historical orders and risk calculations must be interpreted using the rules in effect at that time.
Keep last, mark, and index prices separate
The last traded price reports the most recent execution. The index price is usually derived from one or more spot references. The mark price is a venue-defined fair-price estimate used for unrealized profit and loss, margin, or liquidation calculations. These values may diverge, and each serves a different purpose.
Return them as distinct fields with source timestamps and methodology identifiers. Do not label all three as price. A chart may show last price, while a risk panel uses mark price and a funding model references index price. Ambiguity can create false liquidation warnings or incorrect PnL.
Store the components of an index when available. If the index excludes a stale venue or changes weighting, the metadata should show which methodology version applied. For a composite you calculate yourself, preserve inputs and outlier decisions so it can be reproduced.
Model funding as a scheduled cash-flow event
Funding is commonly used to encourage convergence between the perpetual contract and its reference price. The precise formula, cap, interval, accrual convention, and payment timing vary. An API should return the current estimated rate, next funding time, historical rates, and the actual payment records applied to an account.
Separate a forecast from a settled funding payment. A displayed rate can change before the funding timestamp. Store the calculation timestamp and interval basis. For account history, create a cash-flow event with instrument, position side, rate, notional basis, amount, currency, and settlement time.
Funding affects total return and tax or accounting records. It should not be buried inside a changing unrealized-PnL field. The account ledger must be able to reconcile each payment with the venue statement.
Design the order lifecycle as a state machine
A trading client may submit market, limit, stop, take-profit, reduce-only, post-only, or conditional orders. Venues use different names and combinations. Normalize only the features your contract can define precisely, and preserve venue-specific parameters in an extension object.
Use a client-generated idempotency key or client order ID. The server should distinguish request accepted, order acknowledged, partially filled, fully filled, canceled, rejected, expired, and unknown. “Unknown” is important after a network timeout: the order may exist even when the client did not receive the acknowledgement.
Do not retry a write blindly. Reconcile by client order ID, venue order ID, or account event stream before resubmitting. Record every transition with source sequence and time. A current-order table is useful for display, but an immutable event log is needed for audit and recovery.
Conditional orders deserve special attention. Determine whether the condition is held by the venue, your server, or the client. A browser-held stop disappears when the device disconnects. A server-held condition introduces your own availability and price-source risk. Make the execution location explicit in the API.
Reconstruct fills and positions deterministically
A fill should include order ID, trade ID, instrument, side, price, quantity, fee, fee currency, liquidity role where known, and event time. Deduplicate by the venue’s stable identifier. Preserve corrections or busts as new events rather than editing history silently.
Position representation varies. Some venues use net positions; others support separate long and short legs. Some use isolated margin per position, while cross margin shares collateral. Your canonical model should include position mode and margin mode so a client does not infer them.
Calculate position quantity, average entry, realized PnL, fees, and funding from an event ledger when possible. Compare the result with the venue’s position snapshot. Differences should create reconciliation alerts, not be overwritten without explanation.
Represent collateral and margin tiers
Margin is not one percentage. Initial and maintenance requirements may depend on notional, leverage tier, collateral haircut, portfolio offsets, or account mode. Store the venue’s tier table and effective version. Expose the account’s selected leverage separately from the maximum allowed leverage.
A risk response should identify collateral balance, available margin, initial requirement, maintenance requirement, unrealized PnL basis, and liquidation estimate. Label estimates clearly. Liquidation engines can include fees, insurance rules, partial liquidation, and order-book conditions that a simplified formula cannot reproduce.
Multi-asset collateral adds conversion and concentration risk. Preserve each collateral asset, mark, haircut, and contribution. A single USD-equivalent number is convenient but insufficient for explaining why available margin changed.
Treat liquidation data as risk telemetry
Liquidation price is a scenario output, not a promise. Return the assumptions and time at which it was calculated. For venues that publish liquidation events, distinguish forced-order records, bankruptcy or insurance events, and aggregated market statistics.
Applications should avoid gamifying liquidation proximity. A professional dashboard can show maintenance margin headroom, collateral composition, open orders, and stress scenarios. An API can support alerts, but it should rate-limit noisy updates and require users to choose thresholds deliberately.
Build server-side controls such as maximum order notional, maximum position, reduce-only emergency mode, price collars, stale-market blocks, daily loss limits, and a kill switch. Enforce them before venue submission and log the policy result. Client-side controls alone are easy to bypass or lose during a disconnect.
Sequence private and public streams
Public market data and private account data may arrive on different channels. Track sequence numbers independently. A fill can arrive before an order acknowledgement, or a position update can precede the REST response that caused it. The state machine must accept valid out-of-order events and reconcile them by identifiers.
After reconnecting, obtain snapshots of open orders, positions, collateral, and recent fills, then apply buffered events. If continuity cannot be proved, mark the account state as reconciling. Do not show an apparently precise available-margin figure while the private stream has a known gap.
Centralize upstream connections and fan out authorized account events to clients. Never expose venue API secrets to web, iOS, Android, WordPress, or charting code. Use short-lived application sessions and server-side permission checks.
Separate HFT and ordinary application paths
High frequency trading requires co-location, deterministic networking, venue-specific protocols, and microstructure controls that a general REST gateway or mobile API cannot provide. A general Digital Assets API can still support research, monitoring, risk, and lower-frequency execution, but it should state its latency class honestly.
Create service-level objectives for each path: market-data age, order acknowledgement, account-state reconciliation, and recovery time. Measure percentiles and tail behavior, not only averages. Backpressure and garbage collection that are acceptable for a dashboard may be unacceptable for an execution component.
The market data API article covers order-book integrity and charting. The compliance API guide addresses jurisdiction, identity, and reporting layers that should surround any trading integration.
Test the dangerous paths first
Use a sandbox where available, but also build deterministic simulators. Test duplicate order submissions, timeouts after venue acceptance, partial fills, stale mark prices, changing margin tiers, funding settlement, rejected reduce-only orders, WebSocket gaps, and account reconciliation after restart.
Run scenario tests for rapid price moves and provider outages. Confirm that the system blocks new risk when its price or account state is stale. Verify that a kill switch cancels eligible orders and prevents replacement according to policy.
Conclusion
A robust perpetual derivatives API makes contract economics and account risk explicit. It separates last, mark, and index prices; records funding as cash flow; models orders and positions as event-driven state; versions margin rules; and treats stream recovery as a core function. Those foundations help a product remain explainable under normal trading and, more importantly, during the failures and rapid moves that expose weak integrations.
