Perps Overview
Perpetual futures for the portfolio bound to your API key: live market data for every listed market, account state, orders, fills, funding payments and fees, an order preview, and transfers in both directions — vault-funded deposits into the perps account and partner-signed withdrawals back to the portfolio's Arbitrum trading vault.
Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/perps/markets | GET | All markets with live mark/funding/OI |
/perps/markets/{symbol}/orderbook | GET | L2 snapshot |
/perps/markets/{symbol}/candles | GET | OHLCV |
/perps/markets/{symbol}/quote | GET | Size-aware execution estimate |
/perps/markets/{symbol}/funding | GET | Historical + predicted funding |
/perps/account | GET | Balance, positions, margins |
/perps/account/status | GET | Onboarding state |
/perps/orders/open | GET | Open orders |
/perps/orders/history | GET | Order history |
/perps/fills | GET | Trade fills |
/perps/funding-payments | GET | Funding paid/received |
/perps/fees | GET | Fee rates |
/perps/orders/preview | POST | Order validation/preview |
/perps/withdraw/payload | POST | Typed data for a withdrawal |
/perps/withdraw | POST | Submit the signed withdrawal |
/perps/deposit/vault-fund-hl/quote | POST | Quote a deposit into the perps account |
/perps/deposit/vault-fund-hl | POST | Execute the quoted deposit |
All paths above are shown for the Portfolio API (/v2/portfolio/...). Every endpoint also exists on the Organization API: replace /v2/portfolio/ with /v2/organization/portfolios/{portfolioId}/. See Portfolio vs. Organization API.
Market Symbols
A market is addressed as subvenue:SYMBOL, e.g. native:BTC. Markets on the core exchange use the native subvenue; builder-deployed markets use their own subvenue prefix. Every row returned by /perps/markets carries this id as marketId (with subvenue alongside) — pass that value as {symbol} rather than building it yourself. Responses report the bare base symbol in symbol.
A bare symbol (e.g. BTC) is accepted when exactly one listed market has that base symbol. When more than one market shares a base symbol, bare requests return 400 with ambiguous market symbol — qualify the symbol instead (e.g. native:BTC).
Availability
Market-data endpoints (/perps/markets...) are always available. Account-scoped endpoints return 503 with perps account data is not available on this deployment yet on deployments where perps account reads are not yet enabled; treat 503 as "retry later", not as an error in your request.
Account endpoints require a perps account on the portfolio. If the portfolio has no perps account, account reads return 422 with errorType: "PERPS_ACCOUNT_NOT_CONFIGURED" (or "ACCOUNT_NOT_SETUP" when the account exists but is not yet set up at the venue) — check /perps/account/status first.
Rate Limits & Scope
Perps endpoints are limited to 20 requests/second per API key, in addition to the standard per-key limit on the Portfolio API; the venue may also answer 429 under load. All GET endpoints work with a READ-scoped key; the POST endpoints (order preview, deposit and withdraw) require a WRITE-scoped key.
Order placement, cancellation and leverage changes are not available through API keys. Deposits move funds from a trading vault Definitive custodies and need only a WRITE-scoped key — see Deposit. Withdrawals are signed by the wallet that owns the perps account — see Withdraw.