> For the complete documentation index, see [llms.txt](https://docs.variational.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.variational.io/technical-documentation/api.md). # API ## Read-Only API Public REST API providing market statistics for Variational Omni. ### Base URL ### Endpoint `GET /metadata/v2/stats` Returns platform-wide and per-listing market statistics for all perpetual and swap markets. {% hint style="warning" %} The legacy v1 endpoint, `GET /metadata/stats`, is still available for existing integrations but is not recommended, as it may have incomplete or stale information. For example, its tickers do not say whether a market is a perpetual or a swap, and it reports a placeholder funding rate of `0` for swaps. New integrations should use `/metadata/v2/stats`, and existing ones should [migrate](#migrating-from-v1). {% endhint %} ### Rate Limits * Per IP: 10 requests per 10 seconds. * Global: 1000 requests per minute. The limits are shared with the legacy v1 endpoint. Requests over the limit receive HTTP `429` with a JSON body whose `retry_after_seconds` field says when to retry. ### Response Fields #### General Metrics | Field | Type | Description | | -------------------------- | ------- | ---------------------------------------------------------------------------------------------------- | | `total_volume_24h` | string | 24-hour trading volume across all markets (USDC) | | `cumulative_volume` | string | Lifetime cumulative trading volume (USDC) | | `tvl` | string | Total value locked in settlement pools and the OLP vault (USDC) | | `open_interest` | string | Total open interest across all markets (USDC), double-sided: includes both trader and OLP positions | | `num_markets` | integer | Number of listed markets, perpetuals and swaps alike. May exceed the number of entries in `listings` | | `loss_refund.pool_size` | string | Deprecated. Always `0`, as loss refunds have been discontinued | | `loss_refund.refunded_24h` | string | Deprecated. Always `0`, as loss refunds have been discontinued | | `listings` | array | Per-listing statistics | #### Per-Listing Fields | Field | Type | Description | | ----------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ticker` | string | Market ticker, suffixed with the contract type (e.g., `BTC-PERP`, `XAU-SWAP`) | | `contract_type` | string | `perpetual` or `swap`. Determines the shape of `funding` | | `name` | string | Asset name (e.g., `Bitcoin`) | | `mark_price` | string | Current mark price | | `volume_24h` | string | 24h trading volume (USDC) | | `open_interest.long_open_interest` | string | Long open interest (USDC), single-sided: trader positions only | | `open_interest.short_open_interest` | string | Short open interest (USDC), single-sided: trader positions only | | `funding` | object or null | Current funding terms. See [Perpetual Funding Fields](#perpetual-funding-fields) and [Swap Funding Fields](#swap-funding-fields). `null` when no funding data is available for the market | | `base_spread_bps` | string | Bid/ask spread of the smallest quote (`quotes.base`, or `quotes.size_1k` if unavailable), in basis points of the mark price | | `quotes` | quotes object | Indicative quotes at several sizes | #### Perpetual Funding Fields Shape of `funding` when `contract_type` is `perpetual`. See [Funding Rates](/omni/trading/funding-rates.md) for how perpetual funding works. | Field | Type | Description | | ------------------ | ----------------------------- | -------------------------------------------------------------------------- | | `last` | perpetual rate object | Current funding rate | | `next` | perpetual rate object or null | Predicted funding rate for the next interval. Currently the same as `last` | | `interval_seconds` | integer | Funding interval in seconds | | `next_timestamp` | integer | Time of the next funding payment (Unix seconds) | Each perpetual rate object contains the same rate in two units. A positive rate means longs pay shorts; a negative rate means shorts pay longs. | Field | Type | Description | | ----------------- | ------ | ------------------------------------- | | `annualized_rate` | string | Annualized funding rate | | `interval_rate` | string | Funding rate for one funding interval | #### Swap Funding Fields Shape of `funding` when `contract_type` is `swap`. Swap funding is paid once per trading day, with separate rates for longs and shorts. See [Swaps Funding](/omni/trading/swaps.md#swaps-funding) for how it works. | Field | Type | Description | | ------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------- | | `last` | swap rate object or null | Rates of the most recently applied funding payment. `null` if the market has not paid funding in the past week | | `next` | swap rate object or null | Rates of the upcoming funding payment. `null` between a payment and the publication of the next one's rates | | `interval_seconds` | integer | Always `86400` (one payment per trading day) | | `next_timestamp` | integer or null | Time the `next` payment applies (Unix seconds). `null` when `next` is `null` | At least one of `last` and `next` is present; a swap market with neither reports `funding` as `null`. Each swap rate object contains: | Field | Type | Description | | ----------------------- | ------ | ----------------------------------------------------------------------------- | | `annualized_long_rate` | string | Annualized rate for long positions. Positive means longs pay | | `annualized_short_rate` | string | Annualized rate for short positions. Positive means shorts receive | | `interval_long_rate` | string | Rate for long positions for one payment (the annualized rate divided by 360) | | `interval_short_rate` | string | Rate for short positions for one payment (the annualized rate divided by 360) | Payments that cover weekends or market holidays include the closed days, so their rates read about 3× those of a regular day. #### Quotes Fields | Field | Type | Description | | ------------ | ------------ | ----------------------------------------------------------------- | | `updated_at` | string | Time the quotes were fetched (ISO 8601) | | `base` | quote object | Quote at the market's minimum order size | | `size_1k` | quote object | Quote at $1,000 notional | | `size_100k` | quote object | Quote at $100,000 notional | | `size_1m` | quote object | Quote at $1,000,000 notional (major and high-volume markets only) | #### Quote Fields | Field | Type | Description | | ----- | ------ | ----------- | | `bid` | string | Bid price | | `ask` | string | Ask price | ### Sample JSON ```json { "total_volume_24h":"2920943245.388420", "cumulative_volume":"416044064688.200274", "tvl":"248014344.061357238319", "open_interest":"1987286354.4650931360216989168", "num_markets":574, "loss_refund":{ "pool_size":"0", "refunded_24h":"0" }, "listings":[ { "ticker":"BTC-PERP", "contract_type":"perpetual", "name":"Bitcoin", "mark_price":"81949.0209200006", "volume_24h":"528168457.662900", "open_interest":{ "long_open_interest":"110044164.72693555847828704000", "short_open_interest":"78790752.081392375376751770000" }, "funding":{ "last":{ "annualized_rate":"0.09029", "interval_rate":"0.00008246" }, "next":{ "annualized_rate":"0.09029", "interval_rate":"0.00008246" }, "interval_seconds":28800, "next_timestamp":1792137600 }, "base_spread_bps":"1.2568789577187207946037940000", "quotes":{ "updated_at":"2026-10-16T02:51:10.363561208Z", "base":{ "bid":"81918.72", "ask":"81929.02" }, "size_1k":{ "bid":"81918.72", "ask":"81929.02" }, "size_100k":{ "bid":"81913.39", "ask":"81937.02" }, "size_1m":{ "bid":"81906.19", "ask":"81947.81" } } }, { "ticker":"XAU-SWAP", "contract_type":"swap", "name":"Swap on Gold Spot", "mark_price":"4166.07", "volume_24h":"113948680.184497", "open_interest":{ "long_open_interest":"40296541.62545700000000", "short_open_interest":"9480588.76858260000000" }, "funding":{ "last":{ "annualized_long_rate":"0.05752", "annualized_short_rate":"0.02548", "interval_long_rate":"0.0001598", "interval_short_rate":"0.00007078" }, "next":{ "annualized_long_rate":"0.05843", "annualized_short_rate":"0.02569", "interval_long_rate":"0.0001623", "interval_short_rate":"0.00007135" }, "interval_seconds":86400, "next_timestamp":1792184700 }, "base_spread_bps":"0.0960137491688809837568740000", "quotes":{ "updated_at":"2026-10-16T02:50:29.160234061Z", "base":{ "bid":"4168.12", "ask":"4168.16" }, "size_1k":{ "bid":"4168.12", "ask":"4168.16" }, "size_100k":{ "bid":"4167.8", "ask":"4168.45" }, "size_1m":{ "bid":"4167.53", "ask":"4168.74" } } } ] } ``` ### Example #### Python ```python # /// script # requires-python = ">=3.9" # dependencies = ["requests"] # /// import requests BASE_URL = "https://omni-client-api.prod.ap-northeast-1.variational.io" def fetch_stats(): resp = requests.get(f"{BASE_URL}/metadata/v2/stats") resp.raise_for_status() return resp.json() def describe_funding(listing): funding = listing["funding"] if funding is None: return "no funding data" if listing["contract_type"] == "perpetual": rate = float(funding["last"]["annualized_rate"]) return f"{rate:.2%} annualized" # Swaps: prefer the upcoming payment once its rates are published rates = funding["next"] or funding["last"] long_rate = float(rates["annualized_long_rate"]) short_rate = float(rates["annualized_short_rate"]) return f"long {long_rate:.2%} / short {short_rate:.2%} annualized" stats = fetch_stats() # Platform metrics print(f"24h Volume: ${float(stats['total_volume_24h']):,.2f}") print(f"TVL: ${float(stats['tvl']):,.2f}") print(f"Open Interest: ${float(stats['open_interest']):,.2f}") print(f"Markets: {stats['num_markets']}") # List all markets print("\nListings:") for listing in stats["listings"]: print(f" {listing['ticker']}: ${listing['mark_price']}, funding {describe_funding(listing)}") ``` You may save the script as `omni_stats.py` and run it directly with [uv](https://docs.astral.sh/uv/): ```bash uv run omni_stats.py ``` ### Migrating from v1 `/metadata/v2/stats` reports the same platform-wide metrics as `/metadata/stats`. Only the per-listing fields differ: * `ticker` is suffixed with the contract type, e.g., `BTC` becomes `BTC-PERP`. Swaps are listed under their displayed symbol, e.g., `XAUS` becomes `XAU-SWAP`. * `contract_type` is new. * `funding` replaces `funding_rate` and `funding_interval_s`. For perpetuals, v1's `funding_rate` corresponds to `funding.last.annualized_rate`, and `funding_interval_s` to `funding.interval_seconds`. Swaps, which v1 reports with a placeholder rate of `0`, now report their actual long and short rates. * A market without funding data reports `funding` as `null` rather than a funding rate of `0`. ### Notes * All numeric values are returned as strings to preserve decimal precision. * The bid/ask price may be cached for up to 600 seconds, all quotes contain an `updated_at` field. * Prices and volumes are denominated in USDC. * Funding rates are decimals (multiply by 100 for percentage). * `quotes.updated_at` is an ISO 8601 string, while funding timestamps are Unix seconds. * `name`, `base_spread_bps`, `quotes`, and the individual quote sizes are omitted when unavailable, e.g., while a swap market is closed. `funding` is always present, and is `null` when unavailable. ### Support For questions, [contact support through one of our official channels](/more/getting-help-support.md). ## Trading API {% hint style="info" %} The trading API is still in development, and is not yet available to any users. Please fill out [this form](https://variational.typeform.com/api-request) if you wish to be notified once the trading API is available. {% endhint %}