Perpetual Trading

Perpetual Trading lets users trade perpetual futures on stocks (AAPL, TSLA, NVDA), commodities (GOLD, SILVER, CL) and forex (EUR, GBP, JPY), with leverage, on Hyperliquid. Users deposit USDC from Arbitrum, and every trade is a signed message: no gas and no on-chain transaction per order. Unlike the other products, Perpetual Trading doesn’t use a product account. Orders run from the user’s own Hyperliquid account, keyed by their wallet address. Positions are contracts that track a price, not tokens the user holds. For real on-chain tokens, see Tokenized Assets.

How every action works

Prepare. Call the endpoint for the action: an order, a leverage change, a withdrawal. It returns typed_data, action and nonce.
Sign. The user signs typed_data as EIP-712 typed data in their wallet. Nothing is broadcast.
Execute. Send action, nonce and the signature to POST /v2/perpetual_trading/execute. Compass forwards it to Hyperliquid and returns the result.

Before you start

An API key. See the Quick Start.
An Arbitrum wallet of your own, holding ETH for gas. Deposits go through Hyperliquid’s bridge on Arbitrum, and your wallet sends that transaction. Keep its key on your server.

1. Deposit USDC

The user signs a USDC permit, and your wallet sends the bridge transaction on Arbitrum.

Get the permit

import os
from compass_api_sdk import CompassAPI

compass = CompassAPI(api_key_auth=os.environ["COMPASS_API_KEY"])

deposit = compass.perpetual_trading.perpetual_trading_deposit(
    owner="0xYourWalletAddress", amount="100"
)

# The permit the user signs as EIP-712 typed data
typed_data = deposit.permit.model_dump(by_alias=True)

# Next call: deposit.amount_raw and deposit.permit.message.deadline

import { CompassApiSDK } from "@compass-labs/api-sdk";

const compass = new CompassApiSDK({ apiKeyAuth: process.env.COMPASS_API_KEY });

const deposit = await compass.perpetualTrading.perpetualTradingDeposit({
  owner: "0xYourWalletAddress",
  amount: "100",
});

// deposit.permit: the permit the user signs as EIP-712 typed data.
// The SDK camelCases the keys of its types (permit, eip712Domain):
// rename them back (Permit, EIP712Domain) before signing.

// Next call: deposit.amountRaw and deposit.permit.message.deadline

curl -X POST "https://api.compasslabs.ai/v2/perpetual_trading/deposit" \
  -H "x-api-key: $COMPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner": "0xYourWalletAddress", "amount": "100"}'

Send the bridge transaction

Pass the user’s signature to POST /v2/perpetual_trading/deposit/sponsor_prepare:

relay = compass.perpetual_trading.perpetual_trading_deposit_sponsor_prepare(
    owner="0xYourWalletAddress",
    amount_raw=deposit.amount_raw,
    deadline=int(deposit.permit.message.deadline),
    signature="0xUserPermitSignature",
    sender="0xYourSponsorWallet",
)

const relay = await compass.perpetualTrading.perpetualTradingDepositSponsorPrepare({
  owner: "0xYourWalletAddress",
  amountRaw: deposit.amountRaw,
  deadline: Number(deposit.permit.message.deadline),
  signature: "0xUserPermitSignature",
  sender: "0xYourSponsorWallet",
});

curl -X POST "https://api.compasslabs.ai/v2/perpetual_trading/deposit/sponsor_prepare" \
  -H "x-api-key: $COMPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "0xYourWalletAddress",
    "amount_raw": 100000000,
    "deadline": 1747097383,
    "signature": "0xUserPermitSignature",
    "sender": "0xYourSponsorWallet"
  }'

The response is a transaction for your sponsor wallet to sign and send on Arbitrum. Hyperliquid credits the user’s account once it confirms. Check withdrawable on the positions endpoint before showing the deposit as complete.

2. One-time setup per user

Account mode. Call POST /v2/perpetual_trading/enable_unified_account. If typed_data is null, there’s nothing to do. Otherwise the user signs it and you execute it.
Leverage. Call POST /v2/perpetual_trading/set_leverage with asset and leverage before the first order on each asset. Leave out leverage to use the market’s maximum. If leverage_ok is true, there’s nothing to sign. Leverage stays set per asset until you change it.
Your fee. If you charge a fee, the user approves your builder address once. See Charge a fee.

3. Place an order

Buy 1 AAPL contract at market, then execute the signed action:

# 1. Prepare
order = compass.perpetual_trading.perpetual_trading_market_order(
    owner="0xYourWalletAddress",
    asset="AAPL",
    side="buy",
    size="1",
    slippage_percent=1,
)

# 2. The user signs order.typed_data as EIP-712 typed data
signature = "0xUserSignature"

# 3. Execute
result = compass.perpetual_trading.perpetual_trading_execute(
    action=order.action,
    nonce=order.nonce,
    signature=signature,
)

# result.status: "ok" or "error"

// 1. Prepare
const order = await compass.perpetualTrading.perpetualTradingMarketOrder({
  owner: "0xYourWalletAddress",
  asset: "AAPL",
  side: "buy",
  size: "1",
  slippagePercent: 1,
});

// 2. The user signs order.typedData as EIP-712 typed data
const signature = "0xUserSignature";

// 3. Execute
const result = await compass.perpetualTrading.perpetualTradingExecute({
  action: order.action,
  nonce: order.nonce,
  signature,
});

// result.status: "ok" or "error"

# 1. Prepare
curl -X POST "https://api.compasslabs.ai/v2/perpetual_trading/market_order" \
  -H "x-api-key: $COMPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "0xYourWalletAddress",
    "asset": "AAPL",
    "side": "buy",
    "size": "1",
    "slippage_percent": 1
  }'

# 2. The user signs typed_data from the response as EIP-712 typed data

# 3. Execute
curl -X POST "https://api.compasslabs.ai/v2/perpetual_trading/execute" \
  -H "x-api-key: $COMPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": { "...": "action from the prepare response" },
    "nonce": 1747097383000,
    "signature": "0xUserSignature"
  }'

Field	Description
`asset`	A ticker from the markets list, such as `AAPL`, `GOLD` or `EUR`.
`side`	`buy` or `sell`. Selling without a position opens a short.
`size`	Number of contracts. Each market’s `sz_decimals` sets how many decimals are allowed.
`slippage_percent`	Price protection for the market order. Defaults to `1`.
`reduce_only`	Optional. `true` only ever reduces an existing position, so a close can’t flip into a short.
`builder`	Optional. Your fee on this order. See Charge a fee.

For a limit order, call POST /v2/perpetual_trading/limit_order with a price and time_in_force (gtc or alo), and cancel it with POST /v2/perpetual_trading/cancel_order. Both follow the same sign-and-execute steps.

4. Track positions

positions = compass.perpetual_trading.perpetual_trading_positions(
    owner="0xYourWalletAddress"
)

print(positions.account_value, positions.withdrawable)
for position in positions.positions:
    print(position.asset, position.side, position.unrealized_pnl)

const positions = await compass.perpetualTrading.perpetualTradingPositions({
  owner: "0xYourWalletAddress",
});

console.log(positions.accountValue, positions.withdrawable);
for (const position of positions.positions) {
  console.log(position.asset, position.side, position.unrealizedPnl);
}

curl "https://api.compasslabs.ai/v2/perpetual_trading/positions?owner=0xYourWalletAddress" \
  -H "x-api-key: $COMPASS_API_KEY"

Each open position has side, size, entry_price, mark_price, liquidation_price, leverage, unrealized_pnl and funding_accrued. The response also carries account_value and withdrawable, the USDC the user can take out. For fills and open orders as well, use GET /v2/perpetual_trading/activity. For price charts, use GET /v2/perpetual_trading/candles.

5. Withdraw

Call POST /v2/perpetual_trading/withdraw with owner and amount, and optionally a destination on Arbitrum. The user signs and you execute it. The USDC arrives on Arbitrum once Hyperliquid processes the withdrawal, which takes from minutes to a few hours.

Charge a fee

Hyperliquid lets you add a builder fee to your users’ fills. It’s charged on top of Hyperliquid’s own fee and credited in USDC to an address you control.

Approve once per user. Call POST /v2/perpetual_trading/approve_builder_fee with builder: {"address": "0xYourBuilderAddress", "max_fee_rate": "0.01%"}. The user signs and you execute it. To raise the rate later, approve again. Lowering it needs no new approval.
Add builder to each order. Pass the same address and a max_fee_rate at or below what the user approved. Orders without builder pay no fee.
Read what you earned. Each fill in activity carries its builder_fee, and builder_approval shows the user’s current approval when you pass your builder address.

The rate is at most 0.1%, in steps of 0.001%. The builder address must be a regular wallet holding at least 100 USDC in its Hyperliquid perps account before the first approval; otherwise execute returns 502 Builder has insufficient balance to be approved. Fees accumulate in that address’s Hyperliquid account under the xyz DEX, separate from its main perps balance. Your users, their fills and their approval state also appear on the Hyperliquid tab of your dashboard.

Good to know

Higher leverage means a closer liquidation price. Hyperliquid checks leverage when a position opens. Watching liquidation_price and margin afterwards is up to you.
Markets. GET /v2/perpetual_trading/opportunities lists every market with mark_price, funding_rate, max_leverage, open interest and volume. Filter by category: stock, commodity or forex.
Funding. Positions pay or receive funding every hour. It shows per position as funding_accrued.
Rejected actions. execute returns status: "error" with Hyperliquid’s message, for example when margin is insufficient. Show it to the user.

Endpoints

Endpoint	Use it to
`GET /v2/perpetual_trading/opportunities`	List markets with prices, funding and max leverage.
`POST /v2/perpetual_trading/deposit`	Get the USDC permit for the user to sign.
`POST /v2/perpetual_trading/deposit/sponsor_prepare`	Build the bridge transaction for your wallet.
`POST /v2/perpetual_trading/set_leverage`	Set leverage for an asset.
`POST /v2/perpetual_trading/market_order`	Prepare a market order.
`POST /v2/perpetual_trading/limit_order`	Prepare a limit order.
`POST /v2/perpetual_trading/cancel_order`	Prepare a cancellation.
`POST /v2/perpetual_trading/execute`	Submit any signed action.
`GET /v2/perpetual_trading/positions`	Open positions and balances.
`GET /v2/perpetual_trading/activity`	Positions, fills, open orders and builder approval.
`POST /v2/perpetual_trading/withdraw`	Prepare a withdrawal to Arbitrum.
`POST /v2/perpetual_trading/approve_builder_fee`	Have the user approve your builder fee.

Tokenized Assets

Real tokenized stocks and RWAs, held as ERC-20s.

Crypto-Backed Loans

Borrow USDC against crypto to fund trading.

Bridging

Move USDC to Arbitrum from another chain.

Get Started

Products

Data

Account Lifecycle

Platform Concepts

Developer Tools

Resources

How every action works

Before you start

1. Deposit USDC

2. One-time setup per user

3. Place an order

4. Track positions

5. Withdraw

Charge a fee

Good to know

Endpoints

Next

Tokenized Assets

Crypto-Backed Loans

Bridging

​How every action works

​Before you start

​1. Deposit USDC

​2. One-time setup per user

​3. Place an order

​4. Track positions

​5. Withdraw

​Charge a fee

​Good to know

​Endpoints

​Next

Tokenized Assets

Crypto-Backed Loans

Bridging

How every action works

Before you start

1. Deposit USDC

2. One-time setup per user

3. Place an order

4. Track positions

5. Withdraw

Charge a fee

Good to know

Endpoints

Next