HIP-3-Deployer-Aktionen

Die API für die Bereitstellung und den Betrieb von durch Builder bereitgestellten Perpetual-DEXs umfasst die folgenden L1-Aktionen:

// IMPORTANT: All lists of tuples should be lexographically sorted before signing
type PerpDeployAction =
  | {
      type: "perpDeploy";
      registerAsset2: RegisterAsset2;
    }
  | {
      type: "perpDeploy";
      registerAsset: RegisterAsset;
    }
  | {
      type: "perpDeploy";
      setOracle: SetOracle;
    }
  | {
      type: "perpDeploy";
      setFundingMultipliers: SetFundingMultipliers;
    }
  | {
      type: "perpDeploy";
      setFundingInterestRates: SetFundingInterestRates;
    }
  | {
      type: "perpDeploy";
      setFundingClamps: SetFundingClamps;
    }
  | {
      type: "perpDeploy";
      haltTrading: { coin: string; isHalted: boolean };
    }
  | {
      type: "perpDeploy";
      insertMarginTable: InsertMarginTable;
    }
  | {
      type: "perpDeploy";
      setMarginTableIds: SetMarginTableIds;
    }
  | {
      type: "perpDeploy";
      setFeeRecipient: { dex: string; feeRecipient: address };
    }
  | {
      type: "perpDeploy";
      setOpenInterestCaps: SetOpenInterestCaps;
    }
  | {
      type: "perpDeploy";
      setSubDeployers: { dex: string; subDeployers: Array<SubDeployerInput> };
    }
  | {
      type: "perpDeploy";
      setMarginModes: SetMarginModes;
    }
  | {
      type: "perpDeploy";
      setDeployerFees: SetDeployerFees;
    }
  | {
      type: "perpDeploy";
      setPerpAnnotation: SetPerpAnnotation;
    }
  | {
      type: "perpDeploy";
      disableDex: string;
    };

// User-signed action to transfer collateral between the user's DEX account and its backstop liquidator.
// ntl must be positive and a multiple of 1_000_000_000.
type Hip3LiquidatorTransferAction = {
  type: "hip3LiquidatorTransfer";
  dex: string;
  ntl: number; // Integer amount in millionths of a collateral token: 1_000_000_000 = 1,000 tokens
  isDeposit: boolean; // true deposits; false withdraws
};

/**
 * RegisterAsset2 can be called to initialize a new dex and register an asset at the same time.
 * If schema is not provided, then RegisterAsset can be called multiple times to register additional assets
 * for the provided dex.
 * @param maxGas - Max gas in native token wei. If not provided, then uses current deploy auction price.
 * If the max gas is 0, then a reserve deployment will be used.
 * A reserve deployment allows deployment at the current price of the gas auction, even if it has ended.
 * Currently, 7 reserve deployments are allowed.
 * IMPORTANT: A reserve deployment will be used regardless of whether the auction has completed, so deployers should query the auction status first.
 * @param assetRequest - Contains new asset listing parameters. See RegisterAssetRequest2 below for details.
 * @param dex - Name of the perp dex (2-4 lowercase characters)
 * @param schema - Contains new perp dex parameters. See PerpDexSchemaInput below for details.
 */
type RegisterAsset2 = {
  maxGas?: number;
  assetRequest: RegisterAssetRequest2;
  dex: string;
  schema?: PerpDexSchemaInput;
};

// Same as RegisterAsset2 but uses RegisterAssetRequest
type RegisterAsset = {
  maxGas?: number;
  assetRequest: RegisterAssetRequest;
  dex: string;
  schema?: PerpDexSchemaInput;
};

type RegisterAssetRequest2 = {
  coin: string;
  szDecimals: number;
  oraclePx: string;
  marginTableId: number;
  marginMode: "strictIsolated" | "noCross" | "normal"; // strictIsolated does not allow withdrawing of isolated margin from open positions
};

type RegisterAssetRequest = {
  coin: string;
  szDecimals: number;
  oraclePx: string;
  marginTableId: number;
  onlyIsolated: boolean;
};

/**
 * The markPxs outer list can be length 0, 1, or 2. The median of these inputs
 * along with the local mark price (median(best bid, best ask, last trade price))
 * is used as the new mark price update.
 *
 * SetOracle can be called multiple times but there must be at least 2.5 seconds between calls.
 *
 * Stale mark prices will be updated to the local mark price after 10 seconds of no updates.
 * This fallback counts as an update for purposes of the maximal update frequency.
 * This fallback behavior should not be relied upon. Deployers are expected to call setOracle every 3 seconds even with no changes.
 *
 * All prices are clamped to 10x the start of day value.
 * markPx moves are clamped to 1% from previous markPx.
 * markPx cannot be updated such that open interest would be 10x the open interest cap.
 * @param dex - Name of the perp dex
 * @param oraclePxs - A list (sorted by key) of asset and oracle prices.
 * @param markPxs - An outer list of inner lists (inner list sorted by key) of asset and mark prices.
 * @param externalPerpPxs - A list (sorted by key) of asset and external prices which prevent sudden mark price deviations.
 * Ideally externally determined by deployer, but could fall back to an EMA of recent mark prices.
 * Must include all assets.
 */
type SetOracle = {
  dex: string;
  oraclePxs: Array<[string, string]>;
  markPxs: Array<Array<[string, string]>>;
  externalPerpPxs: Array<[string, string]>;
};

/**
 * @param fullName - Full name of the perp dex
 * @param collateralToken - Collateral token index
 * @param oracleUpdater - User to update oracles. If not provided, then deployer is assumed to be oracle updater.
 */
type PerpDexSchemaInput = {
  fullName: string;
  collateralToken: int;
  oracleUpdater?: string;
};

/**
 * A sorted list of asset and funding multiplier.
 * Multipliers must be between 0 and 10 and are used to scale the funding rate.
 */
type SetFundingMultipliers = Array<[string, string]>;

/**
 * A sorted list of asset and 8 hour interest rate.
 * Interest rates must be between -0.01 and 0.01 and are used as the interest rate
 * component in the funding calculation.
 */
type SetFundingInterestRates = Array<[string, string]>;

/**
 * A sorted list of asset and 8 hour funding clamp.
 * Clamps must be between 0 and 0.01 and bound how far the funding rate can move away from the
 * average premium toward the interest rate. Defaults to 0.0003.
 */
type SetFundingClamps = Array<[string, string]>;

/**
 * A sorted of asset and margin table ids.
 * Margin table ids must be non-zero.
 */
type SetMarginTableIds = Array<[string, number]>;

/**
 * Inserts margin table to dex
 */
type InsertMarginTable = {
  dex: string;
  marginTable: RawMarginTable;
};

/**
 * marginTiers must be sorted in order of increasing lower bound and decreasing maxLeverage
 * marginTiers has a maximum length of 3.
 */
type RawMarginTable = {
  description: string;
  marginTiers: Array<RawMarginTier>;
};

/**
 * lowerBound is a position notional value above which the leverage is constrained by maxLeverage
 */
type RawMarginTier = {
  lowerBound: int;
  maxLeverage: MaxLeverage;
};

/**
 * Max leverage is in the range [1, 50]
 */
type MaxLeverage = number;

/**
 * A sorted list of asset and open interest cap notionals.
 * Open interest caps must be at least the maximum of 1_000_000 (1 size unit of collateral asset) or half of the current open interest.
 * null removes the custom cap for an asset.
 */
type SetOpenInterestCaps = Array<[string, number | null]>;

/**
 * A modification to sub-deployer permissions
 */
type SubDeployerInput = {
  variant: string; // corresponds to a variant of PerpDeployAction. For example, "haltTrading" or "setOracle"
  user: String;
  allowed: boolean; // add or remove the subDeployer from the authorized set for the action variant
};

// A sorted list of (coin, marginMode). See RegisterAssetRequest2 for margin mode definitions.
type SetMarginModes = Array<[string, "strictIsolated" | "noCross" | "normal"]>;

// Let the user normal rate be `x`. Let the user rate be `y` after accounting for aligned quote collateral.
// In other words, `x = y` for non-aligned collateral.
// User pays or receives rebate `P + D` where `P` goes to protocol and `D` goes to deployer.
// If `x > 0` and `scale < 1`, `P = y` and `D = scale * x`
// If `x > 0` and `scale > 1`, `P = y * scale` and `D = x * scale`
// If `x < 0` and `scale < 1`, `P = y / (1 + scale)` and `D = y * scale / (1 + scale)`
// If `x < 0` and `scale > 1`, `P = y / 2` and `D = y / 2`
// On Mainnet, rate limited to one change per 30 days.
// Note that there are currently no aligned quote assets on mainnet.
type SetDeployerFees = Array<
  [
    string,
    {
      scale: string; // Decimal string in [0.0, 3.0], or [0.0, 10.0) when growthMode is true
      growthMode: boolean;
    },
  ]
>;

// category <= 15 characters
// description <= 400 characters
// displayName <= 9 characters
// <= 2 keywords, each keyword <= 10 characters
type SetPerpAnnotation = {
  coin: string;
  category: string;
  description: string;
  displayName: string | null;
  keywords: Array<string>;
};

Für die folgenden Beispiele ist feeScale das Feld scale in SetDeployerFees. Angenommen wird eine positive normale Nutzergebühr von 1 Einheit und nicht abgestimmte Sicherheiten (x = y = 1). userFeeToProtocol und userFeeToDeployer sind die resultierenden Gebühreneinheiten, die dem Nutzer berechnet werden.

Informationen zum Abfragen des Status der Perpetual-Deploy-Auktion finden Sie unter https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-information-about-the-perp-deploy-auction.

Obergrenzen für Open Interest

Von Buildern bereitgestellte Perpetual-Märkte unterliegen zwei Arten von Open-Interest-Obergrenzen: nominal (Summe der absoluten Positionsgrößen multipliziert mit dem Markpreis) und größenbasiert (Summe der absoluten Positionsgrößen).

Nominale Open-Interest-Obergrenzen werden sowohl auf das gesamte, über alle Assets innerhalb der DEX summierte Open Interest als auch pro Asset angewendet. Perpetual-Deployer können eine benutzerdefinierte Open-Interest-Obergrenze pro Asset festlegen, die unter https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/hip-3-deployer-actions dokumentiert ist.

Größenbasierte Open-Interest-Obergrenzen werden nur pro Asset angewendet. Größenbasierte Open-Interest-Obergrenzen sind derzeit konstant 1B pro Asset, daher ist es eine sinnvolle Voreinstellung, szDecimals so zu wählen, dass das minimale Größeninkrement beim anfänglichen Markpreis $1-10 beträgt.

Backstop-Liquidator

Die Adresse des Backstop-Liquidators ist 0x4000000000000000000000000000000000000000 + {dex_index}. Beispielsweise hat die erste HIP-3 DEX die Backstop-Liquidator-Adresse 0x4000000000000000000000000000000000000001.

Nutzer-Kontoübersichten des Nodes

Das Node-Flag --write-user-account-summaries <dex> schreibt Kontoübersichten für die genannte HIP-3 DEX in Stundendateien unter ~/hl/data/dex_user_account_summaries/hourly/<date>/<hour>, wobei date dem Format YYYYMMDD entspricht. Jede Zeile ist ein JSON-Array [time, messages], wobei time die Blockzeit ist und messages entweder ein einzelner Snapshot aller Nutzer auf der DEX oder eine Liste nutzerbezogener Diffs ist:

["2026-09-24T09:00:00.123", [{ "Snapshot": { "0xUSER_A": { "a": "100.0", "b": "90.0" } } }]]
["2026-09-24T09:00:03.456", [{ "Diff": ["0xUSER_A", { "a": "105.0", "b": "90.0" }] }]]

a ist der Kontowert und b ist balance = accountValue - unrealizedPnl, beide denominiert im Collateral-Token des Venues. Die erste Zeile jeder Datei sowie die erste Zeile, die nach dem Start des Nodes geschrieben wird, ist ein Snapshot. Die übrigen Zeilen enthalten Diffs für Nutzer, deren Kontoübersicht sich geändert hat: alle diese Nutzer bei einem Oracle-Update für das Venue oder nur die Nutzer, die an einem Fill, einer Liquidation, einer Funding-Zahlung oder einer Übertragung in das oder aus dem Venue beteiligt sind.

HIP-3* (nur im Testnet)

Star-Aktionen

Eine HIP-3-Venue kann bei ihrer Erstellung als HIP-3* festgelegt werden, indem isStar: true in PerpDexSchemaInput gesetzt wird. Dieser optionale Boolean ist standardmäßig false. HIP-3* ermöglicht mehrere Funktionen zusätzlich zur HIP-3-Spezifikation, darunter eine Allowlist und proxierte Nutzeraktionen.

Operationen

type Hip3StarAction = {
  type: "perpDeploy";
  star: { dex: string; operation: Hip3StarOperation };
};

type Hip3StarOperation =
  | { proxy: [address, Hip3StarProxyOperation] }
  | { setOracle: { oraclePxs: Array<[string, string]> } };

// CancelAction and OrderAction are the standard exchange actions.
type Hip3StarProxyOperation =
  | { modifyApproval: boolean }
  | { modifyBackstopLiquidatorApproval: boolean }
  | { setReduceOnly: boolean }
  | { cancel: Omit<CancelAction, "type"> }
  | { cancelAll: { assets?: Array<number> | null } }
  | { order: Omit<OrderAction, "type"> }
  | { sendAsset: { destination: address; amount: string } };

{
  "type": "perpDeploy",
  "star": {
    "dex": "test",
    "operation": { "proxy": ["0xUSER_A", { "modifyApproval": true }] }
  }
}
{
  "type": "perpDeploy",
  "star": {
    "dex": "test",
    "operation": { "proxy": ["0xUSER_B", { "cancelAll": { "assets": [100001, 100002] } }] }
  }
}
{
  "type": "perpDeploy",
  "star": {
    "dex": "test",
    "operation": { "setOracle": { "oraclePxs": [["test:BTC", "100000.0"], ["test:ETH", "4000.0"]] } }
  }
}

• proxy — ein Paar aus einer Nutzeradresse und einer Proxy-Operation, die auf diesen Nutzer angewendet wird.
• setOracle — aktualisiert Oracle-Preise, wie unten unter Oracle beschrieben.

Proxy-Operationen

• modifyApproval — { "modifyApproval": true } fügt den Nutzer zur Allowlist hinzu, false entfernt ihn und löscht seine Flags. Das Entfernen eines nicht zugelassenen Nutzers ist ein No-op. Die erneute Zulassung eines bereits zugelassenen Nutzers ist ein No-op und behält die Flags des Nutzers. Ein entfernter Nutzer, der erneut zugelassen wird, beginnt mit den Standard-Flags.
• modifyBackstopLiquidatorApproval — { "modifyBackstopLiquidatorApproval": true } erlaubt dem Nutzer, über hip3LiquidatorTransfer Einzahlungen in den Backstop-Liquidator des Venues vorzunehmen und daraus Auszahlungen zu tätigen; false widerruft dies. Der Nutzer muss bereits über modifyApproval zugelassen sein.
• setReduceOnly — { "setReduceOnly": true } beschränkt einen zugelassenen Nutzer darauf, seine Positionen auf dem Venue zu reduzieren. Der Nutzer kann nur Reduce-only-Orders und TWAPs platzieren, Orders in Reduce-only-Orders ändern und stornieren. { "setReduceOnly": false } stellt den vollen Handel wieder her.
• cancel — { "cancel": { "cancels": [{ "a": <asset>, "o": <oid> }] } }, der Standard-Payload der cancel-Exchange-Aktion. Storniert die ruhenden Orders des Nutzers anhand der oid.
• cancelAll — { "cancelAll": { "assets": null } } storniert alle ruhenden Orders und TWAPs des Nutzers auf diesem Venue. { "cancelAll": { "assets": [<asset>, ...] } } storniert nur die ruhenden Orders und TWAPs des Nutzers für die aufgeführten Assets. Die Liste muss 1-10 Einträge enthalten.
• order — { "order": { "orders": [...], "grouping": "na" } }, der Standard-Payload der order-Exchange-Aktion. Jede Order muss reduce-only sein ("r": true).
• sendAsset — { "sendAsset": { "destination": "0xUSER_C", "amount": "100.0" } }. Überträgt Sicherheiten vom Konto des Proxy-Nutzers auf der DEX auf das Konto von destination auf demselben Venue.

Oracle

HIP-3*-Venues aktualisieren Preise mit der setOracle-Star-Operation-Deploy-Aktion. oraclePxs ist eine Liste (nach Key sortiert) von Asset- und Spot-Oracle-Preisen. Externe Perpetual-Preise und Markpreise werden on-chain auf Basis der Spot-Oracle-Preiseingaben des Deployers abgeleitet.

• Externe Perpetual-Preise werden aus dem Asset der Haupt-DEX mit demselben Namen abgeleitet, wobei die Denominierung in USDC umgerechnet wird. Beispielsweise verwendet test:BTC den externen Perpetual-Preis von BTC.
• Markpreise werden on-chain als Median aus Folgendem berechnet:

1. dem Oracle-Preis, angepasst um einen exponentiellen gleitenden Durchschnitt der Prämie des Mid-Preises gegenüber dem Oracle-Preis,
2. dem externen Perpetual-Preis und
3. dem lokalen Markpreis (median(best bid, best ask, last trade price)).

Wenn nur zwei dieser Preise verfügbar sind, wird ein exponentieller gleitender Durchschnitt des lokalen Markpreises als dritter Eingabewert hinzugefügt.

Berechtigungen

Für HIP-3* akzeptiert SubDeployerInput.variant zusätzlich die unten gezeigten Objekte.

Jede Berechtigung gilt nur für ihre eigene Operation. Beispielsweise erlaubt die modifyApproval-Berechtigung nicht modifyBackstopLiquidatorApproval, setReduceOnly oder sendAsset. Ebenso erlaubt die reguläre "setOracle"-Berechtigung, einschließlich derjenigen für oracleUpdater, nicht die setOracle-Star-Operation.

Nutzer-Star-Zustand

Die userStarState-Info-Anfrage gibt den Zulassungsstatus eines Nutzers auf jeder HIP-3*-Venue zurück, auf der der Nutzer zugelassen wurde. Der Status ist null auf Venues, die die Zulassung des Nutzers zwischenzeitlich entfernt haben.

{ "type": "userStarState", "user": "0xUSER_A" }

{
  "dexToState": {
    "test": {
      "isReduceOnly": false,
      "isBackstopLiquidatorDepositAllowed": true
    },
    "demo": null
  }
}