perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/venue-types.js

@@ -1,12 +1,12 @@
 /**
- * Venue-level data contracts (docs/DESIGN-venue-abstraction.md §10).
+ * Venue-level data contracts.
  *
  * SSOT Rule #2: every "unknown" value is `T | null`, never optional, never a
  * silently substituted default.
  */
 export const VENUE_IDS = [
     "pacifica", "hyperliquid", "lighter", "aster",
-    "lighter-rh", "ondo", "arcus", "qfex",
+    "lighter-rh", "ondo", "arcus", "qfex", "risex", "txflow", "variational", "grvt", "extended",
 ];
 export const LEGACY_VENUE_IDS = ["pacifica", "hyperliquid", "lighter", "aster"];
 export function isVenueId(s) {
@@ -21,10 +21,17 @@ export function rateToHourly(rate, basis) {
         return rate / basis.hours;
     return rate / (24 * 365);
 }
-function decimalsOf(step) {
-    const s = step.includes("e") || step.includes("E") ? Number(step).toFixed(20).replace(/0+$/, "") : step;
-    const dot = s.indexOf(".");
-    return dot === -1 ? 0 : s.length - dot - 1;
+/**
+ * Quantity decimals of a lot step, or null when the step is not a power of ten ≤ 1 ("0.001" → 3,
+ * "1" → 0; TxFlow "10" / "100" and a "0.5" step → null): a decimals count cannot express them, and
+ * 0 next to stepSize "10" read as "any integer". `stepSize` is the authoritative grid.
+ */
+export function decimalsOf(step) {
+    const s = step.includes("e") || step.includes("E") ? Number(step).toFixed(20) : step;
+    const t = s.includes(".") ? s.replace(/0+$/, "").replace(/\.$/, "") : s;
+    if (!/^(1|0\.0*1)$/.test(t))
+        return null;
+    return t === "1" ? 0 : t.length - 2;
 }
 /** Pure mapping used by new-venue adapters to serve the legacy getMarkets(). */
 /** Tick/step/leverage required for order entry. Throws when the venue did not publish them. */
@@ -34,9 +41,54 @@ export function requireTradingPrecision(m) {
     }
     return { tickSize: m.tickSize, stepSize: m.stepSize, maxLeverage: m.maxLeverage };
 }
-export function toLegacyMarketInfo(m) {
-    const p = requireTradingPrecision(m);
+/**
+ * What a VenueMarket.fundingRate is per venue (REST source), consistent with the WS `rateKind` where
+ * both read the same field. null = not verified. Venues with per-row kinds (GRVT, Extended,
+ * Variational) set their own on top.
+ *  - arcus: /v1/markets fundingRate = the last hourly settlement (WS markets channel: lastSettled).
+ *  - risex: current_funding_rate equals the last settled print (venues/risex.ts, verified 2026-10-14).
+ *  - txflow: allAssetCtxs `funding` moves every tick — the running period's accruing estimate.
+ *  - hyperliquid: metaAndAssetCtxs `funding` (WS allDexsAssetCtxs) — accruing.
+ *  - aster: premiumIndex lastFundingRate moves during the period (WS markPrice@arr `r`) — accruing.
+ *  - pacifica: /info/prices `funding` = the last settled hourly rate (WS prices `funding`).
+ *  - lighter, lighter-rh: WS market_stats funding_rate = the newest /fundings print — lastSettled.
+ *  - grvt: the ticker's funding rate is the next settlement's (predicted) — as the adapter labels it.
+ *  - extended: /info/markets fundingRate is the current hour's accruing rate.
+ *  - variational: the quoted rate is the predicted next payment.
+ *  - ondo, qfex: not verified against settled prints → null.
+ */
+const VENUE_MARKET_RATE_KIND = {
+    arcus: "lastSettled",
+    risex: "lastSettled",
+    txflow: "accruing",
+    hyperliquid: "accruing",
+    aster: "accruing",
+    pacifica: "lastSettled",
+    lighter: "lastSettled",
+    "lighter-rh": "lastSettled",
+    grvt: "predicted",
+    extended: "accruing",
+    variational: "predicted",
+    // Ondo /v1/perps/contracts `fundingRate` is the last settled print: live 2026-10-19 21:17 UTC it
+    // equalled the 21:00 funding_rate_history row on every market whose rate moves (CXMT 0.0001139,
+    // BB 0.00003, PURR 0.0000182, WTI 0.0000038, USDJPY 0.000001 — each different from the 20:00 print).
+    ondo: "lastSettled",
+};
+export function fundingRateKindOf(venue, fundingRate) {
+    if (fundingRate === null)
+        return null;
+    const k = VENUE_MARKET_RATE_KIND[venue];
+    return k === undefined ? null : k;
+}
+/**
+ * THE market-row shape (`perp market list` / `info` / `prices`, ExchangeMarketInfo) of a
+ * VenueMarket — the one mapper for the CLI adapters of VenueMarket venues and the keyless MCP
+ * `get_markets` public directory rows. It does not require trading precision: a public row
+ * without a published tick / lot / leverage maps those to null.
+ */
+export function venueMarketRow(m) {
     const hours = m.fundingRateBasis.kind === "perHours" ? m.fundingRateBasis.hours : null;
+    const status = m.status;
     return {
         symbol: m.symbol,
         markPrice: m.markPrice,
@@ -44,13 +96,22 @@ export function toLegacyMarketInfo(m) {
         fundingRate: m.fundingRate,
         volume24h: m.volume24h,
         openInterest: m.openInterest,
-        maxLeverage: p.maxLeverage,
-        sizeDecimals: decimalsOf(p.stepSize),
-        stepSize: p.stepSize,
+        maxLeverage: m.maxLeverage,
+        sizeDecimals: m.stepSize === null ? null : decimalsOf(m.stepSize),
+        stepSize: m.stepSize,
         fundingHours: hours,
         marginTiers: m.marginTiers,
+        tradable: m.tradable,
+        fundingRateKind: fundingRateKindOf(m.venue, m.fundingRate),
+        quoteAsset: m.quoteAsset,
+        status: typeof status === "string" ? status : null,
     };
 }
+/** venueMarketRow for an adapter that trades the market: tick / lot / leverage must be published. */
+export function toLegacyMarketInfo(m) {
+    requireTradingPrecision(m);
+    return venueMarketRow(m);
+}
 /**
  * Attach an execution record to a result built without one. Fields of `partial`
  * that are absent are recorded as null (unknown), never defaulted to a value.
@@ -85,3 +146,13 @@ export function parseOrderRef(s) {
         return { kind: "clientOrderId", value: s.slice(2) };
     return { kind: "orderId", value: s };
 }
+/**
+ * Next funding settlement of a venue that documents hourly settlement on the hour (UTC): the next
+ * top of the hour after `now`. Used only where the venue's docs say so — Hyperliquid ("paid every
+ * hour"), Lighter ("at each hour mark"), Pacifica ("at the end of each 1-hour interval") — and
+ * their settled history is stamped on the hour (live 2026-10-19: HL 18:00:00.139 … 21:00:00.032,
+ * Pacifica 18:00:02.674 … 21:00:02.574). Other venues keep null unless they publish the time.
+ */
+export function nextTopOfHourMs(now = Date.now()) {
+    return (Math.floor(now / 3_600_000) + 1) * 3_600_000;
+}

package/dist/exchanges/venue.d.ts

@@ -2,14 +2,16 @@
  * 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
  * `create`) so that public-data paths never pull in heavy SDKs (lighter WASM).
  */
-import type { ExchangeAdapter } from "./interface.js";
-import type { SpotAdapter } from "./spot-interface.js";
+import { PerpError } from "../errors.js";
+import type { ExchangeAdapter, ExchangeBalance, ExchangePosition } from "./interface.js";
+import { type AddressKind } from "./address.js";
+import type { SpotAdapter, SpotBalance } from "./spot-interface.js";
 import type { FundingRateBasis, LegacyVenueId, Network, TimeInForce, VenueFundingRate, VenueId, VenueMarket } from "./venue-types.js";
 import { isVenueId } from "./venue-types.js";
 import type { AnyAgentMeta } from "../settings.js";
@@ -103,7 +105,75 @@ export interface RateLimitPolicy {
 }
 export interface VenuePublicData {
     fetchFundingRates(net: Network): Promise<VenueFundingRate[]>;
-    fetchMarkets(net: Network): Promise<VenueMarket[]>;
+    /**
+     * `opts.funding: false` = the caller needs marks / precision only: a venue whose funding rate
+     * costs an extra read (Lighter: the WS market_stats snapshot) skips it (rows fundingRate null).
+     */
+    fetchMarkets(net: Network, opts?: {
+        funding?: boolean;
+    }): Promise<VenueMarket[]>;
+    /**
+     * Keyless open positions of ANY account by its public address (`account positions --address`,
+     * MCP get_positions_by_address). Present = the venue supports it; `addressKind` is then the
+     * address format it takes (checked before any request). Rows are the keyed `getPositions`
+     * mapping (the same mapper) with plain symbols.
+     */
+    addressKind?: AddressKind;
+    fetchPositionsByAddress?(net: Network, address: string, opts: PublicPositionsOptions): Promise<PublicPositionsResult>;
+    /**
+     * Keyless balances of ANY account by its public address (`account balance --address`, MCP
+     * get_balance_by_address). Present = the venue supports it (takes `addressKind`, like
+     * fetchPositionsByAddress). The balance is the keyed `getBalance` math (the same function).
+     */
+    fetchBalanceByAddress?(net: Network, address: string, opts: PublicPositionsOptions): Promise<PublicBalanceResult>;
+}
+/** One Lighter account (sub-account) of an address: its balance and spot assets. */
+export interface PublicAccountBalance {
+    accountIndex: number;
+    balance: ExchangeBalance;
+    spot: SpotBalance[];
+}
+export interface PublicBalanceResult {
+    /** The account's balance (the keyed getBalance fields + the venue's extras); null on Lighter (per account in `accounts`). */
+    balance: ExchangeBalance | null;
+    /** Spot token balances where the venue publishes them by address; null = not published (nothing invented). */
+    spot: SpotBalance[] | null;
+    /** Lighter / Lighter RH: every account of the address (or the one of accountIndex); null elsewhere. */
+    accounts: PublicAccountBalance[] | null;
+    /** Hyperliquid: HIP-3 dexes with a non-zero account value (the dex's own perp clearinghouse); null elsewhere. */
+    dexes: Record<string, ExchangeBalance> | null;
+    /** Hyperliquid: the account abstraction mode the balance was read under; null elsewhere. */
+    accountMode: string | null;
+    /** Sub-reads that failed (Hyperliquid: one HIP-3 dex, "hip3:<dex>") — unknown, never zero. */
+    errors: Record<string, {
+        code: string;
+        message: string;
+    }>;
+    notes: string[];
+}
+export interface PublicPositionsOptions {
+    /** Lighter: one account of the address (sub-accounts); default every account. */
+    accountIndex?: number;
+}
+/** A position read by public address: the keyed row plus where it lives. */
+export interface PublicPosition extends ExchangePosition {
+    /** Hyperliquid: the HIP-3 dex of the row; null = the native perp dex. */
+    dex?: string | null;
+    /** Lighter: the account (sub-account) index the row belongs to. */
+    accountIndex?: number;
+}
+export interface PublicPositionsResult {
+    positions: PublicPosition[];
+    /**
+     * Sub-reads that failed while the others succeeded (Hyperliquid: one HIP-3 dex), keyed by
+     * source ("hip3:xyz"). Their rows are unknown — never silently absent: callers surface them.
+     */
+    errors: Record<string, {
+        code: string;
+        message: string;
+    }>;
+    /** Human notes on an empty answer ("no Lighter account for this address"). */
+    notes: string[];
 }
 export interface VenueCredentials {
     /** Raw private key from --private-key or (legacy venues only) env. */
@@ -127,11 +197,29 @@ export interface VenueCreateContext {
 export declare const READ_ONLY_CREDENTIALS: VenueCredentials;
 export type VenueRole = "marketData" | "account" | "trading";
 export type SymbolIdentity = "baseTicker" | "explicit";
+/**
+ * How perp-cli reaches the venue. "official" = a documented public API. "unofficial" = an
+ * undocumented API (e.g. the one the venue's own web app uses) that may change or be blocked
+ * without notice; every user-facing surface (JSON `venueApi` / `apiStatus`, human footnotes,
+ * MCP output, the landing screen, the skill docs) labels data read through it.
+ */
+export type VenueApiStatus = {
+    kind: "official";
+} | {
+    kind: "unofficial";
+    note: string;
+    docs: string | null;
+};
+export declare const OFFICIAL_API: VenueApiStatus;
+/** "official" | "unofficial" — the per-row label for mixed-venue tables and JSON. */
+export declare function apiStatusOf(venue: VenueId): VenueApiStatus["kind"];
+/** Human footnote for an unofficial-API venue; null for an official one. */
+export declare function unofficialApiNote(def: VenueDefinition): string | null;
 export interface VenueDefinition {
     id: VenueId;
     aliases: readonly string[];
     displayName: string;
-    family: "pacifica" | "hyperliquid" | "lighter" | "aster" | "ondo" | "arcus" | "qfex";
+    family: "pacifica" | "hyperliquid" | "lighter" | "aster" | "ondo" | "arcus" | "qfex" | "risex" | "txflow" | "variational" | "grvt" | "extended";
     masterKeyKind: MasterKeyKind;
     agentKeyKind: AgentKeyKind;
     secretStorage: SecretStorage;
@@ -143,12 +231,22 @@ export interface VenueDefinition {
     settlementIntervalHours: number | "perMarket";
     /**
      * false = the unit / meaning of the venue's published funding rate is not verified against
-     * settled funding payments yet (design §14.12 #6). Such a venue is left out of cross-venue
+     * settled funding payments yet. Such a venue is left out of cross-venue
      * funding comparison (fetchVenuesRates drops it unless includeUnverified is passed), its
      * adapter reports fundingRate null to bots, and funding-arb strategies refuse it as a leg.
      */
     fundingVerified: boolean;
     roles: readonly VenueRole[];
+    /**
+     * Roles that are implemented but switched off in this release (phased venue rollout, e.g.
+     * RISEx trading in 0.15.0). They are NOT in `roles`; roleUnsupported() uses `reason` /
+     * `remediation` for them. null = nothing held back.
+     */
+    gatedRoles: {
+        roles: readonly VenueRole[];
+        reason: string;
+        remediation: string;
+    } | null;
     /** null when the venue has no trading role. */
     capabilities: VenueCapabilities | null;
     rateLimit: RateLimitPolicy;
@@ -159,11 +257,10 @@ export interface VenueDefinition {
     publicData: VenuePublicData;
     /** null when the venue cannot produce an adapter (public data only). */
     create: ((ctx: VenueCreateContext) => Promise<ExchangeAdapter>) | null;
-    /** null = venue has no spot trading (§12). */
+    /** null = venue has no spot trading. */
     spot: VenueSpotDefinition | null;
     /**
-     * Largest slippage bound (bps) a market-type order may carry on this venue
-     * (design §13.10 #1). resolveSlippage() rejects anything above it with
+     * Largest slippage bound (bps) a market-type order may carry on this venue. resolveSlippage() rejects anything above it with
      * INVALID_PARAMS before sending — never clamps.
      */
     maxSlippageBps: number;
@@ -173,6 +270,13 @@ export interface VenueDefinition {
      * settings.builder.<venue> and the approval is confirmed.
      */
     builderFee: BuilderFeeCapability | null;
+    /** Official documented API, or an unofficial one that is labelled everywhere (VenueApiStatus). */
+    apiStatus: VenueApiStatus;
+    /**
+     * Remediation of every role refusal (roleUnsupported) on a venue that is read-only in this
+     * version (Variational, GRVT, Extended). Absent = the generic market-data-only remediation.
+     */
+    readOnlyRemediation?: string;
 }
 export declare function registerVenue(def: VenueDefinition): void;
 /** Resolve a venue id or alias. Throws UNKNOWN_VENUE. */
@@ -181,7 +285,33 @@ export declare function tryResolveVenueId(nameOrAlias: string): VenueId | null;
 export declare function getVenue(nameOrAlias: string): VenueDefinition;
 export declare function listVenues(): VenueDefinition[];
 export declare function listVenuesWithRole(role: VenueRole): VenueDefinition[];
+/** Venues that read positions by public address (VenuePublicData.fetchPositionsByAddress). */
+export declare function listPublicPositionVenues(): VenueDefinition[];
+/** CAPABILITY_UNSUPPORTED for a venue without public-address position reads (registry-derived). */
+export declare function publicPositionsUnsupported(def: VenueDefinition): PerpError;
+/**
+ * Open positions of `address` on `venue`, keyless: unsupported venue → CAPABILITY_UNSUPPORTED,
+ * wrong address format → INVALID_PARAMS, both before any request.
+ */
+export declare function fetchPositionsByAddress(venue: string, net: Network, address: string, opts?: PublicPositionsOptions): Promise<PublicPositionsResult>;
+/** Venues that read balances by public address (VenuePublicData.fetchBalanceByAddress). */
+export declare function listPublicBalanceVenues(): VenueDefinition[];
+/** CAPABILITY_UNSUPPORTED for a venue without public-address balance reads (registry-derived). */
+export declare function publicBalanceUnsupported(def: VenueDefinition): PerpError;
+/**
+ * Balances of `address` on `venue`, keyless: unsupported venue → CAPABILITY_UNSUPPORTED, wrong
+ * address format → INVALID_PARAMS, both before any request.
+ */
+export declare function fetchBalanceByAddress(venue: string, net: Network, address: string, opts?: PublicPositionsOptions): Promise<PublicBalanceResult>;
 export declare function networkConfig(def: VenueDefinition, net: Network): VenueNetworkConfig;
+/**
+ * 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 declare function roleUnsupported(def: VenueDefinition, feature: string, role?: VenueRole): PerpError;
+/** Throws roleUnsupported() unless the venue has `role`. */
+export declare function requireRole(def: VenueDefinition, role: VenueRole, feature: string): void;
 export declare function requireCapabilities(def: VenueDefinition): VenueCapabilities;
 /**
  * A venue reference as it appears in stored data and funding keys:
@@ -194,7 +324,7 @@ export interface VenueRef {
 export declare function parseVenueRef(ref: string): VenueRef;
 /**
  * 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 declare function fundingBasisOf(ref: string): FundingRateBasis;
@@ -202,9 +332,18 @@ export declare function settlementIntervalOf(ref: string): number;
 /**
  * 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 declare function assertFundingArbVenue(ref: string): void;
+/**
+ * Market rows (`market list|prices|info`, MCP get_markets) state whether their venue's funding rate
+ * is verified — on every venue, true or false (VenueDefinition.fundingVerified), so a consumer
+ * never has to read a missing field as "verified". A venue ref ("hip3:xyz" → hyperliquid) is
+ * resolved; an unknown ref leaves the rows as they are.
+ */
+export declare function withFundingVerified<T extends object>(venue: string, rows: T[]): Array<T & {
+    fundingVerified: boolean;
+}> | T[];
 export declare function isLegacyVenue(def: VenueDefinition): def is VenueDefinition & {
     id: LegacyVenueId;
 };

package/dist/exchanges/venue.js

@@ -2,17 +2,30 @@
  * 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
  * `create`) so that public-data paths never pull in heavy SDKs (lighter WASM).
  */
 import { PerpError } from "../errors.js";
+import { requireAddressOfKind } from "./address.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 +42,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. */
@@ -56,6 +73,64 @@ export function listVenues() {
 export function listVenuesWithRole(role) {
     return listVenues().filter(v => v.roles.includes(role));
 }
+/** Venues that read positions by public address (VenuePublicData.fetchPositionsByAddress). */
+export function listPublicPositionVenues() {
+    return listVenues().filter(v => typeof v.publicData.fetchPositionsByAddress === "function" && v.publicData.addressKind !== undefined);
+}
+/** CAPABILITY_UNSUPPORTED for a venue without public-address position reads (registry-derived). */
+export function publicPositionsUnsupported(def) {
+    const reason = !def.roles.includes("account")
+        ? `${def.displayName} is available for market data only (no account reads)`
+        : `${def.displayName} publishes positions only to the account itself (signed or API-key reads)`;
+    const supported = listPublicPositionVenues().map(v => v.id).join(", ");
+    return new PerpError("CAPABILITY_UNSUPPORTED", `${def.id} does not support publicPositions — ${reason}`, {
+        venue: def.id, feature: "publicPositions", reason,
+        remediation: `Public-address reads: ${supported}; for your own account: perp -e ${def.id} account positions`,
+    });
+}
+/**
+ * Open positions of `address` on `venue`, keyless: unsupported venue → CAPABILITY_UNSUPPORTED,
+ * wrong address format → INVALID_PARAMS, both before any request.
+ */
+export async function fetchPositionsByAddress(venue, net, address, opts = {}) {
+    const def = getVenue(venue);
+    const pd = def.publicData;
+    if (pd.fetchPositionsByAddress === undefined || pd.addressKind === undefined)
+        throw publicPositionsUnsupported(def);
+    if (opts.accountIndex !== undefined && def.id !== "lighter" && def.id !== "lighter-rh") {
+        throw new PerpError("INVALID_PARAMS", `--account-index applies to Lighter only (${def.id} has one account per address)`, { exchange: def.id, remediation: "Drop --account-index" });
+    }
+    return pd.fetchPositionsByAddress(net, requireAddressOfKind(def.id, pd.addressKind, address), opts);
+}
+/** Venues that read balances by public address (VenuePublicData.fetchBalanceByAddress). */
+export function listPublicBalanceVenues() {
+    return listVenues().filter(v => typeof v.publicData.fetchBalanceByAddress === "function" && v.publicData.addressKind !== undefined);
+}
+/** CAPABILITY_UNSUPPORTED for a venue without public-address balance reads (registry-derived). */
+export function publicBalanceUnsupported(def) {
+    const reason = !def.roles.includes("account")
+        ? `${def.displayName} is available for market data only (no account reads)`
+        : `${def.displayName} publishes balances only to the account itself (signed or API-key reads)`;
+    const supported = listPublicBalanceVenues().map(v => v.id).join(", ");
+    return new PerpError("CAPABILITY_UNSUPPORTED", `${def.id} does not support publicBalance — ${reason}`, {
+        venue: def.id, feature: "publicBalance", reason,
+        remediation: `Public-address reads: ${supported}; for your own account: perp -e ${def.id} portfolio`,
+    });
+}
+/**
+ * Balances of `address` on `venue`, keyless: unsupported venue → CAPABILITY_UNSUPPORTED, wrong
+ * address format → INVALID_PARAMS, both before any request.
+ */
+export async function fetchBalanceByAddress(venue, net, address, opts = {}) {
+    const def = getVenue(venue);
+    const pd = def.publicData;
+    if (pd.fetchBalanceByAddress === undefined || pd.addressKind === undefined)
+        throw publicBalanceUnsupported(def);
+    if (opts.accountIndex !== undefined && def.id !== "lighter" && def.id !== "lighter-rh") {
+        throw new PerpError("INVALID_PARAMS", `--account-index applies to Lighter only (${def.id} has one account per address)`, { exchange: def.id, remediation: "Drop --account-index" });
+    }
+    return pd.fetchBalanceByAddress(net, requireAddressOfKind(def.id, pd.addressKind, address), opts);
+}
 export function networkConfig(def, net) {
     const cfg = def.networks[net];
     if (!cfg) {
@@ -65,7 +140,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 +197,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 +223,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);
@@ -126,6 +235,19 @@ export function assertFundingArbVenue(ref) {
         remediation: `Use venues with verified funding (${listVenues().filter(v => v.fundingVerified && v.roles.includes("trading")).map(v => v.id).join(", ")}). ${def.displayName} rates can still be viewed: perp arb scan --rates --include-unverified`,
     });
 }
+/**
+ * Market rows (`market list|prices|info`, MCP get_markets) state whether their venue's funding rate
+ * is verified — on every venue, true or false (VenueDefinition.fundingVerified), so a consumer
+ * never has to read a missing field as "verified". A venue ref ("hip3:xyz" → hyperliquid) is
+ * resolved; an unknown ref leaves the rows as they are.
+ */
+export function withFundingVerified(venue, rows) {
+    const id = tryResolveVenueId(venue.startsWith("hip3:") ? "hyperliquid" : venue);
+    const def = id === null ? undefined : _venues.get(id);
+    if (def === undefined)
+        return rows;
+    return rows.map(r => ({ ...r, fundingVerified: def.fundingVerified }));
+}
 export function isLegacyVenue(def) {
     return def.id === "pacifica" || def.id === "hyperliquid" || def.id === "lighter" || def.id === "aster";
 }

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),
 };