Действия разработчика HIP-3

API для деплоя и управления бессрочными дексами, развёрнутыми билдерами, включает следующие действия L1:

// 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>;
};

В следующих примерах feeScale — это поле scale в SetDeployerFees. Предположим положительную обычную комиссию пользователя в 1 единицу и невыровненный залог (x = y = 1). userFeeToProtocol и userFeeToDeployer — итоговые единицы комиссии, взимаемые с пользователя.

О том, как запросить статус аукциона деплоя перпов, см. https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-information-about-the-perp-deploy-auction.

Лимиты открытого интереса

Бессрочные рынки, развёрнутые билдерами, подчиняются двум типам лимитов открытого интереса: ноциональному (сумма абсолютных размеров позиций, умноженных на марк-цену) и размерному (сумма абсолютных размеров позиций).

Ноциональные лимиты открытого интереса применяются к суммарному открытому интересу по всем активам внутри DEX, а также отдельно к каждому активу. Разработчики перпов могут задать собственный лимит открытого интереса на каждый актив, что описано в https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/hip-3-deployer-actions.

Размерные лимиты открытого интереса применяются только к каждому активу отдельно. В настоящее время размерные лимиты открытого интереса являются константой 1B на актив, поэтому разумным вариантом по умолчанию будет задать szDecimals так, чтобы минимальный шаг размера составлял $1-10 при начальной марк-цене.

Страхующий ликвидатор

Адрес страхующего ликвидатора (backstop liquidator) — 0x4000000000000000000000000000000000000000 + {dex_index}. Например, первый HIP-3 DEX имеет адрес страхующего ликвидатора 0x4000000000000000000000000000000000000001.

Состояния клирингового дома пользователей на ноде

Флаг ноды --write-user-clearinghouse-states <dex> записывает состояния клирингового дома указанного HIP-3 DEX в почасовые файлы по пути ~/hl/data/dex_user_clearinghouse_states/hourly/<date>/<hour>, где date — это YYYYMMDD. Каждая строка — JSON-массив [time, messages], где time — время блока, а messages — либо единый снимок всех пользователей DEX, либо список по-пользовательских диффов:

["2026-09-24T09:00:00.123", [{ "Snapshot": { "0xUSER_A": <clearinghouseState> } }]]
["2026-09-24T09:00:03.456", [{ "Diff": ["0xUSER_A", <clearinghouseState>] }]]

Каждый <clearinghouseState> имеет тот же формат, что и ответ info-запроса clearinghouseState для этого DEX, деноминированный в залоговом токене площадки. Он учитывает только состояние пользователя в указанном DEX, поэтому залог, общий для нескольких DEX (например, через user abstraction), не включается, а liquidationPx всегда равен null. Первая строка каждого файла, а также первая строка, записанная после запуска ноды, — снимок. Остальные строки содержат диффы для пользователей, чьё состояние клирингового дома изменилось, без учёта time: все такие пользователи при обновлении оракула площадки или только пользователи, участвующие в исполнении, ликвидации, выплате финансирования либо переводе на площадку или с неё.

HIP-3* (только testnet)

Star-действия

Площадка HIP-3 может быть обозначена как HIP-3* при создании установкой isStar: true в PerpDexSchemaInput. Этот необязательный булев параметр по умолчанию равен false. HIP-3* включает несколько функций поверх спецификации HIP-3, включая allow-list и проксированные действия пользователей.

Операции

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 — пара из адреса пользователя и одной прокси-операции, применяемой к этому пользователю.
• setOracle — обновляет цены оракула, как описано в разделе «Оракул» ниже.

Прокси-операции

• modifyApproval — { "modifyApproval": true } добавляет пользователя в allowlist, false удаляет его и сбрасывает его флаги. Удаление пользователя, который не одобрен, — no-op. Повторное одобрение уже одобренного пользователя — no-op с сохранением флагов пользователя. Удалённый пользователь, одобренный повторно, начинает с флагами по умолчанию.
• modifyBackstopLiquidatorApproval — { "modifyBackstopLiquidatorApproval": true } позволяет пользователю пополнять страхующий ликвидатор площадки и выводить из него средства через hip3LiquidatorTransfer; false отзывает это разрешение. Пользователь должен быть уже одобрен через modifyApproval.
• setReduceOnly — { "setReduceOnly": true } ограничивает одобренного пользователя только сокращением своих позиций на площадке. Пользователь может размещать только reduce-only ордера и TWAP, изменять ордера в reduce-only ордера и отменять их. { "setReduceOnly": false } восстанавливает полную торговлю.
• cancel — { "cancel": { "cancels": [{ "a": <asset>, "o": <oid> }] } }, стандартная полезная нагрузка exchange-действия cancel. Отменяет стоящие ордера пользователя по oid.
• cancelAll — { "cancelAll": { "assets": null } } отменяет все стоящие ордера и TWAP пользователя на этой площадке. { "cancelAll": { "assets": [<asset>, ...] } } отменяет только стоящие ордера и TWAP пользователя по перечисленным активам. Список должен содержать 1-10 записей.
• order — { "order": { "orders": [...], "grouping": "na" } }, стандартная полезная нагрузка exchange-действия order. Каждый ордер должен быть reduce-only ("r": true).
• sendAsset — { "sendAsset": { "destination": "0xUSER_C", "amount": "100.0" } }. Переводит залог со счёта проксируемого пользователя в DEX на счёт destination на той же площадке.

Оракул

Площадки HIP-3* обновляют цены с помощью действия деплоя star-операции setOracle. oraclePxs — список (отсортированный по ключу) активов и спот-цен оракула. Внешние перп-цены и марк-цены вычисляются ончейн на основе входных спот-цен оракула, предоставляемых разработчиком.

• Внешние перп-цены вычисляются на основе актива основного декса с тем же именем с конвертацией номинации в USDC. Например, test:BTC использует внешнюю перп-цену BTC.
• Марк-цены вычисляются ончейн как медиана из:

1. цены оракула, скорректированной на экспоненциальное скользящее среднее премии средней цены над ценой оракула,
2. внешней перп-цены и
3. локальной марк-цены (медиана(best bid, best ask, цена последней сделки)).

Если доступна только две из этих цен, в качестве третьего входа добавляется экспоненциальное скользящее среднее локальной марк-цены.

Разрешения

Для HIP-3* SubDeployerInput.variant также принимает объекты, показанные ниже.

Каждое право покрывает только свою операцию. Например, право modifyApproval не разрешает modifyBackstopLiquidatorApproval, setReduceOnly или sendAsset. Аналогично, обычное право "setOracle", включая выданное oracleUpdater, не разрешает star-операцию setOracle.

Star-состояние пользователя

Info-запрос userStarState возвращает состояние одобрения пользователя на каждой площадке HIP-3*, где пользователь был одобрен. Состояние равно null на площадках, которые впоследствии отозвали одобрение пользователя.

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

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