Perpetuals

Dedicated endpoints for perpetual asset contexts and margin tables.

Access comprehensive data for the perpetuals exchange, including asset metadata, real-time funding rates, and market contexts. These resources provide the technical details required to monitor account-level summaries, margin tables, and the status of builder-deployed markets.

Retrieve perpetuals metadata (universe and margin tables)

POST /external/info

Fetches the complete list of tradable perpetual assets along with their specific parameters, such as decimal precision and maximum leverage limits. Includes current margin tables that define the tiered leverage structures and maintenance thresholds required for managing positions across the exchange.

Headers

Name	Type	Description
Content-Type	String	"application/json"

Request Body

Name	Type	Description
type	String	"meta"
dex (optional)	String	Perp dex name. Defaults to the empty string which represents the first perp dex.

Response

{
    "universe": [
        {
            "name": "BTC",
            "szDecimals": 5,
            "maxLeverage": 50
        },
        {
            "name": "ETH",
            "szDecimals": 4,
            "maxLeverage": 50
        },
        {
            "name": "HPOS",
            "szDecimals": 0,
            "maxLeverage": 3,
            "onlyIsolated": true
        },
        {
            "name": "LOOM",
            "szDecimals": 1,
            "maxLeverage": 3,
            "isDelisted": true,
            "marginMode": "strictIsolated", // "strictIsolated" means margin cannot be removed, "noCross" means only isolated margin allowed
            "onlyIsolated": true // deprecated. Means either "strictIsolated" or "noCross"
        }
    ],
    "marginTables": [
        [
            50,
            {
                "description": "",
                "marginTiers": [
                    {
                        "lowerBound": "0.0",
                        "maxLeverage": 50
                    }
                ]
            }
        ],
        [
            51,
            {
                "description": "tiered 10x",
                "marginTiers": [
                    {
                        "lowerBound": "0.0",
                        "maxLeverage": 10
                    },
                    {
                        "lowerBound": "3000000.0",
                        "maxLeverage": 5
                    }
                ]
            }
        ]
    ]
}

---

Retrieve user's perpetuals account summary

POST /external/info

Provides a comprehensive overview of a user's perpetual trading state, including detailed position data, cumulative funding tracking, and current margin summaries. It reports critical real-time values such as unrealized PnL, liquidation prices, and account-wide withdrawable totals to facilitate effective risk management.

Headers

Name	Type	Description
Content-Type	String	"application/json"

Request Body

Name	Type	Description
type	String	"clearinghouseState"
user	String	Onchain address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000.
dex (optional)	String	Perp dex name. Defaults to the empty string which represents the first perp dex.

Response

{
  "assetPositions": [
    {
      "position": {
        "coin": "ETH",
        "cumFunding": {
          "allTime": "514.085417",
          "sinceChange": "0.0",
          "sinceOpen": "0.0"
        },
        "entryPx": "2986.3",
        "leverage": {
          "rawUsd": "-95.059824",
          "type": "isolated",
          "value": 20
        },
        "liquidationPx": "2866.26936529",
        "marginUsed": "4.967826",
        "maxLeverage": 50,
        "positionValue": "100.02765",
        "returnOnEquity": "-0.0026789",
        "szi": "0.0335",
        "unrealizedPnl": "-0.0134"
      },
      "type": "oneWay"
    }
  ],
  "crossMaintenanceMarginUsed": "0.0",
  "crossMarginSummary": {
    "accountValue": "13104.514502",
    "totalMarginUsed": "0.0",
    "totalNtlPos": "0.0",
    "totalRawUsd": "13104.514502"
  },
  "marginSummary": {
    "accountValue": "13109.482328",
    "totalMarginUsed": "4.967826",
    "totalNtlPos": "100.02765",
    "totalRawUsd": "13009.454678"
  },
  "time": 1708622398623,
  "withdrawable": "13104.514502"
}

---

Retrieve User's Active Asset Data

POST /external/info

Retrieves real-time account data for a specific asset, including the current leverage settings, mark price, and maximum tradeable sizes. It provides essential information for executing trades, such as the total amount available to trade in both base and quote currencies for the selected coin.

Headers

Name	Type	Description
Content-Type	String	"application/json"

Request Body

Name	Type	Description
type	String	"activeAssetData"
user	String	Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000.
coin	String	Coin, e.g. "ETH". See here for more details.

Responses

First perp dex

{
  "user": "0xb65822a30bbaaa68942d6f4c43d78704faeabbbb",
  "coin": "APT",
  "leverage": {
    "type": "cross",
    "value": 3
  },
  "maxTradeSzs": ["24836370.4400000013", "24836370.4400000013"],
  "availableToTrade": ["37019438.0284740031", "37019438.0284740031"],
  "markPx": "4.4716"
}

HIP-3 dex

---

Retrieve information about the Perp Deploy Auction

POST /external/info

Provides the current status and timing parameters for the Dutch auction required to deploy new permissionless perpetual markets on the exchange. Reports essential metrics such as auction duration, current gas prices, and start times to help developers coordinate new market listings effectively.

Headers

Name	Type	Description
Content-Type	String	"application/json"

Request Body

Name	Type	Description
type	String	"perpDeployAuctionStatus"

Response

{
  "startTimeSeconds": 1747656000,
  "durationSeconds": 111600,
  "startGas": "500.0",
  "currentGas": "500.0",
  "endGas": null
}

---

Query perps at open interest caps

POST /external/info

Identifies all perpetual assets that have reached their open interest limits for a specific perpetual DEX. Returns an array of tickers to help developers monitor market availability and manage risk for builder-deployed markets.

Headers

Name	Type	Description
Content-Type	String	"application/json"

Request Body

Name	Type	Description
type	String	"perpsAtOpenInterestCap"
dex (optional)	String	Perp dex name. Defaults to the empty string which represents the first perp dex.

Response

["BADGER","CANTO","FTM","LOOM","PURR"]

---

Retrieve all perpetual dexs

POST /external/info

Returns a complete list of all perpetual DEXs available on the platform, including their unique identifiers, deployer addresses, and specific market parameters. Provides granular configuration details for each DEX, such as streaming open interest caps and funding multipliers for supported assets.

Headers

Name	Type	Description
Content-Type	String	"application/json"

Request Body

Name	Type	Description
type	String	"perpDexs"

Response

[
  null,
  {
    "name": "test",
    "fullName": "test dex",
    "deployer": "0x5e89b26d8d66da9888c835c9bfcc2aa51813e152",
    "oracleUpdater": null,
    "feeRecipient": null,
    "assetToStreamingOiCap": [["COIN1", "100000.0"], ["COIN2", "200000.0"]],
    "assetToFundingMultiplier": [["COIN1", "1.0"], ["COIN2", "2.0"]]
  }
]