perp-cli 0.14.2 → 0.15.0

package/dist/exchanges/venue.js

@@ -2,7 +2,7 @@
  * Venue definitions — the single source of truth for "which venue, on which
  * network, signed how, funded how, supporting what".
  *
- * See docs/DESIGN-venue-abstraction.md §10. One adapter class may serve several
+ * One adapter class may serve several
  * venues (LighterAdapter serves `lighter` and `lighter-rh`).
  *
  * Venue definition modules must load adapter code lazily (`import()` inside
@@ -10,9 +10,21 @@
  */
 import { PerpError } from "../errors.js";
 import { isVenueId } from "./venue-types.js";
+import { optionsVenueWords } from "./options-venues.js";
 export const READ_ONLY_CREDENTIALS = {
     pk: null, owsWallet: null, owsPassphrase: null, owsKeyToken: null, agent: null,
 };
+export const OFFICIAL_API = { kind: "official" };
+/** "official" | "unofficial" — the per-row label for mixed-venue tables and JSON. */
+export function apiStatusOf(venue) {
+    return getVenue(venue).apiStatus.kind;
+}
+/** Human footnote for an unofficial-API venue; null for an official one. */
+export function unofficialApiNote(def) {
+    return def.apiStatus.kind === "unofficial"
+        ? `${def.displayName}: UNOFFICIAL API — ${def.apiStatus.note}`
+        : null;
+}
 // ── Registry ──
 const _venues = new Map();
 const _aliases = new Map();
@@ -29,8 +41,12 @@ export function registerVenue(def) {
     }
 }
 function unknownVenue(input) {
+    // An options venue (e.g. derive) is not a perp venue: say where it works instead.
+    const optionsOnly = optionsVenueWords().includes(input.toLowerCase())
+        ? ` — ${input} is options-only: perp -e ${input} options …`
+        : "";
     return new PerpError("UNKNOWN_VENUE", `Unknown venue: "${input}"`, {
-        remediation: `Use one of: ${[..._venues.keys()].join(", ")}`,
+        remediation: `Use one of: ${[..._venues.keys()].join(", ")}${optionsOnly}`,
     });
 }
 /** Resolve a venue id or alias. Throws UNKNOWN_VENUE. */
@@ -65,7 +81,41 @@ export function networkConfig(def, net) {
     }
     return cfg;
 }
+/**
+ * The uniform refusal for any account / trading / funds / agent / builder / bot action on a venue
+ * whose roles do not include `role` (a market-data-only venue such as TxFlow). Raised before any
+ * credential is resolved or any request is sent.
+ */
+export function roleUnsupported(def, feature, role = "trading") {
+    if (def.gatedRoles !== null && def.gatedRoles.roles.includes(role)) {
+        const { reason, remediation } = def.gatedRoles;
+        return new PerpError("CAPABILITY_UNSUPPORTED", `${def.id} does not support ${feature} — ${reason}`, {
+            venue: def.id, feature, reason, remediation,
+        });
+    }
+    const reason = def.apiStatus.kind === "unofficial"
+        ? `${def.displayName} is integrated through an unofficial read-only API (market data only)`
+        : `${def.displayName} is available for market data only (no ${role} role)`;
+    // Precedence: gatedRoles (above: a role switched off this release, e.g. RISEx) → the venue's own
+    // readOnlyRemediation (official read-only venues, e.g. Variational) → the generic text (TxFlow).
+    const remediation = def.readOnlyRemediation !== undefined
+        ? def.readOnlyRemediation
+        : def.apiStatus.kind === "unofficial"
+            ? `Trade on the ${def.displayName} website; perp-cli shows ${def.displayName} market data only (perp -e ${def.id} market list|info|funding|book|trades|kline)`
+            : `Use the market-data commands for ${def.id} (perp -e ${def.id} market list|funding)`;
+    return new PerpError("CAPABILITY_UNSUPPORTED", `${def.id} does not support ${feature} — ${reason}`, {
+        venue: def.id, feature, reason, remediation,
+    });
+}
+/** Throws roleUnsupported() unless the venue has `role`. */
+export function requireRole(def, role, feature) {
+    if (!def.roles.includes(role))
+        throw roleUnsupported(def, feature, role);
+}
 export function requireCapabilities(def) {
+    // A venue without the trading role is a definite capability refusal, not "not implemented yet".
+    if (!def.roles.includes("trading"))
+        throw roleUnsupported(def, "trading");
     if (!def.capabilities) {
         throw new PerpError("NOT_IMPLEMENTED", `${def.displayName} does not support trading via API`, {
             remediation: `${def.id} is available for market data only (funding/market commands)`,
@@ -88,7 +138,7 @@ export function parseVenueRef(ref) {
 }
 /**
  * Funding basis for a venue ref. HIP-3 dexes use the Hyperliquid core basis
- * (current behavior preserved; see design §10.1 — verify against live data).
+ * (current behavior preserved; verify against live data).
  * Throws for venues whose basis is per-market; callers must use the market's value.
  */
 export function fundingBasisOf(ref) {
@@ -114,7 +164,7 @@ export function settlementIntervalOf(ref) {
 /**
  * Refuse a venue whose funding rate is unverified (VenueDefinition.fundingVerified false) as a
  * leg of a funding strategy (arb scan ranking, arb exec / auto, funding bots). Uniform
- * CAPABILITY_UNSUPPORTED (design §13.6, §14.12 #6). Unknown venue refs throw UNKNOWN_VENUE.
+ * CAPABILITY_UNSUPPORTED. Unknown venue refs throw UNKNOWN_VENUE.
  */
 export function assertFundingArbVenue(ref) {
     const def = getVenue(parseVenueRef(ref).venue);

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

@@ -1,8 +1,7 @@
 /**
  * Arcus — perps on the Robinhood chain rootchain, USDG collateral
- * (design §4 Arcus column, §10.4, §10.10).
  * Not registered here; the registry module owns registerVenue().
- * Adapter and public-data code are loaded lazily (§10.10).
+ * Adapter and public-data code are loaded lazily.
  */
 import type { VenueDefinition } from "../venue.js";
 export declare const arcusVenue: VenueDefinition;

package/dist/exchanges/venues/arcus.js

@@ -1,8 +1,7 @@
 /**
  * Arcus — perps on the Robinhood chain rootchain, USDG collateral
- * (design §4 Arcus column, §10.4, §10.10).
  * Not registered here; the registry module owns registerVenue().
- * Adapter and public-data code are loaded lazily (§10.10).
+ * Adapter and public-data code are loaded lazily.
  */
 import { BUILDER_FEE_CAPABILITIES } from "../builder-fee.js";
 const publicData = {
@@ -50,6 +49,7 @@ export const arcusVenue = {
     settlementIntervalHours: 1,
     fundingVerified: true,
     roles: ["marketData", "account", "trading"],
+    gatedRoles: null,
     capabilities: {
         marketOrder: "slippageBounded",
         // GTC = GTT at goodTil now + 40 days (ARCUS_GOOD_TIL_HORIZON_MS); GTT kept as the venue alias.
@@ -83,7 +83,7 @@ export const arcusVenue = {
     restrictedRegions: ["US", "CA", "GB"],
     symbolIdentity: "baseTicker",
     publicData,
-    // §12: market swaps via router.spot.arcus.xyz, settled on-chain from the master EVM wallet.
+    // market swaps via router.spot.arcus.xyz, settled on-chain from the master EVM wallet.
     spot: {
         accountModel: "wallet",
         quoteAssets: { mainnet: ["USDG"], testnet: ["USDG"] },
@@ -99,9 +99,10 @@ export const arcusVenue = {
             return spot;
         },
     },
-    // Arcus venue limit per design §13.10 #1.
+    // Arcus venue slippage limit.
     maxSlippageBps: 1000,
     builderFee: BUILDER_FEE_CAPABILITIES["arcus"],
+    apiStatus: { kind: "official" },
     async create(ctx) {
         const { ArcusAdapter } = await import("../arcus/adapter.js");
         return new ArcusAdapter(arcusVenue, ctx);

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

@@ -1,6 +1,6 @@
 /**
- * Aster venue definition (design §10.1, §10.8, §10.13 #4).
- * Adapter + public-data code are loaded lazily (§10.10).
+ * Aster venue definition.
+ * Adapter + public-data code are loaded lazily.
  */
 import type { VenueDefinition } from "../venue.js";
 /** Aster client order id (V3 futures "New Order" `newClientOrderId` rule). */

package/dist/exchanges/venues/aster.js

@@ -1,6 +1,6 @@
 /**
- * Aster venue definition (design §10.1, §10.8, §10.13 #4).
- * Adapter + public-data code are loaded lazily (§10.10).
+ * Aster venue definition.
+ * Adapter + public-data code are loaded lazily.
  */
 import { BUILDER_FEE_CAPABILITIES } from "../builder-fee.js";
 /** Aster client order id (V3 futures "New Order" `newClientOrderId` rule). */
@@ -122,6 +122,7 @@ export const asterVenue = {
     settlementIntervalHours: "perMarket",
     fundingVerified: true,
     roles: ["marketData", "account", "trading"],
+    gatedRoles: null,
     capabilities: {
         // Market = IOC LIMIT at mark ± slippage (adapter marketOrder), never native MARKET.
         marketOrder: "slippageBounded",
@@ -146,12 +147,12 @@ export const asterVenue = {
     },
     // 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.
+    // Declared only — per 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.
+    // separate spot account (sapi /api/v3) + /asset/wallet/transfer. Agent signer needs canSpotTrade.
     spot: {
         accountModel: "separate",
         quoteAssets: { mainnet: ["USDT", "USD1"], testnet: ["USDT", "USD1"] },
@@ -172,5 +173,6 @@ export const asterVenue = {
     // (INVALID_PARAMS) at order time; this is only the outer venue-wide bound.
     maxSlippageBps: 5000,
     builderFee: BUILDER_FEE_CAPABILITIES["aster"],
+    apiStatus: { kind: "official" },
     create: async (ctx) => (await import("./create-helpers.js")).createAster(ctx),
 };

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

@@ -2,7 +2,7 @@
  * 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).
+ * and the MCP server's getOrCreateAdapter.
  *
  * 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.

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

@@ -2,7 +2,7 @@
  * 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).
+ * and the MCP server's getOrCreateAdapter.
  *
  * 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.
@@ -84,7 +84,7 @@ export async function createPacifica(ctx) {
         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).
+        // Read-only: no key material. index.ts:143 Keypair.generate() recorded as out of scope.
         adapter = new PacificaAdapter(Keypair.generate(), ctx.network, false);
     }
     const agent = await legacyAgentOf(ctx, creds, "pacifica");
@@ -138,7 +138,7 @@ export async function createHyperliquid(ctx) {
 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.
+        // 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",
         });

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

@@ -0,0 +1,21 @@
+/**
+ * Extended (formerly X10) — perps order book on Starknet, USD collateral. MARKET DATA ONLY in this
+ * version, through the OFFICIAL public REST API (https://api.docs.extended.exchange/).
+ *
+ *  - roles are ["marketData"]: every account / trading / funds / agent / builder / bot path
+ *    refuses with CAPABILITY_UNSUPPORTED before any request (venue.ts roleUnsupported(), with the
+ *    readOnlyRemediation below). There is no Extended order, signing (Stark), transfer or account
+ *    code at all; trading is planned for a later release.
+ *  - Hosts (docs "Mainnet" / "Testnet"): mainnet api.starknet.extended.exchange, testnet (Sepolia)
+ *    api.starknet.sepolia.extended.exchange. The old api.extended.exchange answers 404.
+ *  - Every request must carry a User-Agent header (docs "Mandatory headers"; none → HTTP 403).
+ *  - Funding (docs "Get funding rates history", docs.extended.exchange funding-payments): applied
+ *    once per hour; marketStats.fundingRate is the current hour's ACCRUING rate (recomputed every
+ *    minute) as a FRACTION per hour — see extended/public.ts.
+ * Not registered here; the registry module owns registerVenue().
+ */
+import type { VenueDefinition } from "../venue.js";
+export declare const EXTENDED_DOCS_URL = "https://api.docs.extended.exchange/";
+/** The remediation of every role refusal (owner decision: phase 1 is read-only). */
+export declare const EXTENDED_READ_ONLY_REMEDIATION = "Extended is read-only (market data) in this version; trading is planned for a later release. Market data: perp -e extended market list|prices|info|book|trades|funding|kline";
+export declare const extendedVenue: VenueDefinition;

package/dist/exchanges/venues/extended.js

@@ -0,0 +1,96 @@
+/**
+ * Extended (formerly X10) — perps order book on Starknet, USD collateral. MARKET DATA ONLY in this
+ * version, through the OFFICIAL public REST API (https://api.docs.extended.exchange/).
+ *
+ *  - roles are ["marketData"]: every account / trading / funds / agent / builder / bot path
+ *    refuses with CAPABILITY_UNSUPPORTED before any request (venue.ts roleUnsupported(), with the
+ *    readOnlyRemediation below). There is no Extended order, signing (Stark), transfer or account
+ *    code at all; trading is planned for a later release.
+ *  - Hosts (docs "Mainnet" / "Testnet"): mainnet api.starknet.extended.exchange, testnet (Sepolia)
+ *    api.starknet.sepolia.extended.exchange. The old api.extended.exchange answers 404.
+ *  - Every request must carry a User-Agent header (docs "Mandatory headers"; none → HTTP 403).
+ *  - Funding (docs "Get funding rates history", docs.extended.exchange funding-payments): applied
+ *    once per hour; marketStats.fundingRate is the current hour's ACCRUING rate (recomputed every
+ *    minute) as a FRACTION per hour — see extended/public.ts.
+ * Not registered here; the registry module owns registerVenue().
+ */
+export const EXTENDED_DOCS_URL = "https://api.docs.extended.exchange/";
+/** The remediation of every role refusal (owner decision: phase 1 is read-only). */
+export const EXTENDED_READ_ONLY_REMEDIATION = "Extended is read-only (market data) in this version; trading is planned for a later release. Market data: perp -e extended market list|prices|info|book|trades|funding|kline";
+/** Lazy: public.ts is only loaded when market data is actually requested. */
+const publicData = {
+    async fetchFundingRates(net) {
+        return (await import("../extended/public.js")).extendedPublicData.fetchFundingRates(net);
+    },
+    async fetchMarkets(net) {
+        return (await import("../extended/public.js")).extendedPublicData.fetchMarkets(net);
+    },
+};
+export const extendedVenue = {
+    id: "extended",
+    aliases: ["ext", "x10"],
+    displayName: "Extended",
+    family: "extended",
+    masterKeyKind: "none",
+    agentKeyKind: "none",
+    secretStorage: { kind: "none", dir: null },
+    networks: {
+        mainnet: {
+            restUrl: "https://api.starknet.extended.exchange/api/v1",
+            wsUrl: "wss://api.starknet.extended.exchange/stream.extended.exchange/v1",
+            explorerUrl: null,
+            signingChainId: null,
+            settlementChain: "starknet",
+            collateral: ["USD"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+        testnet: {
+            restUrl: "https://api.starknet.sepolia.extended.exchange/api/v1",
+            // The docs' SDK config (TESTNET_CONFIG stream_url). Unused (no ws codec); live 2026-10-19 it
+            // answered HTTP 403 to a public stream (api.starknet.sepolia… answered 503) — unverified.
+            wsUrl: "wss://starknet.sepolia.extended.exchange/stream.extended.exchange/v1",
+            explorerUrl: null,
+            signingChainId: null,
+            settlementChain: "starknet",
+            collateral: ["USD"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+    },
+    // Funding is applied once per hour on every perpetual market; the published rate is per hour.
+    fundingRateBasis: { kind: "perHours", hours: 1 },
+    settlementIntervalHours: 1,
+    // Not verified: the unit / sign of marketStats.fundingRate is not checked against a settled account
+    // funding payment (needs an account; RISEx's bar). Partial evidence only: docs + one recorded
+    // settlement (src/__tests__/fixtures/extended/funding-settlement-evidence.json — last accruing value
+    // == applied print on 8 markets, 5 of them at the baseline). And `_24_5` equities print 0 while
+    // their underlying is closed (TSLA_24_5: 34 of 43 weekend prints were 0), so hourly × 8760
+    // overstates them. Until settled against payments Extended is not a funding-arb venue.
+    fundingVerified: false,
+    roles: ["marketData"],
+    capabilities: null,
+    // Docs "Rate Limits": default tier 1,000 requests/minute per IP, all endpoints throttled by IP.
+    // 15/s sustained (900/min) leaves headroom for other processes on the same IP.
+    rateLimit: { capacity: 50, refillPerSec: 15, weights: null },
+    // docs.extended.exchange/extended-resources/legal/restricted-countries (2026-10-19), Category A;
+    // Ukraine is restricted only for Crimea / Donetsk / Kherson / Luhansk / Zaporizhzhia (no alpha-2).
+    // Warning-only and shown with credentials — unused while the venue is market data only.
+    restrictedRegions: ["AF", "CA", "HK", "CU", "IR", "IQ", "YE", "KP", "RU", "SY", "SC", "GB", "US"],
+    symbolIdentity: "baseTicker",
+    publicData,
+    spot: null,
+    // Unused (no trading role); the field is required by the definition shape.
+    maxSlippageBps: 1,
+    builderFee: null,
+    apiStatus: { kind: "official" },
+    gatedRoles: null,
+    readOnlyRemediation: EXTENDED_READ_ONLY_REMEDIATION,
+    // A public-only adapter: market data works, every account / trading method refuses.
+    async create(ctx) {
+        const { ExtendedPublicAdapter } = await import("../extended/adapter.js");
+        return new ExtendedPublicAdapter(extendedVenue, ctx.network);
+    },
+};

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

@@ -0,0 +1,30 @@
+/**
+ * GRVT venue definition — MARKET DATA ONLY in this version (official, documented API).
+ *
+ * GRVT (api-docs.grvt.io) is a hybrid perps exchange (off-chain matching, ZK-validium settlement on
+ * GRVT chain 325), USDT collateral. perp-cli reads its public Market Data REST API
+ * (`POST https://market-data.grvt.io/full/v1/<endpoint>`, no key) and nothing else:
+ *  - roles are ["marketData"]: every account / trading / funds / agent / builder / bot path refuses
+ *    with CAPABILITY_UNSUPPORTED before any request (venue.ts roleUnsupported(), with the
+ *    readOnlyRemediation below). There is no GRVT order, signing, transfer or account code at all.
+ *  - funding is unverified (fundingVerified false): the ticker's `funding_rate` is the venue's
+ *    indicative rate for the active interval (a moving estimate of the next payment, "predicted"),
+ *    quoted in percent per the market's own funding interval (4 h or 8 h, per instrument). The
+ *    percent unit is documented for settled history (/full/v1/funding "percentage points") and
+ *    observed identical in magnitude on the ticker (whose schema says "centibeeps"); it is not yet
+ *    checked against settled funding payments (an authenticated read) — kept out of arb ranking
+ *    unless --include-unverified.
+ * Not registered here; the registry module owns registerVenue().
+ */
+import type { RateLimitPolicy, VenueDefinition } from "../venue.js";
+export declare const GRVT_DOCS_URL = "https://api-docs.grvt.io";
+/** Uniform refusal text for every write / signer / setup-trading path on GRVT. */
+export declare const GRVT_READ_ONLY_REMEDIATION = "GRVT is read-only (market data) in this version; trading is planned for a later release";
+/**
+ * help.grvt.io "What are the rate limitations on Grvt?" — REST Market Data, every tier, per minute:
+ * GetInstrument / MiniTicker / Ticker 1500, all others 500 (WS JSON-RPC calls count too). Two token
+ * buckets sized so that no 60 s window can exceed the limit (capacity + 60 s × refill ≤ limit).
+ */
+export declare const GRVT_TICKER_RATE_LIMIT: RateLimitPolicy;
+export declare const GRVT_OTHER_RATE_LIMIT: RateLimitPolicy;
+export declare const grvtVenue: VenueDefinition;

package/dist/exchanges/venues/grvt.js

@@ -0,0 +1,98 @@
+/**
+ * GRVT venue definition — MARKET DATA ONLY in this version (official, documented API).
+ *
+ * GRVT (api-docs.grvt.io) is a hybrid perps exchange (off-chain matching, ZK-validium settlement on
+ * GRVT chain 325), USDT collateral. perp-cli reads its public Market Data REST API
+ * (`POST https://market-data.grvt.io/full/v1/<endpoint>`, no key) and nothing else:
+ *  - roles are ["marketData"]: every account / trading / funds / agent / builder / bot path refuses
+ *    with CAPABILITY_UNSUPPORTED before any request (venue.ts roleUnsupported(), with the
+ *    readOnlyRemediation below). There is no GRVT order, signing, transfer or account code at all.
+ *  - funding is unverified (fundingVerified false): the ticker's `funding_rate` is the venue's
+ *    indicative rate for the active interval (a moving estimate of the next payment, "predicted"),
+ *    quoted in percent per the market's own funding interval (4 h or 8 h, per instrument). The
+ *    percent unit is documented for settled history (/full/v1/funding "percentage points") and
+ *    observed identical in magnitude on the ticker (whose schema says "centibeeps"); it is not yet
+ *    checked against settled funding payments (an authenticated read) — kept out of arb ranking
+ *    unless --include-unverified.
+ * Not registered here; the registry module owns registerVenue().
+ */
+export const GRVT_DOCS_URL = "https://api-docs.grvt.io";
+/** Uniform refusal text for every write / signer / setup-trading path on GRVT. */
+export const GRVT_READ_ONLY_REMEDIATION = "GRVT is read-only (market data) in this version; trading is planned for a later release";
+/**
+ * help.grvt.io "What are the rate limitations on Grvt?" — REST Market Data, every tier, per minute:
+ * GetInstrument / MiniTicker / Ticker 1500, all others 500 (WS JSON-RPC calls count too). Two token
+ * buckets sized so that no 60 s window can exceed the limit (capacity + 60 s × refill ≤ limit).
+ */
+export const GRVT_TICKER_RATE_LIMIT = { capacity: 750, refillPerSec: 12, weights: null };
+export const GRVT_OTHER_RATE_LIMIT = { capacity: 250, refillPerSec: 4, weights: null };
+/** Lazy: public.ts is only loaded when market data is actually requested. */
+const publicData = {
+    async fetchFundingRates(net) {
+        return (await import("../grvt/public.js")).grvtPublicData.fetchFundingRates(net);
+    },
+    async fetchMarkets(net) {
+        return (await import("../grvt/public.js")).grvtPublicData.fetchMarkets(net);
+    },
+};
+export const grvtVenue = {
+    id: "grvt",
+    aliases: ["grv"],
+    displayName: "GRVT",
+    family: "grvt",
+    masterKeyKind: "none",
+    agentKeyKind: "none",
+    secretStorage: { kind: "none", dir: null },
+    networks: {
+        // grvt-pysdk grvt_raw_env.py (PROD / TESTNET); the docs' "Try it out" uses the same hosts.
+        mainnet: {
+            restUrl: "https://market-data.grvt.io",
+            wsUrl: "wss://market-data.grvt.io/ws/full",
+            explorerUrl: null,
+            signingChainId: null,
+            settlementChain: "offchain",
+            collateral: ["USDT"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+        testnet: {
+            restUrl: "https://market-data.testnet.grvt.io",
+            wsUrl: "wss://market-data.testnet.grvt.io/ws/full",
+            explorerUrl: null,
+            signingChainId: null,
+            settlementChain: "offchain",
+            collateral: ["USDT"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+    },
+    // Per instrument: funding_interval_hours is 8 or 4 (live 2026-10-19: 124 × 8 h, 60 × 4 h).
+    fundingRateBasis: "perMarket",
+    settlementIntervalHours: "perMarket",
+    fundingVerified: false,
+    roles: ["marketData"],
+    // Not a release gate (nothing is implemented and switched off): the venue has no trading code yet.
+    gatedRoles: null,
+    capabilities: null,
+    // "All others" bucket (instruments, book, trade, funding, kline, margin_rules); the ticker bucket
+    // is GRVT_TICKER_RATE_LIMIT (grvt/client.ts picks per endpoint).
+    rateLimit: GRVT_OTHER_RATE_LIMIT,
+    // help.grvt.io/en/articles/9711621-restricted-jurisdictions (also Crimea / Donetsk / Luhansk /
+    // Kherson / Zaporizhzhya / Sevastopol regions). Trading needs KYC — relevant once trading lands.
+    restrictedRegions: ["US", "PR", "AS", "GU", "MP", "VI", "SG", "HK", "KP", "IR", "MM", "BY", "CU", "AF", "CA", "LY", "RU", "SO", "SS", "SD", "SY"],
+    symbolIdentity: "baseTicker",
+    publicData,
+    spot: null,
+    // Unused (no trading role); the field is required by the definition shape.
+    maxSlippageBps: 1,
+    builderFee: null,
+    apiStatus: { kind: "official" },
+    readOnlyRemediation: GRVT_READ_ONLY_REMEDIATION,
+    // A public-only adapter: market data works, every account / trading method refuses.
+    async create(ctx) {
+        const { GrvtPublicAdapter } = await import("../grvt/adapter.js");
+        return new GrvtPublicAdapter(grvtVenue, ctx.network);
+    },
+};

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

@@ -1,7 +1,7 @@
 /**
- * Hyperliquid venue definition (design §10.1, §10.8, §10.13 #4).
+ * Hyperliquid venue definition.
  * HIP-3 dexes are not venues: they are selected via VenueCreateContext.hlDex.
- * Adapter + public-data code are loaded lazily (§10.10).
+ * Adapter + public-data code are loaded lazily.
  */
 import type { Network, VenueDefinition } from "../venue.js";
 /**

package/dist/exchanges/venues/hyperliquid.js

@@ -1,7 +1,7 @@
 /**
- * Hyperliquid venue definition (design §10.1, §10.8, §10.13 #4).
+ * Hyperliquid venue definition.
  * HIP-3 dexes are not venues: they are selected via VenueCreateContext.hlDex.
- * Adapter + public-data code are loaded lazily (§10.10).
+ * Adapter + public-data code are loaded lazily.
  */
 import { BUILDER_FEE_CAPABILITIES } from "../builder-fee.js";
 /**
@@ -36,7 +36,7 @@ export const hyperliquidVenue = {
     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).
+    // Testnet WS per the HL websocket docs (opened in the 2026-10-13 ws probe). signingChainId: L1 action phantom-agent domain (hyperliquid.ts).
     networks: {
         mainnet: {
             restUrl: "https://api.hyperliquid.xyz",
@@ -51,7 +51,7 @@ export const hyperliquidVenue = {
         },
         testnet: {
             restUrl: "https://api.hyperliquid-testnet.xyz",
-            wsUrl: null,
+            wsUrl: "wss://api.hyperliquid-testnet.xyz/ws",
             explorerUrl: null,
             signingChainId: 1337,
             settlementChain: "hyperliquid",
@@ -65,11 +65,12 @@ export const hyperliquidVenue = {
     settlementIntervalHours: 1,
     fundingVerified: true,
     roles: ["marketData", "account", "trading"],
-    // marketOrder: IOC limit at a protection price (§13.2/§13.10 #5). Declared reference
+    gatedRoles: null,
+    // marketOrder: IOC limit at a protection price. 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
+    // tpsl stays "separateOrders": HL `normalTpsl` grouping was evaluated 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.
@@ -92,7 +93,7 @@ export const hyperliquidVenue = {
     // 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.
+    // Declared only — per the limiter is applied to new venues + lighter-rh.
     rateLimit: {
         capacity: 1200,
         refillPerSec: 20,
@@ -104,7 +105,7 @@ export const hyperliquidVenue = {
     restrictedRegions: [],
     symbolIdentity: "baseTicker",
     publicData,
-    // §12: spot USDC is shared with perp margin when the account is unified (isUnifiedAccount, read at init).
+    // spot USDC is shared with perp margin when the account is unified (isUnifiedAccount, read at init).
     spot: {
         accountModel: "runtime",
         quoteAssets: { mainnet: ["USDC"], testnet: ["USDC"] },
@@ -122,5 +123,6 @@ export const hyperliquidVenue = {
     },
     maxSlippageBps: 5000,
     builderFee: BUILDER_FEE_CAPABILITIES["hyperliquid"],
+    apiStatus: { kind: "official" },
     create: async (ctx) => (await import("./create-helpers.js")).createHyperliquid(ctx),
 };

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

@@ -10,7 +10,12 @@ 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];
+import { risexVenue } from "./risex.js";
+import { txflowVenue } from "./txflow.js";
+import { variationalVenue } from "./variational.js";
+import { grvtVenue } from "./grvt.js";
+import { extendedVenue } from "./extended.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, 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, };
+export { pacificaVenue, hyperliquidVenue, lighterVenue, asterVenue, lighterRhVenue, ondoVenue, arcusVenue, qfexVenue, risexVenue, txflowVenue, variationalVenue, grvtVenue, extendedVenue, };

package/dist/exchanges/venues/index.js

@@ -11,9 +11,15 @@ import { lighterVenue } from "./lighter.js";
 import { ondoVenue } from "./ondo.js";
 import { pacificaVenue } from "./pacifica.js";
 import { qfexVenue } from "./qfex.js";
+import { risexVenue } from "./risex.js";
+import { txflowVenue } from "./txflow.js";
+import { variationalVenue } from "./variational.js";
+import { grvtVenue } from "./grvt.js";
+import { extendedVenue } from "./extended.js";
 export const ALL_VENUES = [
     pacificaVenue, hyperliquidVenue, lighterVenue, asterVenue,
-    lighterRhVenue, ondoVenue, arcusVenue, qfexVenue,
+    lighterRhVenue, ondoVenue, arcusVenue, qfexVenue, risexVenue, txflowVenue, variationalVenue, grvtVenue,
+    extendedVenue,
 ];
 /** Idempotent: registers all venues on first call, no-op afterwards. */
 export function ensureVenuesRegistered() {
@@ -23,4 +29,4 @@ export function ensureVenuesRegistered() {
     }
 }
 ensureVenuesRegistered();
-export { pacificaVenue, hyperliquidVenue, lighterVenue, asterVenue, lighterRhVenue, ondoVenue, arcusVenue, qfexVenue, };
+export { pacificaVenue, hyperliquidVenue, lighterVenue, asterVenue, lighterRhVenue, ondoVenue, arcusVenue, qfexVenue, risexVenue, txflowVenue, variationalVenue, grvtVenue, extendedVenue, };