perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/venues/aster.js

@@ -0,0 +1,176 @@
+/**
+ * Aster venue definition (design §10.1, §10.8, §10.13 #4).
+ * Adapter + public-data code are loaded lazily (§10.10).
+ */
+import { BUILDER_FEE_CAPABILITIES } from "../builder-fee.js";
+/** Aster client order id (V3 futures "New Order" `newClientOrderId` rule). */
+export const ASTER_CLIENT_ID_RE = /^[.A-Z:/a-z0-9_-]{1,36}$/;
+const publicData = {
+    async fetchFundingRates(net) {
+        return (await import("../../funding/legacy-public.js")).legacyPublicData("aster").fetchFundingRates(net);
+    },
+    async fetchMarkets(net) {
+        return (await import("../../funding/legacy-public.js")).legacyPublicData("aster").fetchMarkets(net);
+    },
+};
+/**
+ * PINNED Aster vault + token addresses (mainnet). A deposit is `approve(vault, exact amount)` then
+ * `deposit(address currency, uint256 amount, uint256 broker)` on the vault — never a plain token
+ * transfer. Verified 2026-10-05 against:
+ *   - github.com/asterdex/api-docs demo/aster-deposit-withdrawal.md "Mainnet contract addresses"
+ *     (BSC 0x1284…7974, Arbitrum 0x9E36…E1d5) and its ethers example (BSC USDT 0x55d3…7955)
+ *   - docs.asterdex.com/overview/smart-contracts
+ *   - the verified AstherusVault source on BscScan / Arbiscan (`deposit(address,uint256,uint256)`
+ *     selector 0x0efe6a8b, `supportToken(address)`, `paused()`, event Deposit)
+ *   - live `supportToken(token)` non-zero for all four tokens below
+ * Token decimals are NOT pinned: they are read on-chain (`decimals()`) before every deposit
+ * (BSC USDT / USDC have 18, Arbitrum USDC / USDT have 6).
+ */
+export const ASTER_FUNDS_CHAINS = {
+    bsc: {
+        chainId: 56,
+        label: "BNB Chain",
+        withdrawChainName: "BSC",
+        rpcUrl: "https://bsc-dataseed.bnbchain.org",
+        vault: "0x128463A60784c4D3f46c23Af3f65Ed859Ba87974",
+        tokens: {
+            USDT: "0x55d398326f99059fF775485246999027B3197955",
+            USDC: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
+        },
+        sources: [
+            "https://github.com/asterdex/api-docs/blob/master/demo/aster-deposit-withdrawal.md",
+            "https://docs.asterdex.com/overview/smart-contracts",
+            "https://bscscan.com/address/0x128463A60784c4D3f46c23Af3f65Ed859Ba87974#code",
+        ],
+    },
+    arbitrum: {
+        chainId: 42161,
+        label: "Arbitrum",
+        withdrawChainName: "Arbitrum",
+        rpcUrl: "https://arb1.arbitrum.io/rpc",
+        vault: "0x9E36CB86a159d479cEd94Fa05036f235Ac40E1d5",
+        tokens: {
+            USDT: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
+            USDC: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+        },
+        sources: [
+            "https://github.com/asterdex/api-docs/blob/master/demo/aster-deposit-withdrawal.md",
+            "https://docs.asterdex.com/overview/smart-contracts",
+            "https://arbiscan.io/address/0x9E36CB86a159d479cEd94Fa05036f235Ac40E1d5#code",
+        ],
+    },
+};
+/** Vault `broker` argument: 1 = perp (futures) account; 1000 = spot account (never used here). */
+export const ASTER_DEPOSIT_BROKER_PERP = 1n;
+/**
+ * Why deposit / withdraw are mainnet only (uniform CAPABILITY_UNSUPPORTED on testnet): the vault
+ * addresses above are mainnet deployments, and the withdraw signature's `aster chain` is the
+ * fixed string "Mainnet" (no testnet value is documented).
+ */
+export const ASTER_FUNDS_TESTNET_UNSUPPORTED = {
+    reason: "the pinned vault contracts are mainnet deployments and the withdraw signature is defined for \"Mainnet\" only",
+    remediation: "Run without -n testnet; fund the Aster testnet account from the testnet app faucet",
+};
+export const asterVenue = {
+    id: "aster",
+    aliases: ["ast"],
+    displayName: "Aster",
+    family: "aster",
+    masterKeyKind: "evm",
+    agentKeyKind: "evm",
+    secretStorage: { kind: "ows-wallet", dir: null },
+    // Hosts per github.com/asterdex/api-docs V3 (aster-finance-futures-api-v3.md / -testnet.md):
+    // REST base "https://fapi.asterdex.com" / "https://fapi.asterdex-testnet.com",
+    // WS "wss://fstream.asterdex.com" / "wss://fstream.asterdex-testnet.com"
+    // (live 2026-10-02: testnet /fapi/v3/time 200, both WS handshakes open). The old
+    // testnet host testnet.asterdex.com does not resolve. AsterAdapter and the public
+    // data path (api/public/urls.ts) both read these values — no env override.
+    // No explorer / signing chain id in code → null. Markets quote in USDT (aster.ts symbol mapping).
+    networks: {
+        mainnet: {
+            restUrl: "https://fapi.asterdex.com",
+            wsUrl: "wss://fstream.asterdex.com",
+            explorerUrl: null,
+            signingChainId: null,
+            settlementChain: "bnb",
+            collateral: ["USDT"],
+            collateralAssetIndex: null,
+            // Default deposit route (BNB Chain USDT); the Arbitrum route is in ASTER_FUNDS_CHAINS.
+            rpcUrl: ASTER_FUNDS_CHAINS.bsc.rpcUrl,
+            depositPins: {
+                chainId: ASTER_FUNDS_CHAINS.bsc.chainId,
+                contract: ASTER_FUNDS_CHAINS.bsc.vault,
+                token: ASTER_FUNDS_CHAINS.bsc.tokens.USDT,
+                sources: ASTER_FUNDS_CHAINS.bsc.sources,
+            },
+        },
+        testnet: {
+            restUrl: "https://fapi.asterdex-testnet.com",
+            wsUrl: "wss://fstream.asterdex-testnet.com",
+            explorerUrl: null,
+            signingChainId: null,
+            settlementChain: "bnb",
+            collateral: ["USDT"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+    },
+    // Per symbol: GET /fapi/v3/fundingInfo lists fundingIntervalHours per market
+    // (live 2026-09-30: 4h, 8h, 1h and 2h markets). A flat venue value would be wrong.
+    fundingRateBasis: "perMarket",
+    settlementIntervalHours: "perMarket",
+    fundingVerified: true,
+    roles: ["marketData", "account", "trading"],
+    capabilities: {
+        // Market = IOC LIMIT at mark ± slippage (adapter marketOrder), never native MARKET.
+        marketOrder: "slippageBounded",
+        // Live exchangeInfo timeInForce: GTC/IOC/GTX/HIDDEN — no FOK. ALO is the common name for GTX.
+        timeInForce: ["GTC", "IOC", "ALO", "GTX"],
+        reduceOnlyTif: null,
+        // V3 futures "New Order": `newClientOrderId` "A unique id among open orders. Automatically
+        // generated if not sent. Can only be string following the rule: ^[\\.A-Z\\:/a-z0-9_-]{1,36}$";
+        // "Query Order" / "Cancel Order": "Either `orderId` or `origClientOrderId` must be sent."
+        clientOrderId: true,
+        orderAck: "sync",
+        tpsl: "separateOrders",
+        // PUT /fapi/v3/order (V3 "Modify Order", LIMIT only).
+        amend: "native",
+        batchPlaceMax: null,
+        marginModes: ["cross", "isolated"],
+        // POST /fapi/v3/aster/user-withdraw (mainnet only — exchanges/aster-funds.ts): USDT (default)
+        // or USDC to the account owner's own address on BNB Chain or Arbitrum. Needs an API wallet
+        // with canWithdraw. USDC: listed by POST /fapi/v3/aster/user-withdraw-info (live 2026-10-13:
+        // USDC on chains 1 / 56 / 4663 / 5042 / 42161 with perpMaxWithdrawAmount + withdrawFee).
+        withdrawAssets: ["USDT", "USDC"],
+    },
+    // GET /fapi/v1/exchangeInfo rateLimits: REQUEST_WEIGHT 2400/min
+    // (ORDERS 1200/min and 300/10s are separate order-count limits, not modeled).
+    // Declared only — per §10.9 the limiter is applied to new venues + lighter-rh.
+    rateLimit: { capacity: 2400, refillPerSec: 40, weights: null },
+    restrictedRegions: [],
+    symbolIdentity: "baseTicker",
+    publicData,
+    // §12: separate spot account (sapi /api/v3) + /asset/wallet/transfer. Agent signer needs canSpotTrade.
+    spot: {
+        accountModel: "separate",
+        quoteAssets: { mainnet: ["USDT", "USD1"], testnet: ["USDT", "USD1"] },
+        capabilities: { limitOrder: true, orderbook: true, cancel: true, transfer: true },
+        async createSpot(perp) {
+            const [{ AsterAdapter }, { AsterSpotAdapter }] = await Promise.all([
+                import("../aster.js"), import("../aster-spot.js"),
+            ]);
+            if (!(perp instanceof AsterAdapter))
+                throw new Error(`aster spot needs an AsterAdapter (got ${perp.name})`);
+            const spot = new AsterSpotAdapter(perp);
+            await spot.init();
+            return spot;
+        },
+    },
+    // PERCENT_PRICE is per symbol (live 2026-10-02: multiplierUp 1.02..1.15), not a venue
+    // constant — the adapter rejects a protection price outside the symbol's band
+    // (INVALID_PARAMS) at order time; this is only the outer venue-wide bound.
+    maxSlippageBps: 5000,
+    builderFee: BUILDER_FEE_CAPABILITIES["aster"],
+    create: async (ctx) => (await import("./create-helpers.js")).createAster(ctx),
+};

package/dist/exchanges/venues/create-helpers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Adapter construction for the pre-existing venues (pacifica / hyperliquid /
+ * lighter / lighter-rh / aster) — the single creation path that replaced the
+ * three copies in src/index.ts (getAdapter / _initWithOws / getAdapterForExchange)
+ * and the MCP server's getOrCreateAdapter (design §10.2).
+ *
+ * Signer tiers, as before: agent (Tier 1) → OWS master (Tier 2) → raw PK (Tier 3).
+ * Which tier signs a given request is still decided inside each adapter.
+ *
+ * Adapter modules are imported lazily so venue definitions stay cheap to load.
+ */
+import type { ExchangeAdapter } from "../interface.js";
+import type { VenueCreateContext } from "../venue.js";
+import type { LighterVenueId } from "./lighter-family.js";
+export declare function createPacifica(ctx: VenueCreateContext): Promise<ExchangeAdapter>;
+export declare function createHyperliquid(ctx: VenueCreateContext): Promise<ExchangeAdapter>;
+export declare function createLighterFamily(venue: LighterVenueId, ctx: VenueCreateContext): Promise<ExchangeAdapter>;
+export declare function createAster(ctx: VenueCreateContext): Promise<ExchangeAdapter>;

package/dist/exchanges/venues/create-helpers.js

@@ -0,0 +1,199 @@
+/**
+ * Adapter construction for the pre-existing venues (pacifica / hyperliquid /
+ * lighter / lighter-rh / aster) — the single creation path that replaced the
+ * three copies in src/index.ts (getAdapter / _initWithOws / getAdapterForExchange)
+ * and the MCP server's getOrCreateAdapter (design §10.2).
+ *
+ * Signer tiers, as before: agent (Tier 1) → OWS master (Tier 2) → raw PK (Tier 3).
+ * Which tier signs a given request is still decided inside each adapter.
+ *
+ * Adapter modules are imported lazily so venue definitions stay cheap to load.
+ */
+import { PerpError } from "../../errors.js";
+import { resolveBuilderGate } from "../builder-fee.js";
+/**
+ * Legacy-shaped agent meta (aster/hl/pac/lighter/lighter-rh), or null. An agent
+ * registered on another network is never attached: --no-agent drops it,
+ * otherwise AGENT_NOT_REGISTERED (a mainnet agent must not sign on testnet).
+ */
+async function legacyAgentOf(ctx, creds, venue) {
+    const agent = creds.agent;
+    if (agent === null)
+        return null;
+    if ("kind" in agent) {
+        throw new PerpError("INVALID_PARAMS", `${venue}: agent meta of kind "${agent.kind}" cannot sign for this venue`);
+    }
+    const { agentNetworkOf, assertAgentNetwork } = await import("../../agent-wallet/store.js");
+    if (ctx.noAgent && agentNetworkOf(venue, agent) !== ctx.network)
+        return null;
+    assertAgentNetwork(venue, agent, ctx.network);
+    return agent;
+}
+/**
+ * An imported agent (key created on the venue website) belongs to the master address on its
+ * record. If a DIFFERENT master wallet is loaded, account reads would show that wallet while the
+ * agent trades for its own master — refuse instead of mixing two accounts (Rule #2).
+ */
+async function assertImportedAgentMaster(venue, agent, masterAddress) {
+    const { agentSourceOf } = await import("../../agent-wallet/store.js");
+    if (agentSourceOf(venue, agent) !== "imported")
+        return;
+    // Pacifica records the master as a Solana address (base58, case-sensitive); EVM venues as 0x hex.
+    const recorded = venue === "pacifica" ? agent.userSolanaAddress : agent.userEvmAddress;
+    if (recorded === undefined || recorded === "") {
+        throw new PerpError("INVALID_PARAMS", `${venue} agent "${agent.agentName}" was imported without a master address`, {
+            remediation: `Re-import it: perp wallet agent import ${venue} --agent-name ${agent.agentName} --master-address <master> --replace`,
+        });
+    }
+    const same = venue === "pacifica" ? masterAddress === recorded : masterAddress.toLowerCase() === recorded.toLowerCase();
+    if (same)
+        return;
+    throw new PerpError("INVALID_PARAMS", `${venue} agent "${agent.agentName}" was imported for master ${recorded}, but the loaded master wallet is ${masterAddress}`, {
+        remediation: `Select the matching master (--ows <wallet>), or run with --no-agent to use ${masterAddress} directly`,
+    });
+}
+function effectiveCredentials(ctx) {
+    return ctx.readOnly
+        ? { pk: null, owsWallet: null, owsPassphrase: null, owsKeyToken: ctx.credentials.owsKeyToken, agent: null }
+        : ctx.credentials;
+}
+/** Passphrase that opens the OWS master wallet. resolveCredentials sets it whenever owsWallet is set. */
+function owsMasterPassphrase(creds) {
+    if (creds.owsPassphrase === null) {
+        throw new PerpError("PASSPHRASE_REQUIRED", `OWS wallet "${creds.owsWallet}" has no resolved passphrase`, {
+            remediation: "Pass --passphrase, set OWS_PASSPHRASE, or --ows-key <token>",
+        });
+    }
+    return creds.owsPassphrase;
+}
+// ── Pacifica ──
+export async function createPacifica(ctx) {
+    const creds = effectiveCredentials(ctx);
+    const { PacificaAdapter } = await import("../pacifica.js");
+    const { parseSolanaKeypair } = await import("../../config.js");
+    const { Keypair } = await import("@solana/web3.js");
+    const { loadSettings } = await import("../../settings.js");
+    const { OwsSolanaSigner } = await import("../../signer/ows-solana.js");
+    let adapter;
+    if (creds.owsWallet !== null) {
+        // Tier 2: OWS master. The keypair is unused for signing once a signer is injected.
+        adapter = new PacificaAdapter(Keypair.generate(), ctx.network, true);
+        adapter.setSigner(OwsSolanaSigner.create(creds.owsWallet, owsMasterPassphrase(creds)));
+    }
+    else if (creds.pk !== null) {
+        adapter = new PacificaAdapter(parseSolanaKeypair(creds.pk), ctx.network, true);
+    }
+    else {
+        // Read-only: no key material. index.ts:143 Keypair.generate() recorded as out of scope (§10.11).
+        adapter = new PacificaAdapter(Keypair.generate(), ctx.network, false);
+    }
+    const agent = await legacyAgentOf(ctx, creds, "pacifica");
+    if (agent !== null && !ctx.noAgent) {
+        // A loaded master (OWS / raw key) must be the master the imported agent was created for.
+        if (creds.owsWallet !== null || creds.pk !== null)
+            await assertImportedAgentMaster("pacifica", agent, adapter.publicKey);
+        // Pacifica agent wallets are created with an empty passphrase (runPacApproveFlow).
+        adapter.setAgentSigner(agent, OwsSolanaSigner.create(agent.agentWalletName, ""));
+    }
+    if (ctx.noAgent)
+        adapter.setNoAgent(true);
+    // Builder code: only settings builder.pacifica (off by default) + a confirmed approval.
+    const pac = adapter;
+    pac.builderFee = resolveBuilderGate("pacifica", ctx, loadSettings().builder, t => pac.builderApprovalOf(t), () => pac.publicKey);
+    return adapter;
+}
+// ── Hyperliquid ──
+export async function createHyperliquid(ctx) {
+    const creds = effectiveCredentials(ctx);
+    const { HyperliquidAdapter } = await import("../hyperliquid.js");
+    const { OwsEvmSigner } = await import("../../signer/ows-evm.js");
+    const isTestnet = ctx.network === "testnet";
+    const adapter = new HyperliquidAdapter(creds.pk ?? undefined, isTestnet);
+    if (ctx.hlDex !== null)
+        adapter.setDex(ctx.hlDex);
+    if (creds.owsWallet !== null)
+        adapter.setSigner(OwsEvmSigner.create(creds.owsWallet, owsMasterPassphrase(creds)));
+    const agent = await legacyAgentOf(ctx, creds, "hyperliquid");
+    // No master on this machine (e.g. an agent imported from the HL website): account reads use the
+    // master's public address from the agent record; the agent key signs trades.
+    if (agent !== null && !ctx.noAgent && creds.owsWallet === null && creds.pk === null)
+        adapter.setAddress(agent.userEvmAddress);
+    await adapter.init();
+    if (agent !== null && !ctx.noAgent && adapter.address)
+        await assertImportedAgentMaster("hyperliquid", agent, adapter.address);
+    // No implicit referral signing on creation (read-only paths share this path):
+    // referral is the explicit `perp -e hyperliquid wallet manage referral set`.
+    if (agent !== null) {
+        // HL agent wallets are created with an empty passphrase (runHlApproveFlow).
+        adapter.setAgentSigner(agent, OwsEvmSigner.create(agent.agentWalletName, ""));
+    }
+    if (ctx.noAgent)
+        adapter.setNoAgent(true);
+    // Builder fee: only settings builder.hyperliquid (off by default) + a confirmed master approval.
+    const { loadSettings } = await import("../../settings.js");
+    adapter.builderFee = resolveBuilderGate("hyperliquid", ctx, loadSettings().builder, t => adapter.builderApprovalOf(t), () => adapter.address);
+    return adapter;
+}
+// ── Lighter family ──
+export async function createLighterFamily(venue, ctx) {
+    const creds = effectiveCredentials(ctx);
+    if (venue === "lighter-rh" && creds.pk !== null) {
+        // Design §10.3: the Lighter RH master key is an OWS wallet only — no env / raw-PK tier.
+        throw new PerpError("NO_ENV_TIER", "Lighter RH does not accept a raw private key (env / --private-key / local wallet)", {
+            remediation: "Import the key into OWS (perp wallet import, key via hidden prompt / stdin) and run with --ows <wallet>, or register an agent: perp wallet agent approve lighter-rh",
+        });
+    }
+    const { LighterAdapter } = await import("../lighter.js");
+    const { OwsEvmSigner } = await import("../../signer/ows-evm.js");
+    const adapter = LighterAdapter.forVenue(venue, creds.pk ?? "", ctx.network === "testnet");
+    if (creds.owsWallet !== null)
+        adapter.setSigner(OwsEvmSigner.create(creds.owsWallet, owsMasterPassphrase(creds)));
+    const agent = await legacyAgentOf(ctx, creds, venue);
+    if (agent !== null && !ctx.noAgent) {
+        if (typeof agent.accountIndex !== "number" || typeof agent.apiKeyIndex !== "number") {
+            throw new PerpError("AGENT_NOT_REGISTERED", `${venue} agent "${agent.agentName}" has no accountIndex/apiKeyIndex`, {
+                remediation: `perp wallet agent approve ${venue} --rotate`,
+            });
+        }
+        // SSOT Rule #3: the agent L2 key lives only in the venue keystore.
+        const { loadLighterFamilyKey } = await import("../../agent-wallet/lighter-keystore.js");
+        adapter.setAgentSigner(agent, loadLighterFamilyKey(venue, ctx.network, agent.accountIndex, agent.apiKeyIndex, ""));
+        // No master on this machine (e.g. an API key imported from the website): account reads use the
+        // account owner's L1 address recorded on the agent; the API key signs trades.
+        if (creds.owsWallet === null && creds.pk === null)
+            adapter.setAddress(agent.userEvmAddress);
+    }
+    if (ctx.noAgent)
+        adapter.setNoAgent(true);
+    await adapter.init();
+    if (agent !== null && !ctx.noAgent && adapter.address)
+        await assertImportedAgentMaster(venue, agent, adapter.address);
+    // No implicit referral signing on creation: `perp -e lighter wallet manage referral set`.
+    return adapter;
+}
+// ── Aster ──
+export async function createAster(ctx) {
+    const creds = effectiveCredentials(ctx);
+    const { AsterAdapter } = await import("../aster.js");
+    const adapter = new AsterAdapter(creds.pk ?? undefined, ctx.network === "testnet");
+    await adapter.init();
+    if (creds.owsWallet !== null) {
+        const { OwsEvmSigner } = await import("../../signer/ows-evm.js");
+        adapter.setMasterSigner(OwsEvmSigner.create(creds.owsWallet, owsMasterPassphrase(creds)));
+    }
+    const agent = await legacyAgentOf(ctx, creds, "aster");
+    if (agent !== null) {
+        const { agentSigningStrategyFor } = await import("../../agent-wallet/signing-strategy.js");
+        const { agentSourceOf } = await import("../../agent-wallet/store.js");
+        // Empty token = no OWS API-key policy gating (legacy behavior). An imported agent's OWS wallet
+        // has no API key / policy and an empty passphrase, so it is always opened with "".
+        const token = agentSourceOf("aster", agent) === "imported" ? "" : (creds.owsKeyToken ?? "");
+        adapter.setAgent(agent, agentSigningStrategyFor(agent, token));
+    }
+    if (ctx.noAgent)
+        adapter.setNoAgent(true);
+    // Builder fee: only settings builder.aster (off by default) + a confirmed master approval.
+    const { loadSettings } = await import("../../settings.js");
+    adapter.builderFee = resolveBuilderGate("aster", ctx, loadSettings().builder, t => adapter.builderApprovalOf(t), () => adapter.userAddress);
+    return adapter;
+}

package/dist/exchanges/venues/hyperliquid.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Hyperliquid venue definition (design §10.1, §10.8, §10.13 #4).
+ * HIP-3 dexes are not venues: they are selected via VenueCreateContext.hlDex.
+ * Adapter + public-data code are loaded lazily (§10.10).
+ */
+import type { Network, VenueDefinition } from "../venue.js";
+/**
+ * Per-network parameters of Hyperliquid *user-signed* actions (approveAgent,
+ * userSetAbstraction, …) — EIP-712 domain "HyperliquidSignTransaction".
+ * `hyperliquidChain` selects the HL environment and prevents cross-network
+ * replay; `signatureChainId` is the wallet signing chain and must equal the
+ * domain chainId. Values mirror hyperliquid-python-sdk `sign_user_signed_action`
+ * ("Mainnet"/"Testnet") and the exchange-endpoint docs ("0xa4b1" Arbitrum One;
+ * testnet signs on Arbitrum Sepolia 0x66eee as the SDK does).
+ */
+export declare const HL_USER_SIGNED: Record<Network, {
+    hyperliquidChain: "Mainnet" | "Testnet";
+    signatureChainIdHex: string;
+    signatureChainId: number;
+}>;
+/** Hyperliquid client order id (cloid): "0x" + 32 lowercase hex chars (128 bits). */
+export declare const HL_CLOID_RE: RegExp;
+export declare const hyperliquidVenue: VenueDefinition;

package/dist/exchanges/venues/hyperliquid.js

@@ -0,0 +1,126 @@
+/**
+ * Hyperliquid venue definition (design §10.1, §10.8, §10.13 #4).
+ * HIP-3 dexes are not venues: they are selected via VenueCreateContext.hlDex.
+ * Adapter + public-data code are loaded lazily (§10.10).
+ */
+import { BUILDER_FEE_CAPABILITIES } from "../builder-fee.js";
+/**
+ * Per-network parameters of Hyperliquid *user-signed* actions (approveAgent,
+ * userSetAbstraction, …) — EIP-712 domain "HyperliquidSignTransaction".
+ * `hyperliquidChain` selects the HL environment and prevents cross-network
+ * replay; `signatureChainId` is the wallet signing chain and must equal the
+ * domain chainId. Values mirror hyperliquid-python-sdk `sign_user_signed_action`
+ * ("Mainnet"/"Testnet") and the exchange-endpoint docs ("0xa4b1" Arbitrum One;
+ * testnet signs on Arbitrum Sepolia 0x66eee as the SDK does).
+ */
+export const HL_USER_SIGNED = {
+    mainnet: { hyperliquidChain: "Mainnet", signatureChainIdHex: "0xa4b1", signatureChainId: 42161 },
+    testnet: { hyperliquidChain: "Testnet", signatureChainIdHex: "0x66eee", signatureChainId: 421614 },
+};
+/** Hyperliquid client order id (cloid): "0x" + 32 lowercase hex chars (128 bits). */
+export const HL_CLOID_RE = /^0x[0-9a-f]{32}$/;
+const publicData = {
+    async fetchFundingRates(net) {
+        return (await import("../../funding/legacy-public.js")).legacyPublicData("hyperliquid").fetchFundingRates(net);
+    },
+    async fetchMarkets(net) {
+        return (await import("../../funding/legacy-public.js")).legacyPublicData("hyperliquid").fetchMarkets(net);
+    },
+};
+export const hyperliquidVenue = {
+    id: "hyperliquid",
+    aliases: ["hl"],
+    displayName: "Hyperliquid",
+    family: "hyperliquid",
+    masterKeyKind: "evm",
+    agentKeyKind: "evm",
+    secretStorage: { kind: "ows-wallet", dir: null },
+    // REST: src/exchanges/hyperliquid.ts; mainnet WS: src/dashboard/ws-feeds.ts.
+    // Testnet WS is not in code → null. signingChainId: L1 action phantom-agent domain (hyperliquid.ts).
+    networks: {
+        mainnet: {
+            restUrl: "https://api.hyperliquid.xyz",
+            wsUrl: "wss://api.hyperliquid.xyz/ws",
+            explorerUrl: null,
+            signingChainId: 1337,
+            settlementChain: "hyperliquid",
+            collateral: ["USDC"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+        testnet: {
+            restUrl: "https://api.hyperliquid-testnet.xyz",
+            wsUrl: null,
+            explorerUrl: null,
+            signingChainId: 1337,
+            settlementChain: "hyperliquid",
+            collateral: ["USDC"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+    },
+    fundingRateBasis: { kind: "perHours", hours: 1 },
+    settlementIntervalHours: 1,
+    fundingVerified: true,
+    roles: ["marketData", "account", "trading"],
+    // marketOrder: IOC limit at a protection price (§13.2/§13.10 #5). Declared reference
+    // price = l2Book mid ((best bid + best ask) / 2) for native perps, HIP-3 and spot —
+    // no runtime substitute; a one-sided/empty book → PRICE_STALE. Rounding: 5 significant
+    // figures, max 6 − szDecimals (perp) / 8 − szDecimals (spot) decimals, toward crossing.
+    // tpsl stays "separateOrders": HL `normalTpsl` grouping was evaluated (§13.10 #12) and not
+    // used — its children have a fixed size equal to the parent and are fully cancelled when
+    // a partially filled parent is cancelled (HL docs, TP/SL orders), so a partially filled
+    // IOC entry would be left unprotected; separateOrders sizes TP/SL to the verified fill.
+    capabilities: {
+        marketOrder: "slippageBounded",
+        timeInForce: ["GTC", "IOC", "ALO"],
+        reduceOnlyTif: null,
+        // HL docs exchange-endpoint "Place an order": `c` "Cloid (client order id)" — "an optional
+        // 128 bit hex string, e.g. 0x1234567890abcdef1234567890abcdef"; cancelled by `cancelByCloid`,
+        // queried by info `orderStatus` (`oid` "u64 … or 16-byte hex string representing the client
+        // order id"). Native perps and HIP-3 dexes alike (the global asset id selects the dex).
+        clientOrderId: true,
+        orderAck: "sync",
+        tpsl: "separateOrders",
+        amend: "native",
+        batchPlaceMax: null,
+        marginModes: ["cross", "isolated"],
+        withdrawAssets: ["USDC"],
+    },
+    // HL docs "Rate limits and user limits": REST requests share an aggregated
+    // weight of 1200/min per IP. Exchange actions weigh 1 (unbatched); light info
+    // requests 2; most info requests 20; userRole 60.
+    // Declared only — per §10.9 the limiter is applied to new venues + lighter-rh.
+    rateLimit: {
+        capacity: 1200,
+        refillPerSec: 20,
+        weights: {
+            l2Book: 2, allMids: 2, clearinghouseState: 2, orderStatus: 2, spotClearinghouseState: 2, exchangeStatus: 2,
+            userRole: 60,
+        },
+    },
+    restrictedRegions: [],
+    symbolIdentity: "baseTicker",
+    publicData,
+    // §12: spot USDC is shared with perp margin when the account is unified (isUnifiedAccount, read at init).
+    spot: {
+        accountModel: "runtime",
+        quoteAssets: { mainnet: ["USDC"], testnet: ["USDC"] },
+        capabilities: { limitOrder: true, orderbook: true, cancel: true, transfer: true },
+        async createSpot(perp) {
+            const [{ HyperliquidAdapter }, { HyperliquidSpotAdapter }] = await Promise.all([
+                import("../hyperliquid.js"), import("../hyperliquid-spot.js"),
+            ]);
+            if (!(perp instanceof HyperliquidAdapter))
+                throw new Error(`hyperliquid spot needs a HyperliquidAdapter (got ${perp.name})`);
+            const spot = new HyperliquidSpotAdapter(perp);
+            await spot.init();
+            return spot;
+        },
+    },
+    maxSlippageBps: 5000,
+    builderFee: BUILDER_FEE_CAPABILITIES["hyperliquid"],
+    create: async (ctx) => (await import("./create-helpers.js")).createHyperliquid(ctx),
+};

package/dist/exchanges/venues/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Venue registry bootstrap: registers every venue definition exactly once.
+ * Importing this module (for its side effect) makes getVenue()/listVenues() usable.
+ */
+import { arcusVenue } from "./arcus.js";
+import { asterVenue } from "./aster.js";
+import { hyperliquidVenue } from "./hyperliquid.js";
+import { lighterRhVenue } from "./lighter-rh.js";
+import { lighterVenue } from "./lighter.js";
+import { ondoVenue } from "./ondo.js";
+import { pacificaVenue } from "./pacifica.js";
+import { qfexVenue } from "./qfex.js";
+export declare const ALL_VENUES: readonly [import("../venue.js").VenueDefinition, import("../venue.js").VenueDefinition, import("../venue.js").VenueDefinition, import("../venue.js").VenueDefinition, import("../venue.js").VenueDefinition, import("../venue.js").VenueDefinition, import("../venue.js").VenueDefinition, import("../venue.js").VenueDefinition];
+/** Idempotent: registers all venues on first call, no-op afterwards. */
+export declare function ensureVenuesRegistered(): void;
+export { pacificaVenue, hyperliquidVenue, lighterVenue, asterVenue, lighterRhVenue, ondoVenue, arcusVenue, qfexVenue, };

package/dist/exchanges/venues/index.js

@@ -0,0 +1,26 @@
+/**
+ * Venue registry bootstrap: registers every venue definition exactly once.
+ * Importing this module (for its side effect) makes getVenue()/listVenues() usable.
+ */
+import { registerVenue, tryResolveVenueId } from "../venue.js";
+import { arcusVenue } from "./arcus.js";
+import { asterVenue } from "./aster.js";
+import { hyperliquidVenue } from "./hyperliquid.js";
+import { lighterRhVenue } from "./lighter-rh.js";
+import { lighterVenue } from "./lighter.js";
+import { ondoVenue } from "./ondo.js";
+import { pacificaVenue } from "./pacifica.js";
+import { qfexVenue } from "./qfex.js";
+export const ALL_VENUES = [
+    pacificaVenue, hyperliquidVenue, lighterVenue, asterVenue,
+    lighterRhVenue, ondoVenue, arcusVenue, qfexVenue,
+];
+/** Idempotent: registers all venues on first call, no-op afterwards. */
+export function ensureVenuesRegistered() {
+    for (const def of ALL_VENUES) {
+        if (tryResolveVenueId(def.id) === null)
+            registerVenue(def);
+    }
+}
+ensureVenuesRegistered();
+export { pacificaVenue, hyperliquidVenue, lighterVenue, asterVenue, lighterRhVenue, ondoVenue, arcusVenue, qfexVenue, };