- Your backendConnect the lane
Verify the partner-chain key, contracts, and market rules.
- Account walletRegister a session
Sign the login; use the session for trading and private updates.
- Wallet · ContractDeposit collateral
Approve and deposit, then wait for usable account credit.
- Your backend · APISign & trade
Submit signed orders and track positions, fills, and fees.
- Your backend · RPCReconcile & withdraw
Resolve pending actions and confirm the final wallet payout.
Confirm the assigned lane is ready before funding. Order admission, execution, and withdrawal payout are separate states to reconcile.
API version: v1 Guide updated: 25 October 2026
Default deployment: Arbitrum One, Global lane (global:42161)
Audience: partner engineers integrating a server-side trading account
When no partner is specified, use global: REST https://perps-api.orbs.network, WebSocket wss://perps-api.orbs.network/ws, routing header X-Partner-Chain-Key: global:42161, and rollup contract 0xd2c8793397036f6D2F60A93D3eB28295a3F1B102 for both the EIP-712 domain and deposits. See the Global connection values and readiness notes. This deployment uses real USDC on Arbitrum One; confirm funding instructions before the first deposit.
This guide explains how to integrate without the Perpetual Hub UI or a Perpetual Hub SDK. Use HTTPS for account and trading requests, WebSocket for live updates, and your chain's JSON-RPC interface for collateral deposits.
Account model
Your integration operates one partner-controlled wallet address as one trading account within your assigned partner and chain. That account has one net position per symbol. All orders, collateral, fees, funding, profit/loss and liquidation exposure belong to that account.
Your customer accounting and any allocation across other trading providers remain in your system. Funding a customer balance in your system does not fund this trading account: collateral must be deposited separately into the assigned Perpetual Hub contract.
The wallet and signing service can run on your backend. No browser component is required. A registered session key supports routine trading and private streaming; withdrawals require the account wallet's signature.
Backend REST calls require no CORS headers or browser-origin allowlisting. Backend WebSocket connections must send an agreed, allowlisted Origin header. See connection requirements before connecting.
Read in this order
| Guide | What you implement |
|---|---|
| 01 — Connection and conventions | Onboarding values, routing, numerical units, market discovery |
| 02 — Signing and sessions | Exact typed-data definitions, session registration and renewal |
| 03 — Deposits and withdrawals | Token approval, contract deposits, withdrawal requests and payout tracking |
| 04 — Trading | Market/limit orders, position closes, TP/SL, replacement, cancellation and leverage |
| 05 — Account and history | Balances, positions, orders, fills, funding, transactions and request lookup |
| 06 — Market data and streaming | Prices, funding rates, public/private subscriptions and reconnect handling |
| 07 — Reliability and acceptance | Errors, uncertain outcomes, reconciliation and integration test checklist |
First successful integration
- Receive the onboarding values listed in connection.
- Verify
/api/v1/config, obtain the enabled symbol list, and confirm the selected symbol's execution rules. - Register a session key with an account-wallet-signed login.
- Subscribe to market data and authenticated account updates.
- Approve collateral and call the deposit contract. Wait for the account API to show usable collateral.
- Set leverage, submit a small order, and confirm the resulting position and fill history.
- Exercise cancellation, protective TP/SL and replacement flows.
- Close the position and reconcile fills, fees and funding.
- Request a small withdrawal, track its lifecycle, and confirm the wallet receipt.
An HTTP success response is not interchangeable with a fill or a completed wallet transfer. Each guide identifies which result to wait for.
Endpoint index
All paths below are relative to your assigned HTTPS base URL. Always send X-Partner-Chain-Key.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/config | Chain and collateral contract addresses |
| GET | /api/v1/markets | Market catalogue |
| GET | /api/v1/risk-config | Public leverage, margin-bracket and trading-fee information |
| POST | /api/v1/auth/login | Register or replace the account's session key |
| GET | /api/v1/prices | Latest cached mark-price values |
| GET | /api/v1/market-data | Display prices, 24-hour statistics and funding-rate information |
| GET | /api/v1/leverage/allowed?symbol=SYMBOL | Currently allowed leverage |
| POST | /api/v1/leverage | Change account leverage for a symbol |
| POST | /api/v1/order | Submit an order, bracket order or replacement |
| DELETE | /api/v1/order/{orderId} | Cancel an open order, with a signed JSON body |
| GET | /api/v1/user/{address} | Current account, positions, pending orders and withdrawals |
| GET | /api/v1/user/{address}/portfolio | Account valuation and summary |
| GET | /api/v1/user/{address}/risk-preview?symbol=SYMBOL | Informational risk preview |
| GET | /api/v1/user/{address}/trades | Executed fills |
| GET | /api/v1/user/{address}/funding | Recorded funding charges/credits |
| GET | /api/v1/user/{address}/orders/history | Order activity |
| GET | /api/v1/user/{address}/transactions | Deposits and withdrawal requests, including withdrawal progress |
| GET | /api/v1/user/{address}/request/{requestId} | Recorded submission outcome and available execution evidence |
| POST | /api/v1/withdraw | Request a collateral withdrawal |
WebSocket uses the separately supplied URL. Deposits use the collateral and deposit contracts; there is no REST deposit-submission endpoint in this integration.
Scope of the examples
The deployment URLs, chain ID, partner key, contract and collateral addresses in Connection are Global production values. Account addresses, IDs, timestamps, prices and other example response values remain illustrative. Supply your own account credentials and generate fresh timestamps/signatures at runtime. The example symbol XRPUSDT is usable only if enabled for your integration. Values are examples, not executable trading recommendations or guaranteed acceptance limits.
Examples show the fields relevant to each flow. Responses may contain additional fields; clients should tolerate them. Do not add undocumented request fields.
This guide forms a self-contained partner handoff. No other repository documentation is required to follow it.