# API

## Read-Only API

Public REST API providing market statistics for Variational Omni.

### Base URL

<https://omni-client-api.prod.ap-northeast-1.variational.io>

### Endpoint

GET /metadata/stats

Returns platform-wide and per-listing market statistics.

### Rate Limits

* Per IP: 10 requests per 10 seconds.
* Global: 1000 requests per minute.&#x20;

### 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                          |
| num\_markets               | integer | Number of listed perpetual markets                              |
| loss\_refund.pool\_size    | string  | Loss refund pool balance (USDC)                                 |
| loss\_refund.refunded\_24h | string  | Amount of loss refunds processed in last 24 hours (USDC)        |
| listings                   | array   | Per-listing statistics                                          |

#### Per-Listing Fields

| Field                                | Type          | Description                       |
| ------------------------------------ | ------------- | --------------------------------- |
| ticker                               | string        | Asset ticker (e.g., `BTC`, `ETH`) |
| name                                 | string        | Token Description                 |
| mark\_price                          | string        | Current mark price                |
| volume\_24h                          | string        | 24h trading volume (USDC)         |
| open\_interest.long\_open\_interest  | string        | Long open interest                |
| open\_interest.short\_open\_interest | string        | Short open interest               |
| funding\_rate                        | string        | Current funding rate (decimal)    |
| funding\_interval\_s                 | integer       | Funding interval in seconds       |
| base\_spread\_bps                    | string        | Base spread in basis points       |
| quotes.updated\_at                   | string        | ISO 8601 timestamp of quote       |
| quotes                               | quotes object | Quote details                     |

#### Quotes Fields

| Field       | Type                            | Description                                |
| ----------- | ------------------------------- | ------------------------------------------ |
| updated\_at | Time the quote was last updated | ISO 8601 timestamp of quote                |
| 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 (majors only) |

#### Quote Fields

| Field | Type   | Description |
| ----- | ------ | ----------- |
| bid   | string | price       |
| ask   | string | price       |

### Sample Json

```
{
   "total_volume_24h":"1852892926.854888",
   "cumulative_volume":"108671952666.516115",
   "tvl":"100687516.122407000000",
   "open_interest":"901741683.7948225316456366773",
   "num_markets":486,
   "loss_refund":{
      "pool_size":"106919.703032000000",
      "refunded_24h":"25475.042848"
   },
   "listings":[
      {
         "ticker":"BTC",
         "name":"Bitcoin",
         "mark_price":"93787.9606019699",
         "volume_24h":"1058107020.462713",
         "open_interest":{
            "long_open_interest":"113883049.01452301878687056000",
            "short_open_interest":"82403040.51901045963533924000"
         },
         "funding_rate":"0.037347",
         "funding_interval_s":28800,
         "base_spread_bps":"0.4307589134116585963643440000",
         "quotes":{
            "updated_at":"2026-01-06T06:38:52.476166127Z",
            "size_1k":{
               "bid":"93750.97",
               "ask":"93755.01"
            },
            "size_100k":{
               "bid":"93746.13",
               "ask":"93759.85"
            },
            "size_1m":{
               "bid":"93718.95",
               "ask":"93779.82"
            }
         }
      }
   ]
}
```

### Example

#### Python

```python
import requests

BASE_URL = "https://omni-client-api.prod.ap-northeast-1.variational.io"

def fetch_stats():
    resp = requests.get(f"{BASE_URL}/metadata/stats")
    resp.raise_for_status()
    return resp.json()

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 tokens
print("\nListings:")
for listing in stats["listings"]:
    print(f"  {listing['ticker']}: ${listing['mark_price']}")
```

### 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 USD&#x43;**.**
* Funding rates are decimals (multiply by 100 for percentage).
* Optional fields may be omitted when unavailable.

### Support

For questions, [contact support through one of our official channels](https://docs.variational.io/more/getting-help-support).

## 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.variational.io/technical-documentation/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.