perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/grvt/adapter.js

@@ -0,0 +1,283 @@
+/**
+ * GRVT public-only adapter — official Market Data API, read-only in this version (venues/grvt.ts).
+ *
+ * Market data (markets, orderbook, trades, funding history, klines) is implemented. Every account /
+ * trading method refuses with CAPABILITY_UNSUPPORTED before any request — there is no GRVT account,
+ * signing or order code. Unknown symbols are SYMBOL_NOT_FOUND from the instrument directory (GRVT
+ * answers an unknown instrument with HTTP 400 "malformed syntax", so it is never asked).
+ */
+import { PerpError } from "../../errors.js";
+import { mulDecimal } from "../precision.js";
+import { roleUnsupported } from "../venue.js";
+import { grvtShapeError } from "./client.js";
+import { fetchGrvtMarket, fetchGrvtMarkets, grvtClient, grvtDirectory, resolveGrvtMarket, } from "./public.js";
+/** perp-cli interval → GRVT CandlestickInterval (api-docs.grvt.io/schemas/candlestick_interval). */
+export const GRVT_KLINE_INTERVALS = {
+    "1m": "CI_1_M", "3m": "CI_3_M", "5m": "CI_5_M", "15m": "CI_15_M", "30m": "CI_30_M",
+    "1h": "CI_1_H", "2h": "CI_2_H", "4h": "CI_4_H", "6h": "CI_6_H", "8h": "CI_8_H", "12h": "CI_12_H",
+    "1d": "CI_1_D", "3d": "CI_3_D", "5d": "CI_5_D", "1w": "CI_1_W", "2w": "CI_2_W", "3w": "CI_3_W", "4w": "CI_4_W",
+};
+/** Fixed-length intervals (ms): `start_time` is floored to their boundary (epoch-aligned, UTC). */
+const GRVT_KLINE_FIXED_MS = {
+    "1m": 60_000, "3m": 180_000, "5m": 300_000, "15m": 900_000, "30m": 1_800_000, "1h": 3_600_000, "2h": 7_200_000,
+    "4h": 14_400_000, "6h": 21_600_000, "8h": 28_800_000, "12h": 43_200_000, "1d": 86_400_000,
+};
+const GRVT_KLINE_NOMINAL_MS = {
+    ...GRVT_KLINE_FIXED_MS, "3d": 259_200_000, "5d": 432_000_000, "1w": 604_800_000, "2w": 1_209_600_000, "3w": 1_814_400_000, "4w": 2_419_200_000,
+};
+/**
+ * Bars per kline page (the documented max) and the most pages one read may take. The `next`
+ * cursor runs dry after ~1000 bars (live 2026-10-19: page 2 had 2 rows and `next` ""), so pages
+ * walk `end_time` back to just before the oldest bar returned instead.
+ */
+export const GRVT_KLINE_PAGE = 1000;
+/**
+ * Pages actually read before giving up. Real pages hold fewer than 1000 bars (minutes without a
+ * bar: 40 d of 1m took 58 pages for 57,583 bars), so the read budget is 25 % above the nominal
+ * GRVT_KLINE_MAX_PAGES. 75 requests stay well inside GRVT's 500 market-data requests / minute.
+ */
+export const GRVT_KLINE_READ_PAGES = 75;
+/** Measured live 2026-10-19: /trade answers at most 1000 rows (limit 1500 → 1000, no cursor). */
+export const GRVT_TRADES_CAP = 1000;
+/** Measured live 2026-10-19: /funding honours limit 10,000 in one answer (BTC). */
+export const GRVT_FUNDING_CAP = 10_000;
+export const GRVT_KLINE_MAX_PAGES = 60;
+const WARN = (msg) => { process.stderr.write(`${msg}\n`); };
+/** Order book depths GRVT serves (api_orderbook_levels_request). */
+export const GRVT_BOOK_DEPTHS = [10, 50, 100, 500];
+const DEC = /^-?\d+(\.\d+)?$/;
+function dec(v, what) {
+    if (typeof v !== "string" || !DEC.test(v))
+        throw grvtShapeError(`${what} is not a decimal string`);
+    return v;
+}
+function nsToMs(v, what) {
+    if (typeof v !== "string" || !/^\d+$/.test(v))
+        throw grvtShapeError(`${what} is not a nanosecond timestamp`);
+    return Number(BigInt(v) / 1000000n);
+}
+function msToNs(ms) {
+    return (BigInt(Math.floor(ms)) * 1000000n).toString();
+}
+export function toGrvtMarketInfo(m) {
+    return {
+        symbol: m.symbol,
+        markPrice: m.markPrice,
+        indexPrice: m.indexPrice,
+        fundingRate: m.fundingRate,
+        volume24h: m.volume24h,
+        openInterest: m.openInterest,
+        maxLeverage: m.maxLeverage,
+        sizeDecimals: null,
+        stepSize: m.stepSize,
+        fundingHours: m.settlementIntervalHours,
+        marginTiers: m.marginTiers,
+        venueSymbol: m.venueSymbol,
+        lastPrice: m.lastPrice,
+        bestBid: m.bestBid,
+        bestAsk: m.bestAsk,
+        tickSize: m.tickSize,
+        leverageAsOf: m.leverageAsOf,
+        minSize: m.minSize,
+        minNotional: m.minNotional,
+        nextFundingTime: m.nextFundingTime,
+        fundingRateKind: "predicted",
+        fundingVerified: false,
+    };
+}
+export class GrvtPublicAdapter {
+    venue;
+    network;
+    name = "grvt";
+    aliases = ["grv"];
+    client;
+    constructor(venue, network) {
+        this.venue = venue;
+        this.network = network;
+        this.client = grvtClient(network);
+    }
+    async market(symbol) {
+        return resolveGrvtMarket(await grvtDirectory(this.client, this.network, WARN), symbol);
+    }
+    // ── Market data ──
+    /** Every market with leverage (`market list`): margin_rules come from the 6 h file cache. */
+    async getVenueMarkets() {
+        return fetchGrvtMarkets(this.network, { leverage: true });
+    }
+    async getMarkets() {
+        return (await this.getVenueMarkets()).map(toGrvtMarketInfo);
+    }
+    /** One market (`market info`): the directory, its ticker and its margin rules — no fan-out. */
+    async getMarketInfo(symbol) {
+        return toGrvtMarketInfo(await fetchGrvtMarket(this.network, symbol));
+    }
+    async getOrderbook(symbol, depth = 50) {
+        const m = await this.market(symbol);
+        // The smallest served depth that covers the request; above 500 → INVALID_PARAMS (never clamped).
+        const d = GRVT_BOOK_DEPTHS.find(x => x >= depth);
+        if (d === undefined || !Number.isInteger(depth) || depth < 1) {
+            throw new PerpError("INVALID_PARAMS", `GRVT: book depth must be 1..500 (got ${depth})`, { exchange: "grvt", remediation: "Pass --depth 1..500" });
+        }
+        const res = await this.client.result("book", { instrument: m.instrument, depth: d });
+        if (res === null || typeof res !== "object" || !Array.isArray(res.bids) || !Array.isArray(res.asks)) {
+            throw grvtShapeError("book has no bids / asks arrays");
+        }
+        const side = (rows, what) => rows.map(r => {
+            const x = r;
+            return [dec(x.price, `${what} price`), dec(x.size, `${what} size`)];
+        });
+        // GRVT serves 10 / 50 / 100 / 500 levels: return exactly the `depth` requested.
+        return { bids: side(res.bids.slice(0, depth), "bid"), asks: side(res.asks.slice(0, depth), "ask") };
+    }
+    async getRecentTrades(symbol, limit = 50) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > GRVT_TRADES_CAP) {
+            throw new PerpError("INVALID_PARAMS", `GRVT: trades limit must be 1..${GRVT_TRADES_CAP} (got ${limit})`, {
+                remediation: `GRVT serves at most ${GRVT_TRADES_CAP} recent trades per request and no cursor for older ones`,
+            });
+        }
+        const m = await this.market(symbol);
+        const res = await this.client.result("trade", { instrument: m.instrument, limit });
+        if (!Array.isArray(res))
+            throw grvtShapeError("trade result is not an array");
+        // The venue answers oldest first; every venue's tape is newest first.
+        return res.map(t => {
+            const x = t;
+            if (typeof x.is_taker_buyer !== "boolean")
+                throw grvtShapeError("trade without is_taker_buyer");
+            return {
+                time: nsToMs(x.event_time, "trade event_time"),
+                symbol: m.symbol,
+                side: x.is_taker_buyer ? "buy" : "sell",
+                price: dec(x.price, "trade price"),
+                size: dec(x.size, "trade size"),
+                fee: null,
+            };
+        }).sort((a, b) => b.time - a.time);
+    }
+    /**
+     * Settled funding (/full/v1/funding, one record per funding interval, newest first). `rate` is a
+     * fraction per the record's `intervalHours` (published in percentage points, converted exactly).
+     */
+    async getFundingHistory(symbol, limit = 100) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > GRVT_FUNDING_CAP) {
+            throw new PerpError("INVALID_PARAMS", `GRVT: funding history limit must be 1..${GRVT_FUNDING_CAP} (got ${limit})`);
+        }
+        const m = await this.market(symbol);
+        // Sent as asked (it was silently clamped to 1000; the venue serves 10,000 in one answer).
+        const res = await this.client.result("funding", { instrument: m.instrument, limit });
+        if (!Array.isArray(res))
+            throw grvtShapeError("funding result is not an array");
+        return res.map(r => {
+            const x = r;
+            const fi = x.funding_interval_hours;
+            if (typeof fi !== "number" || !Number.isInteger(fi) || fi <= 0)
+                throw grvtShapeError("funding record without funding_interval_hours");
+            const mark = typeof x.mark_price === "string" && DEC.test(x.mark_price) && Number(x.mark_price) > 0 ? x.mark_price : null;
+            return {
+                time: nsToMs(x.funding_time, "funding_time"),
+                rate: mulDecimal(dec(x.funding_rate, "funding_rate"), "0.01"),
+                price: mark,
+                intervalHours: fi,
+                rateKind: "lastSettled",
+            };
+        });
+    }
+    async getKlines(symbol, interval, startTime, endTime) {
+        const ci = GRVT_KLINE_INTERVALS[interval];
+        if (ci === undefined) {
+            throw new PerpError("INVALID_PARAMS", `GRVT: unsupported candle interval "${interval}"`, {
+                remediation: `Use one of: ${Object.keys(GRVT_KLINE_INTERVALS).join(", ")}`,
+            });
+        }
+        if (!(endTime > startTime))
+            throw new PerpError("INVALID_PARAMS", "GRVT: candle end time must be after the start time");
+        const fixed = GRVT_KLINE_FIXED_MS[interval];
+        // An off-grid start_time makes GRVT answer a truncated first bar labelled off the grid
+        // (live: 4h from 05:07 → a 06:00–08:00 bar), so the start is floored to the boundary.
+        const start = fixed === undefined ? startTime : Math.floor(startTime / fixed) * fixed;
+        const pagesNeeded = Math.ceil((endTime - start) / GRVT_KLINE_NOMINAL_MS[interval] / GRVT_KLINE_PAGE);
+        if (pagesNeeded > GRVT_KLINE_MAX_PAGES) {
+            throw new PerpError("INVALID_PARAMS", `GRVT: ${interval} candles over this range need ${pagesNeeded} requests (max ${GRVT_KLINE_MAX_PAGES})`, {
+                remediation: "Narrow --start / --end or use a longer interval",
+            });
+        }
+        const m = await this.market(symbol);
+        // Reverse-chronological pages of up to 1000 bars; the next page ends just before the oldest
+        // bar returned. Done when a page is empty or reaches `start` — never on the cursor alone.
+        const byOpen = new Map();
+        let end = endTime;
+        let oldestSeen = Infinity;
+        let exhausted = false;
+        for (let page = 0; page < GRVT_KLINE_READ_PAGES; page++) {
+            const res = await this.client.post("kline", {
+                instrument: m.instrument, interval: ci, type: "TRADE", start_time: msToNs(start), end_time: msToNs(end), limit: GRVT_KLINE_PAGE,
+            });
+            if (res === null || typeof res !== "object" || !Array.isArray(res.result))
+                throw grvtShapeError("kline result is not an array");
+            // A fixed-interval bar whose first minute had no trade is labelled at its first trade (live
+            // 2026-10-19: the 09:30–10:00 30m bar opened "09:31"); its open is the bucket boundary, and a
+            // page asked to end before that label answers the same bar again — it is not an older bar.
+            const inPage = res.result
+                .map(c => ({ c, t: fixed === undefined ? nsToMs(c.open_time, "kline open_time") : Math.floor(nsToMs(c.open_time, "kline open_time") / fixed) * fixed }))
+                .filter(x => page === 0 || x.t < oldestSeen);
+            // No bar older than the last page (an empty page, or only bars already read): history starts here.
+            if (inPage.length === 0) {
+                exhausted = true;
+                break;
+            }
+            let oldest = Infinity;
+            for (const { c, t } of inPage) {
+                byOpen.set(String(t), { ...c, open_time: `${t}000000` });
+                if (t < oldest)
+                    oldest = t;
+            }
+            oldestSeen = oldest;
+            if (oldest <= start)
+                break;
+            end = oldest - 1;
+        }
+        // Ran out of the read budget before reaching `start`: the oldest bars would be missing — never
+        // returned as the whole range.
+        if (!exhausted && oldestSeen > start) {
+            throw new PerpError("EXCHANGE_ERROR", `GRVT: ${interval} candles reached only ${new Date(oldestSeen).toISOString()} after ${GRVT_KLINE_READ_PAGES} pages (requested from ${new Date(start).toISOString()})`, {
+                exchange: "grvt", reachedMs: oldestSeen, requestedFromMs: start,
+                remediation: `Narrow --start / --end (or use a longer interval); fetch older bars with --end ${oldestSeen - 1}`,
+            });
+        }
+        const rows = [...byOpen.values()];
+        const bars = rows.map(c => {
+            const x = c;
+            return {
+                time: nsToMs(x.open_time, "kline open_time"),
+                open: dec(x.open, "kline open"), high: dec(x.high, "kline high"), low: dec(x.low, "kline low"), close: dec(x.close, "kline close"),
+                volume: dec(x.volume_b, "kline volume_b"),
+                quoteVolume: typeof x.volume_q === "string" && DEC.test(x.volume_q) ? x.volume_q : null,
+                trades: typeof x.trades === "number" ? x.trades : null,
+                closeMs: nsToMs(x.close_time, "kline close_time"),
+            };
+        }).sort((a, b) => a.time - b.time);
+        // Calendar intervals (3d … 4w) are not floored: a first bar shorter than the interval is a
+        // truncated bar (live: the first 1w bar covered 4 days) and is left out. The newest bar may be
+        // in progress and is kept.
+        const nominal = GRVT_KLINE_NOMINAL_MS[interval];
+        const full = fixed === undefined && bars.length > 1 && bars[0].closeMs - bars[0].time + 1 < nominal * 0.99 ? bars.slice(1) : bars;
+        return full.map(({ closeMs: _c, ...k }) => k);
+    }
+    // ── Account / trading: refused (read-only in this version) ──
+    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/grvt/client.d.ts

@@ -0,0 +1,25 @@
+/**
+ * GRVT Market Data REST transport (official API, api-docs.grvt.io/market_data_api/).
+ *
+ *  - `POST <rest>/full/v1/<endpoint>` with a JSON body; success is `{result: …}` (`margin_rules`
+ *    answers its object unwrapped), an error is `{code, message, status}` with the HTTP status
+ *    (1003/400 malformed — also what an unknown instrument gets —, 1004/404 not found, 1006/429
+ *    rate limit, 1002/500 internal).
+ *  - Rate limits (help.grvt.io): Ticker / MiniTicker / GetInstrument 1500 per minute, everything
+ *    else 500 per minute — two token buckets per network (venues/grvt.ts).
+ *  - No retries, no fallback: every failure is a PerpError.
+ */
+import { PerpError } from "../../errors.js";
+import type { Network } from "../venue-types.js";
+export declare const GRVT_HTTP_TIMEOUT_MS = 15000;
+/** Response of an unexpected shape: an explicit EXCHANGE_ERROR, never a guessed value. */
+export declare function grvtShapeError(what: string): PerpError;
+export declare class GrvtClient {
+    private readonly restUrl;
+    private readonly network;
+    constructor(restUrl: string, network: Network);
+    /** POST /full/v1/<endpoint>. Returns the parsed body; every error path is a PerpError. */
+    post<T = unknown>(endpoint: string, body: Record<string, unknown>): Promise<T>;
+    /** POST and unwrap `{result}` (every market-data endpoint except margin_rules). */
+    result<T = unknown>(endpoint: string, body: Record<string, unknown>): Promise<T>;
+}

package/dist/exchanges/grvt/client.js

@@ -0,0 +1,86 @@
+/**
+ * GRVT Market Data REST transport (official API, api-docs.grvt.io/market_data_api/).
+ *
+ *  - `POST <rest>/full/v1/<endpoint>` with a JSON body; success is `{result: …}` (`margin_rules`
+ *    answers its object unwrapped), an error is `{code, message, status}` with the HTTP status
+ *    (1003/400 malformed — also what an unknown instrument gets —, 1004/404 not found, 1006/429
+ *    rate limit, 1002/500 internal).
+ *  - Rate limits (help.grvt.io): Ticker / MiniTicker / GetInstrument 1500 per minute, everything
+ *    else 500 per minute — two token buckets per network (venues/grvt.ts).
+ *  - No retries, no fallback: every failure is a PerpError.
+ */
+import { PerpError, extractErrorMessage } from "../../errors.js";
+import { acquireRate, rateLimitedError } from "../rate-limiter.js";
+import { GRVT_OTHER_RATE_LIMIT, GRVT_TICKER_RATE_LIMIT } from "../venues/grvt.js";
+export const GRVT_HTTP_TIMEOUT_MS = 15_000;
+/** Endpoints in the 1500 / min bucket. */
+const TICKER_BUCKET = new Set(["ticker", "mini", "instrument"]);
+/** Response of an unexpected shape: an explicit EXCHANGE_ERROR, never a guessed value. */
+export function grvtShapeError(what) {
+    return new PerpError("EXCHANGE_ERROR", `GRVT market data: unexpected response — ${what}`, {
+        exchange: "grvt",
+        remediation: "GRVT's market-data response did not match its documented schema (api-docs.grvt.io); perp-cli needs an update to read it",
+    });
+}
+function errorBodyOf(parsed) {
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const p = parsed;
+    if (typeof p.message !== "string")
+        return null;
+    return { code: typeof p.code === "number" ? p.code : null, message: p.message };
+}
+export class GrvtClient {
+    restUrl;
+    network;
+    constructor(restUrl, network) {
+        this.restUrl = restUrl;
+        this.network = network;
+    }
+    /** POST /full/v1/<endpoint>. Returns the parsed body; every error path is a PerpError. */
+    async post(endpoint, body) {
+        const ticker = TICKER_BUCKET.has(endpoint);
+        await acquireRate(`grvt:${ticker ? "ticker" : "other"}:${this.network}`, ticker ? GRVT_TICKER_RATE_LIMIT : GRVT_OTHER_RATE_LIMIT, endpoint);
+        let res;
+        try {
+            res = await fetch(`${this.restUrl}/full/v1/${endpoint}`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(GRVT_HTTP_TIMEOUT_MS),
+            });
+        }
+        catch (e) {
+            throw new PerpError("EXCHANGE_UNREACHABLE", `GRVT ${endpoint}: ${extractErrorMessage(e)}`, { exchange: "grvt" });
+        }
+        const text = await res.text().catch((e) => {
+            throw new PerpError("EXCHANGE_UNREACHABLE", `GRVT ${endpoint}: response body unreadable (${extractErrorMessage(e)})`, { exchange: "grvt" });
+        });
+        if (res.status === 429)
+            throw rateLimitedError("grvt", res.headers.get("retry-after"), text);
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (!res.ok) {
+            const err = errorBodyOf(parsed);
+            const msg = err !== null ? `${err.code ?? "?"} ${err.message}` : text.slice(0, 200);
+            throw new PerpError(res.status >= 500 ? "EXCHANGE_UNREACHABLE" : "EXCHANGE_ERROR", `GRVT ${endpoint}: HTTP ${res.status} ${msg}`, {
+                exchange: "grvt", status: res.status,
+            });
+        }
+        if (parsed === undefined)
+            throw grvtShapeError(`${endpoint} returned a non-JSON body`);
+        return parsed;
+    }
+    /** POST and unwrap `{result}` (every market-data endpoint except margin_rules). */
+    async result(endpoint, body) {
+        const res = await this.post(endpoint, body);
+        if (res === null || typeof res !== "object" || !("result" in res))
+            throw grvtShapeError(`${endpoint} has no result`);
+        return res.result;
+    }
+}

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

@@ -0,0 +1,151 @@
+/**
+ * GRVT public market data — official Market Data REST API (api-docs.grvt.io/market_data_api/).
+ *
+ * Sources (all `POST https://market-data.grvt.io/full/v1/…`, no key):
+ *   instruments {kind:["PERPETUAL"], is_active:true, limit}  directory: instrument "BTC_USDT_Perp",
+ *        base, quote, kind, settlement_period, tick_size, min_size, min_notional,
+ *        funding_interval_hours (4 or 8, PER INSTRUMENT), asset_class (CRYPTO / EQUITY / COMMODITY),
+ *        status. No leverage and no lot step (base_decimals is the signing multiplier, not a lot).
+ *   ticker {instrument}       one instrument per call (no bulk ticker exists): mark / index / last /
+ *        best bid / best ask prices, open_interest (base), buy/sell_volume_24h_q (quote = USDT),
+ *        funding_rate, next_funding_time (ns).
+ *   margin_rules {instrument} risk_brackets → max_leverage of tier 1 (= maxLeverage) and the tiers.
+ *
+ * Mapping:
+ *  - symbol = `base` ("BTC", "KPEPE"); venueSymbol = instrument ("BTC_USDT_Perp"); canonical via
+ *    canonical-symbols.ts (crypto by ticker + denomination aliases, equity / etf by ticker,
+ *    commodity explicit only). Pre-IPO markets (listed by GRVT as EQUITY) are preIpo → no canonical.
+ *  - funding: `funding_rate` is the venue's INDICATIVE rate for the active interval (the interval
+ *    ending at next_funding_time) — kind "predicted", a moving estimate. Its unit is PERCENT per the
+ *    market's funding interval: settled history (/full/v1/funding, "percentage points") prints the
+ *    same magnitude (BTC 0.01 = HL-style 0.01 %/8 h baseline; ticker 0.0063). The ticker schema says
+ *    "centibeeps", which would make every rate 100× smaller than its own settled prints — not used.
+ *    Converted to a fraction per interval by an exact × 0.01; basis perHours = funding_interval_hours.
+ *  - volume24h = buy + sell 24 h quote volume (the docs' "24 hour volume"), exact decimal sum.
+ *  - unknown / absent values are null; a ticker without a mark price, or whose read fails, drops
+ *    that market (warned by name).
+ *  - request budget: the registry path (fetchMarkets / fetchFundingRates) is price-only
+ *    (instruments + one ticker per market, both reused in-process for 15 s); margin_rules (leverage)
+ *    only for `market list` / `info`, file-cached 6 h per network.
+ */
+import { type VenuePublicData } from "../venue.js";
+import type { AssetClass, FundingRateBasis, Network, VenueFundingRate, VenueMarket } from "../venue-types.js";
+import { GrvtClient } from "./client.js";
+/** Requests in flight at once for the per-instrument fan-out (ticker / margin_rules). */
+export declare const GRVT_FANOUT_CONCURRENCY = 8;
+/** In-process reuse of the directory and of each ticker (repeated MCP / dashboard reads). */
+export declare const GRVT_SHORT_TTL_MS = 15000;
+/** margin_rules brackets change rarely: file cache (src/cache.ts), per network. */
+export declare const GRVT_MARGIN_TTL_MS: number;
+export interface GrvtMarketMeta {
+    instrument: string;
+    symbol: string;
+    quote: string;
+    tickSize: string;
+    minSize: string;
+    minNotional: string | null;
+    /** funding_interval_hours of this instrument (required by the schema; drift is EXCHANGE_ERROR). */
+    fundingIntervalHours: number;
+    assetClass: AssetClass;
+    canonical: string | null;
+    tradable: boolean;
+}
+/**
+ * Cross-venue key: crypto / commodity / preIpo through canonical-symbols.ts; an equity / etf only
+ * when whitelisted (MATCHABLE_EQUITY / ETF), else null — warned once when not reviewed at all.
+ */
+export declare function grvtCanonicalOf(symbol: string, assetClass: AssetClass, warn: (msg: string) => void): string | null;
+/**
+ * Parse one instruments row. Returns null for a row that is not a listed perpetual (another kind,
+ * an expiring settlement period); shape drift on a perpetual row is EXCHANGE_ERROR.
+ */
+export declare function toGrvtMarketMeta(raw: unknown, warn: (msg: string) => void): GrvtMarketMeta | null;
+export declare function fetchGrvtDirectory(client: GrvtClient, warn: (msg: string) => void): Promise<GrvtMarketMeta[]>;
+/** Resolve a CLI symbol ("btc", "BTC-PERP", "BTC_USDT_Perp", "BTC-USDT") against the directory. */
+export declare function resolveGrvtMarket(dir: readonly GrvtMarketMeta[], input: string): GrvtMarketMeta;
+export interface GrvtTicker {
+    markPrice: string | null;
+    indexPrice: string | null;
+    lastPrice: string | null;
+    bestBid: string | null;
+    bestAsk: string | null;
+    openInterest: string | null;
+    volume24hQuote: string | null;
+    /** Percent per the market's funding interval, as published. */
+    fundingPct: string | null;
+    /** ms; null when absent. */
+    nextFundingTime: number | null;
+}
+export declare function toGrvtTicker(raw: unknown): GrvtTicker;
+/** Percent → fraction, exactly ("0.0063" → "0.000063"); null stays null (unknown, never 0). */
+export declare function grvtPercentToFraction(pct: string | null): string | null;
+export declare function grvtFundingBasis(m: Pick<GrvtMarketMeta, "fundingIntervalHours">): FundingRateBasis;
+export interface GrvtLeverage {
+    maxLeverage: number;
+    tiers: Array<{
+        lowerBound: number;
+        maxLeverage: number;
+    }>;
+}
+/** risk_brackets → tier-1 max leverage and the notional tiers (ascending); null when unpublished. */
+export declare function toGrvtLeverage(raw: unknown): GrvtLeverage | null;
+type Settled<R> = {
+    ok: true;
+    value: R;
+} | {
+    ok: false;
+    error: unknown;
+};
+/**
+ * Run `fn` over `items` with `limit` in flight; each item settles on its own. RATE_LIMITED stops
+ * every worker (nothing new is sent) and is re-thrown — the venue told us to back off.
+ */
+export declare function settleEach<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<Settled<R>[]>;
+export declare function fetchGrvtTicker(client: GrvtClient, instrument: string): Promise<GrvtTicker>;
+export declare function fetchGrvtLeverage(client: GrvtClient, instrument: string): Promise<GrvtLeverage | null>;
+/** Drop every GRVT cache (in-process directory / tickers and the margin-rules file cache). */
+export declare function clearGrvtCaches(): void;
+/** The directory, reused for GRVT_SHORT_TTL_MS; a failed read is not kept. */
+export declare function grvtDirectory(client: GrvtClient, net: Network, warn: (msg: string) => void): Promise<GrvtMarketMeta[]>;
+/** One ticker, reused for GRVT_SHORT_TTL_MS. */
+export declare function grvtTicker(client: GrvtClient, net: Network, instrument: string): Promise<GrvtTicker>;
+/** One margin-rules cache entry: when it was read (ms) and what it said (null = no brackets published). */
+export interface GrvtLeverageEntry {
+    fetchedAt: number;
+    leverage: GrvtLeverage | null;
+}
+/**
+ * Leverage per instrument from the margin-rules file cache (JSON: instrument → {fetchedAt, leverage}).
+ * Each entry expires on its own GRVT_MARGIN_TTL_MS after ITS read (rewriting the file never extends
+ * an old entry); expired, malformed and missing instruments are read again. A failed read leaves
+ * that market's leverage unknown (null entry, warned, not cached).
+ */
+export declare function grvtLeverageFor(client: GrvtClient, net: Network, instruments: readonly string[], warn: (msg: string) => void): Promise<Record<string, GrvtLeverageEntry | null>>;
+export type GrvtVenueMarket = VenueMarket & {
+    tickSize: string;
+    /** When maxLeverage / marginTiers were read from GRVT (ISO; they may come from the 6 h cache); null = not read. */
+    leverageAsOf: string | null;
+    lastPrice: string | null;
+    bestBid: string | null;
+    bestAsk: string | null;
+    nextFundingTime: number | null;
+};
+export declare function toGrvtVenueMarket(m: GrvtMarketMeta, t: GrvtTicker & {
+    markPrice: string;
+}, entry: GrvtLeverageEntry | null): GrvtVenueMarket;
+export interface GrvtPublicDeps {
+    warn: (msg: string) => void;
+}
+export declare function grvtClient(net: Network): GrvtClient;
+export interface GrvtMarketsOptions {
+    /** true: also max leverage / margin tiers (margin_rules, file-cached); false: price-only (instruments + tickers). */
+    leverage: boolean;
+}
+export declare function fetchGrvtMarkets(net: Network, opts: GrvtMarketsOptions, deps?: GrvtPublicDeps): Promise<GrvtVenueMarket[]>;
+/** One market: directory (cached) + its ticker + its margin rules — no fan-out. */
+export declare function fetchGrvtMarket(net: Network, symbol: string, deps?: GrvtPublicDeps): Promise<GrvtVenueMarket>;
+/** Funding rows (tickers only — no margin_rules): fraction per the market's own interval. */
+export declare function fetchGrvtFundingRates(net: Network, deps?: GrvtPublicDeps): Promise<VenueFundingRate[]>;
+/** The registry's public data path (MCP get_prices / get_markets, market://prices, arb, dashboards): price-only. */
+export declare const grvtPublicData: VenuePublicData;
+export {};