HIP-3 デプロイヤーアクション

ビルダーがデプロイした永続契約 DEX をデプロイおよび運用するための 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 は SetDeployerFees の scale フィールドです。通常ユーザーの手数料が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 を参照してください。

建玉キャップ

ビルダーがデプロイした永続契約市場には、ノーショナル（ポジションサイズの絶対値とマークプライスの積の合計）とサイズ（ポジションサイズの絶対値の合計）の2種類の建玉キャップが適用されます。

ノーショナル建玉キャップは、DEX 内のすべての資産にわたる合計建玉に対しても、資産ごとにも適用されます。永続契約のデプロイヤーは資産ごとにカスタム建玉キャップを設定できます。これについては https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/hip-3-deployer-actions に記載されています。

サイズ建玉キャップは資産ごとにのみ適用されます。サイズ建玉キャップは現在、資産ごとに一定の1Bであるため、初期マークプライスで最小サイズ刻みが$1〜10になるように szDecimals を設定することが合理的なデフォルトです。

バックストップ清算人

バックストップ清算人アドレスは 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> は、その DEX の clearinghouseState info リクエストのレスポンスと同じ形式を持ち、そのベニューの担保トークンで表示されます。これは指定された名前の DEX 上のユーザーのステートのみを対象とするため、DEX 間で共有される担保（例：ユーザーアブストラクションを通じたもの）は含まれず、liquidationPx は常に null です。各ファイルの最初の行、およびノード起動後に書き込まれた最初の行はスナップショットです。その他の行には、清算所ステートが変化したユーザーの差分が含まれます（time は無視）。すなわち、ベニューのオラクル更新時にはそのような全ユーザー、または約定、清算、ファンディング支払い、ベニューへの入出金転送に関与したユーザーのみが対象です。

HIP-3*（testnet のみ）

Star アクション

HIP-3 ベニューは、作成時に PerpDexSchemaInput で isStar: true を設定することで HIP-3* として指定できます。このオプションのブール値はデフォルトで false です。HIP-3* は、許可リストとプロキシされたユーザーアクションを含む、HIP-3 仕様の上にいくつかの機能を追加します。

オペレーション

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 — ユーザーアドレスと、そのユーザーに適用される1つのプロキシオペレーションのペア。
• setOracle — 下記の Oracle の説明の通り、オラクル価格を更新します。

プロキシオペレーション

• modifyApproval — { "modifyApproval": true } はユーザーを許可リストに追加し、false はユーザーを削除してそのフラグをクリアします。未承認のユーザーの削除は何もしません。承認済みユーザーの再承認は何もせず、ユーザーのフラグを維持します。削除された後に再承認されたユーザーは、デフォルトのフラグで開始します。
• modifyBackstopLiquidatorApproval — { "modifyBackstopLiquidatorApproval": true } は、hip3LiquidatorTransfer を介したベニューのバックストップ清算人への入出金をユーザーに許可します。false はこれを取り消します。ユーザーは modifyApproval によって既に承認されている必要があります。
• setReduceOnly — { "setReduceOnly": true } は、承認されたユーザーをベニュー上のポジションの削減に限定します。ユーザーができるのは、リデュースオンリーの注文と TWAP の発注、注文のリデュースオンリーへの変更、キャンセルのみです。{ "setReduceOnly": false } は完全なトレーディングを復元します。
• cancel — { "cancel": { "cancels": [{ "a": <asset>, "o": <oid> }] } }、標準の cancel 取引アクションのペイロード。oid によってユーザーの待機中の注文をキャンセルします。
• cancelAll — { "cancelAll": { "assets": null } } は、このベニューにおけるユーザーのすべての待機中の注文と TWAP をキャンセルします。{ "cancelAll": { "assets": [<asset>, ...] } } は、リストされた資産に対するユーザーの待機中の注文と TWAP のみをキャンセルします。リストには1〜10個のエントリが含まれる必要があります。
• order — { "order": { "orders": [...], "grouping": "na" } }、標準の order 取引アクションのペイロード。すべての注文はリデュースオンリー（"r": true）である必要があります。
• sendAsset — { "sendAsset": { "destination": "0xUSER_C", "amount": "100.0" } }。プロキシされたユーザーの DEX 上のアカウントから、同じベニューの destination のアカウントへ担保を移動します。

オラクル

HIP-3* ベニューは、setOracle star オペレーションのデプロイアクションで価格を更新します。oraclePxs は資産とスポットオラクル価格の（キーでソートされた）リストです。外部の永続契約価格とマークプライスは、デプロイヤーのスポットオラクル価格の入力に基づいてオンチェーンで導出されます。

• 外部の永続契約価格は、同名のメイン DEX 資産から導出され、額面単位は USDC に変換されます。例えば、test:BTC は BTC の外部永続契約価格を使用します。
• マークプライスは、以下の中央値としてオンチェーンで計算されます：

1. ミッドプライスのオラクル価格に対するプレミアムの指数移動平均によって調整されたオラクル価格、
2. 外部の永続契約価格、
3. ローカルのマークプライス（median(best bid, best ask, last trade price)）。

これらの価格のうち2つのみが利用可能な場合は、ローカルのマークプライスの指数移動平均が3番目の入力として追加されます。

権限

HIP-3* の場合、SubDeployerInput.variant は以下に示すオブジェクトも受け付けます。

各権限はそれ自体のオペレーションのみをカバーします。例えば、modifyApproval の権限は modifyBackstopLiquidatorApproval、setReduceOnly、sendAsset を許可しません。同様に、通常の "setOracle" 権限（oracleUpdater に付与されるものを含む）は、setOracle star オペレーションを許可しません。

ユーザー star ステート

userStarState info リクエストは、ユーザーが承認されたすべての HIP-3* ベニューにおけるユーザーの承認ステートを返します。その後ユーザーの承認を削除したベニューでは、ステートは null です。

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

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