perp-cli 0.14.2 → 0.15.0

package/dist/exchanges/variational/adapter.js

@@ -0,0 +1,137 @@
+/**
+ * Variational public-only adapter — OFFICIAL read-only API (venues/variational.ts).
+ *
+ * Markets, current funding terms and the OLP's indicative RFQ quotes come from the one stats
+ * payload (variational/public.ts). Variational is an RFQ venue with a single maker, so there is no
+ * order book, trade tape or candle feed in the API: getOrderbook / getRecentTrades / getKlines /
+ * getFundingHistory refuse with CAPABILITY_UNSUPPORTED (with the command that does work), and every
+ * account / trading method refuses before any request.
+ */
+import { unsupported } from "../trading-v2.js";
+import { roleUnsupported } from "../venue.js";
+import { rateToHourly } from "../venue-types.js";
+import { annualizeHourlyRate } from "../../funding/normalize.js";
+import { currentPerpRate, fetchVariationalListings, fundingBasisOf, resolveVariationalListing, } from "./public.js";
+const RFQ_NOTE = "Variational is an RFQ venue: the single market maker (OLP) quotes every trade. These are its INDICATIVE quotes at fixed notionals (may be cached up to 600 s), not order-book levels; the executed price is a firm quote at submit time.";
+export class VariationalPublicAdapter {
+    venue;
+    network;
+    name = "variational";
+    aliases = ["var", "omni"];
+    constructor(venue, network) {
+        this.venue = venue;
+        this.network = network;
+    }
+    warn(msg) {
+        process.stderr.write(`${msg}\n`);
+    }
+    async listing(symbol) {
+        return resolveVariationalListing(await fetchVariationalListings(this.network), symbol);
+    }
+    // ── Market data ──
+    async getMarkets() {
+        return (await fetchVariationalListings(this.network)).map(l => {
+            const rate = currentPerpRate(l, m => this.warn(m));
+            const f = l.funding;
+            return {
+                symbol: l.symbol,
+                markPrice: l.markPrice,
+                indexPrice: null,
+                fundingRate: rate,
+                volume24h: l.volume24h,
+                // Base-unit OI is not published (USD, single-sided only — see openInterestUsd).
+                openInterest: null,
+                maxLeverage: null,
+                sizeDecimals: null,
+                stepSize: null,
+                fundingHours: f === null ? null : f.intervalSeconds / 3600,
+                marginTiers: null,
+                venueApi: "official",
+                ticker: l.ticker,
+                contractType: l.contractType,
+                name: l.name,
+                fundingRateKind: rate === null ? null : "predicted",
+                nextFundingTime: f === null ? null : f.nextFundingTime,
+                openInterestUsd: { long: l.longOpenInterestUsd, short: l.shortOpenInterestUsd },
+                swapFunding: f !== null && f.kind === "swap" ? { last: f.last, next: f.next } : null,
+            };
+        });
+    }
+    /** Current funding terms of one market (the API publishes no funding history). */
+    async getFundingTerms(symbol) {
+        const l = await this.listing(symbol);
+        const f = l.funding;
+        const rate = currentPerpRate(l, m => this.warn(m));
+        const base = { kind: "currentFunding", venue: "variational", symbol: l.symbol, ticker: l.ticker, contractType: l.contractType };
+        if (f === null) {
+            return { ...base, rateKind: null, intervalRate: null, intervalHours: null, hourlyRate: null, annualizedPct: null, venueAnnualizedRate: null, nextFundingTime: null, swap: null, note: "Variational publishes no funding terms for this market right now" };
+        }
+        const intervalHours = f.intervalSeconds / 3600;
+        if (f.kind === "swap") {
+            return {
+                ...base, rateKind: null, intervalRate: null, intervalHours, hourlyRate: null, annualizedPct: null, venueAnnualizedRate: null,
+                nextFundingTime: f.nextFundingTime, swap: { last: f.last, next: f.next },
+                note: "Swap: separate long / short rates paid once per trading day (positive long rate = longs pay, positive short rate = shorts receive); no single funding rate",
+            };
+        }
+        const hourlyRate = rate === null ? null : rateToHourly(Number(rate), fundingBasisOf(f));
+        return {
+            ...base,
+            rateKind: rate === null ? null : "predicted",
+            intervalRate: rate,
+            intervalHours,
+            hourlyRate,
+            annualizedPct: hourlyRate === null ? null : annualizeHourlyRate(hourlyRate),
+            venueAnnualizedRate: f.last.annualized,
+            nextFundingTime: f.nextFundingTime,
+            swap: null,
+            note: rate === null
+                ? "The published interval and annualized rates disagree; funding is not shown"
+                : `Current (predicted) rate for the ${intervalHours}h window ending at nextFundingTime; positive = longs pay. Variational publishes no funding history`,
+        };
+    }
+    /** The OLP's indicative RFQ quotes (Variational has no order book). */
+    async getRfqQuotes(symbol) {
+        const l = await this.listing(symbol);
+        return {
+            kind: "rfqQuotes",
+            venue: "variational",
+            symbol: l.symbol,
+            ticker: l.ticker,
+            markPrice: l.markPrice,
+            updatedAt: l.quotes === null ? null : l.quotes.updatedAt,
+            baseSpreadBps: l.baseSpreadBps,
+            quotes: l.quotes === null ? [] : l.quotes.tiers,
+            note: RFQ_NOTE,
+        };
+    }
+    async getOrderbook() {
+        throw unsupported("variational", "orderbook", "Variational is an RFQ venue with a single market maker (OLP); there is no order book", "See the OLP's indicative RFQ quotes at fixed notionals: perp -e variational market book <symbol>");
+    }
+    async getRecentTrades() {
+        throw unsupported("variational", "recentTrades", "Variational's public API publishes no trade tape", "Market stats (24h volume, open interest): perp -e variational market info <symbol>");
+    }
+    async getFundingHistory() {
+        throw unsupported("variational", "fundingHistory", "Variational's public API publishes no funding history", "Current funding terms: perp -e variational market funding <symbol>, or perp arb scan --rates");
+    }
+    async getKlines() {
+        throw unsupported("variational", "klines", "Variational's public API publishes no candles", "Current mark price: perp -e variational market info <symbol>");
+    }
+    // ── Account / trading: refused (market-data-only venue, no public trading API) ──
+    refuse(feature) {
+        throw roleUnsupported(this.venue, feature);
+    }
+    async getBalance() { return this.refuse("account"); }
+    async getPositions() { return this.refuse("account"); }
+    async getOpenOrders() { return this.refuse("account"); }
+    async getOrderHistory() { return this.refuse("account"); }
+    async getTradeHistory() { return this.refuse("account"); }
+    async getFundingPayments() { return this.refuse("account"); }
+    async marketOrder() { return this.refuse("trading"); }
+    async limitOrder() { return this.refuse("trading"); }
+    async editOrder() { return this.refuse("trading"); }
+    async cancelOrder() { return this.refuse("trading"); }
+    async cancelAllOrders() { return this.refuse("trading"); }
+    async setLeverage() { return this.refuse("trading"); }
+    async stopOrder() { return this.refuse("trading"); }
+}

package/dist/exchanges/variational/client.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Variational transport — the OFFICIAL read-only API (docs.variational.io/technical-documentation/api).
+ *
+ * One endpoint, `GET <rest>/metadata/v2/stats`, serves every market. Limits (documented): 10
+ * requests / 10 s per IP, 1000 / min globally, shared with the legacy v1 endpoint; over the limit
+ * the venue answers HTTP 429 with a JSON body whose `retry_after_seconds` says when to retry.
+ * Every request first takes a token from the per-process limiter (venue rateLimit policy).
+ */
+import { PerpError } from "../../errors.js";
+import type { RateLimitPolicy } from "../venue.js";
+export declare const VARIATIONAL_HTTP_TIMEOUT_MS = 15000;
+export declare const VARIATIONAL_STATS_PATH = "/metadata/v2/stats";
+/** Payload drift in the documented API: an explicit EXCHANGE_ERROR, never a guessed value. */
+export declare function variationalShapeError(what: string): PerpError;
+export declare class VariationalClient {
+    private readonly restUrl;
+    private readonly rateLimit;
+    constructor(restUrl: string, rateLimit: RateLimitPolicy);
+    /** GET /metadata/v2/stats. Returns the parsed body; every error path is a PerpError. */
+    stats(): Promise<unknown>;
+}

package/dist/exchanges/variational/client.js

@@ -0,0 +1,66 @@
+/**
+ * Variational transport — the OFFICIAL read-only API (docs.variational.io/technical-documentation/api).
+ *
+ * One endpoint, `GET <rest>/metadata/v2/stats`, serves every market. Limits (documented): 10
+ * requests / 10 s per IP, 1000 / min globally, shared with the legacy v1 endpoint; over the limit
+ * the venue answers HTTP 429 with a JSON body whose `retry_after_seconds` says when to retry.
+ * Every request first takes a token from the per-process limiter (venue rateLimit policy).
+ */
+import { PerpError, extractErrorMessage } from "../../errors.js";
+import { acquireRate, rateLimitedError } from "../rate-limiter.js";
+export const VARIATIONAL_HTTP_TIMEOUT_MS = 15_000;
+export const VARIATIONAL_STATS_PATH = "/metadata/v2/stats";
+/** Payload drift in the documented API: an explicit EXCHANGE_ERROR, never a guessed value. */
+export function variationalShapeError(what) {
+    return new PerpError("EXCHANGE_ERROR", `Variational ${VARIATIONAL_STATS_PATH} shape changed: ${what}`, {
+        exchange: "variational",
+        remediation: "Variational's stats payload no longer matches its documentation (docs.variational.io/technical-documentation/api); perp-cli needs an update to read it",
+    });
+}
+/** `retry_after_seconds` from a 429 body (documented), else the Retry-After header. */
+function retryAfterOf(res, parsed) {
+    const v = parsed?.retry_after_seconds;
+    if (typeof v === "number" && Number.isFinite(v))
+        return String(v);
+    return res.headers.get("retry-after");
+}
+export class VariationalClient {
+    restUrl;
+    rateLimit;
+    constructor(restUrl, rateLimit) {
+        this.restUrl = restUrl;
+        this.rateLimit = rateLimit;
+    }
+    /** GET /metadata/v2/stats. Returns the parsed body; every error path is a PerpError. */
+    async stats() {
+        await acquireRate("variational", this.rateLimit, VARIATIONAL_STATS_PATH);
+        let res;
+        try {
+            res = await fetch(`${this.restUrl}${VARIATIONAL_STATS_PATH}`, { signal: AbortSignal.timeout(VARIATIONAL_HTTP_TIMEOUT_MS) });
+        }
+        catch (e) {
+            throw new PerpError("EXCHANGE_UNREACHABLE", `Variational stats: ${extractErrorMessage(e)}`, { exchange: "variational" });
+        }
+        const text = await res.text().catch((e) => {
+            throw new PerpError("EXCHANGE_UNREACHABLE", `Variational stats: response body unreadable (${extractErrorMessage(e)})`, { exchange: "variational" });
+        });
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (res.status === 429)
+            throw rateLimitedError("variational", retryAfterOf(res, parsed), text);
+        if (!res.ok) {
+            throw new PerpError("EXCHANGE_ERROR", `Variational stats: HTTP ${res.status} ${text.slice(0, 200)}`, {
+                exchange: "variational", status: res.status,
+                remediation: "Variational's public stats API answered with an error; retry later",
+            });
+        }
+        if (parsed === undefined)
+            throw variationalShapeError("response is not JSON");
+        return parsed;
+    }
+}

package/dist/exchanges/variational/public.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Variational public market data — the OFFICIAL read-only API (venues/variational.ts).
+ *
+ * Source: `GET /metadata/v2/stats` (docs.variational.io/technical-documentation/api). One call
+ * returns every listing; it is shared by every reader for VARIATIONAL_STATS_TTL_MS through the
+ * file cache (cache.ts, cross-process, raw JSON body only) plus an in-process in-flight promise,
+ * so `market list` + `arb scan` + `perp health` inside the window cost ONE request.
+ *
+ * Listings (575 on 2026-10-19: 557 perpetuals, 18 swaps):
+ *  - ticker "BTC-PERP" / "XAU-SWAP", contract_type "perpetual" | "swap". Perp display symbol =
+ *    the base ("BTC"); a swap keeps its suffix ("XAU-SWAP") so it never collides with "XAU" perp.
+ *  - mark_price, volume_24h (USDC), open_interest.{long,short}_open_interest (USDC, single-sided:
+ *    trader positions only — the OLP is the other side). Base-unit OI is NOT published, so the
+ *    legacy openInterest (base units) is null; the USD figures are carried separately.
+ *  - quotes.{base,size_1k,size_100k,size_1m}.{bid,ask}: the OLP's INDICATIVE RFQ quotes at fixed
+ *    notionals (may be cached up to 600 s; quotes.updated_at). Omitted while a market is closed.
+ *
+ * Funding (docs.variational.io/omni/trading/funding-rates):
+ *  - perpetual: funding.last.interval_rate is a decimal fraction for ONE interval_seconds window
+ *    (1h / 4h / 8h, per market), positive = longs pay. annualized_rate is the same rate × 365 d /
+ *    interval — the identity is checked per row; a row that breaks it gets no rate (warned).
+ *  - rateKind "predicted": `last` is recomputed during the window (live samples 2026-10-19: 175
+ *    of 557 perps changed within 2 min under the same next_timestamp) and `next` ("predicted
+ *    funding rate for the next interval") equals it. It is the rate the OLP will charge at
+ *    next_timestamp, not a settled print.
+ *  - swap: separate long / short rates paid once per trading day — there is no single funding
+ *    rate, so fundingRate is null and swaps are never matched across venues (canonical null);
+ *    the long / short rates are shown on the Variational rows only.
+ */
+import { type VenuePublicData } from "../venue.js";
+import type { AssetClass, FundingRateBasis, Network, VenueFundingRate, VenueMarket } from "../venue-types.js";
+import type { SwapFundingRates } from "../interface.js";
+/** How long one stats payload serves every reader (the venue itself sends max-age=30). */
+export declare const VARIATIONAL_STATS_TTL_MS = 5000;
+/**
+ * Hint for a cross-venue lookup by a Variational ticker whose canonical symbol differs (arb scan
+ * --compare US500): where it is compared instead, or that it is never matched. null = no override.
+ */
+export declare function canonicalHintFor(symbol: string): string | null;
+export declare function looksTradFi(name: string | null): boolean;
+export declare function warnOnce(warn: (msg: string) => void, msg: string): void;
+export type QuoteTier = "base" | "size_1k" | "size_100k" | "size_1m";
+export declare const QUOTE_TIERS: readonly QuoteTier[];
+/** USD notional of each quote tier; "base" = the market's minimum order size (notional not published). */
+export declare const QUOTE_TIER_NOTIONAL_USD: Readonly<Record<QuoteTier, string | null>>;
+export interface VariationalQuote {
+    tier: QuoteTier;
+    notionalUsd: string | null;
+    bid: string;
+    ask: string;
+}
+export interface VariationalQuotes {
+    updatedAt: string;
+    tiers: VariationalQuote[];
+}
+export interface VariationalPerpRate {
+    annualized: string;
+    interval: string;
+}
+export type VariationalSwapRate = SwapFundingRates;
+export type VariationalFunding = {
+    kind: "perpetual";
+    intervalSeconds: number;
+    nextFundingTime: number | null;
+    last: VariationalPerpRate;
+    next: VariationalPerpRate | null;
+} | {
+    kind: "swap";
+    intervalSeconds: number;
+    nextFundingTime: number | null;
+    last: VariationalSwapRate | null;
+    next: VariationalSwapRate | null;
+};
+export interface VariationalListing {
+    ticker: string;
+    contractType: "perpetual" | "swap";
+    /** Display symbol: "BTC" for BTC-PERP, "XAU-SWAP" for a swap. */
+    symbol: string;
+    base: string;
+    name: string | null;
+    markPrice: string;
+    volume24h: string;
+    longOpenInterestUsd: string;
+    shortOpenInterestUsd: string;
+    funding: VariationalFunding | null;
+    baseSpreadBps: string | null;
+    quotes: VariationalQuotes | null;
+    assetClass: AssetClass;
+    canonical: string | null;
+}
+/**
+ * Parse the stats payload. A non-object payload / missing listings array is EXCHANGE_ERROR; a
+ * single malformed or unclassifiable listing is dropped with a warning naming it (never guessed).
+ */
+export declare function parseVariationalStats(body: unknown, warn: (msg: string) => void): VariationalListing[];
+/** interval_rate agrees with annualized_rate × interval / 365 d (both published, both rounded). */
+export declare function perpRateConsistent(rate: VariationalPerpRate, intervalSeconds: number): boolean;
+/** Basis of one perp's interval_rate: perHours(interval_seconds / 3600). */
+export declare function fundingBasisOf(f: VariationalFunding): FundingRateBasis;
+/**
+ * The current (predicted) funding rate per interval, or null: swaps (no single rate), no funding
+ * terms, or a perp whose two published representations disagree (unit drift — warned).
+ */
+export declare function currentPerpRate(l: VariationalListing, warn: (msg: string) => void): string | null;
+export interface VariationalPublicDeps {
+    stats: (net: Network) => Promise<unknown>;
+    cache: {
+        get: (key: string) => unknown;
+        set: (key: string, value: unknown, ttlMs: number) => void;
+    };
+    warn: (msg: string) => void;
+}
+export declare const statsCacheKey: (net: Network) => string;
+/**
+ * The raw stats body: from the cache when fresh, else ONE request shared by every concurrent
+ * caller in this process. Only the raw JSON body is cached (JSON-safe); parsing runs per read.
+ */
+export declare function fetchVariationalStatsRaw(net: Network, deps?: VariationalPublicDeps): Promise<unknown>;
+export declare function fetchVariationalListings(net: Network, deps?: VariationalPublicDeps): Promise<VariationalListing[]>;
+/** null when the listing has no funding terms (its interval — part of VenueMarket — is unknown). */
+export declare function toVariationalVenueMarket(l: VariationalListing, warn: (msg: string) => void): VenueMarket | null;
+export declare function fetchVariationalMarkets(net: Network, deps?: VariationalPublicDeps): Promise<VenueMarket[]>;
+export declare function fetchVariationalFundingRates(net: Network, deps?: VariationalPublicDeps): Promise<VenueFundingRate[]>;
+export declare const variationalPublicData: VenuePublicData;
+/** Resolve a CLI symbol ("btc", "BTC-PERP", "xau-swap") against the parsed listings. */
+export declare function resolveVariationalListing(listings: readonly VariationalListing[], input: string): VariationalListing;