# TWAP

### What is TWAP?

TWAP (Time-Weighted Average Price) is a pricing algorithm used to calculate **the average price of an asset over a defined time period**. The value derived from TWAP is used as the reference price for any token with a liquidity pool deployed on GnoSwap, serving as **a minimal and permissionless price oracle**.

### **Advantages of TWAP**

* **Flexibility:** TWAP is highly customizable and flexible due to its simple implementation. A shorter observation window can be used for freshness and responsiveness, while a longer observation window can be used for stability against abnormal price spikes.
* **Manipulation Resistance:** Manipulating a TWAP-based token price forces the attacker to maintain an unfavorable exchange rate for a liquidity pool for an extended period of time while exposed to arbitrage. The cost to attack increases linearly with the length of the observation window.
* **Scalability:** TWAP can be used on any liquidity pool on GnoSwap to provide a reference price permissionlessly, without needing to integrate a 3rd-party oracle provider.

{% hint style="info" %}
**Observation Window**: The block-based time span used for TWAP calculation.
{% endhint %}

### **TWAP Formula**

The following formula is used to calculate the TWAP of a token:

$$
\text{TWAP}*{N-M \rightarrow N} = \frac{priceCum\_N - priceCum*{N-M}}{time\_N - time\_{N-M}}
$$

* `N` : Current block
* `M` : The number of blocks in the observation window
* `priceCum` : Cumulative sum of `price * block duration` over the observation window

For tokens with multiple pools, the price history of the most liquid pool is selected.

<details>

<summary>TWAP Calculation Example</summary>

Assume the following cumulative price data was recorded over the past 10 blocks:

* **Block #100**
  * Cumulative Price (priceCum₁₀₀): 12,000
  * Timestamp (time₁₀₀): 1,000,000
* **Block #110** (current block)
  * Cumulative Price (priceCum₁₁₀): 14,000
  * Timestamp (time₁₁₀): 1,001,000

Then, the TWAP is calculated as:

```
(14,000 − 12,000) / (1,001,000 − 1,000,000) = 2,000 / 1,000 = 2.0
```

This indicates that the average pool price over the last 10 blocks was 2.0.

</details>

### **Price Grades**

Token prices are classified into 2 tiers: **oracle-grade** and **informational**.

**Oracle-grade** refers to prices of tokens that pass strict criteria described below.

**Informational** refers to prices of tokens that do not meet the criteria. Token prices under this category should only be used for informational purposes.

The criteria evaluate pools containing a token, using the following variables:

* **Root Pool:** A stricter requirement is enforced to pools which consists of two Root Tokens (e.g., USDC/GNOT, GNS/GNOT).
* **TVL Threshold**: A minimum Total Value Locked (TVL) to ensure sufficient liquidity.
* **SqrtPrice Threshold**: Ensures both tokens are present in the pool to prevent single-sided liquidity manipulations.
* **Block Age Threshold**: Pools must have enough price history to calculate a reliable TWAP.
* **Observation Window**: Pools with higher liquidity can tolerate shorter observation windows, as the cost of price manipulation scales with liquidity around market price.

{% hint style="info" %}
**Root Token**: A token considered core to the ecosystem. Initially includes GNOT, GNS, and reputable stablecoins.
{% endhint %}

### TWAP API Usage Guide

The following API endpoints can be used to fetch the TWAP of any token traded on GnoSwap. You can filter by tiers or set a custom observation window.

#### **1. Oracle-Grade Prices**

Use this endpoint to fetch the prices of oracle-grade tier tokens.

<table><thead><tr><th width="146.0703125">Method </th><th>URL</th></tr></thead><tbody><tr><td>GET</td><td>https://api.gnoswap.io/v1/tokens/prices?grade=ORACLE</td></tr></tbody></table>

#### **2. Informational Prices**

Use this endpoint to fetch the prices of informational tier tokens.

<table><thead><tr><th width="146.0703125">Method </th><th>URL</th></tr></thead><tbody><tr><td>GET</td><td>https://api.gnoswap.io/v1/tokens/prices?grade=INFORMATIONAL</td></tr></tbody></table>

#### **3. No Price Available**

No TWAP price is provided for tokens with negligible liquidity or an age of 11 blocks or less.

<table><thead><tr><th width="146.0703125">Method </th><th>URL</th></tr></thead><tbody><tr><td>GET</td><td>https://api.gnoswap.io/v1/tokens/prices?grade=NONE</td></tr></tbody></table>

#### **4. Custom Observation Window**

You can customize TWAP queries by specifying the observation window used to calculate the price. **Longer observation windows** can be used for instances that require higher stability. **Shorter observation windows** can be used for instances that require responsiveness and freshness of price data.

<table><thead><tr><th width="146.0703125">Method </th><th>URL</th></tr></thead><tbody><tr><td>GET</td><td>https://api.gnoswap.io/v1/tokens/prices?window=600</td></tr></tbody></table>

**Examples:**&#x20;

* `window=600` → 10-minute TWAP
* `window=1800` → 30-minute TWAP

{% hint style="info" %}
**Disclaimer**

TWAP-based prices are provided for **informational purposes only**. Prices may differ from actual execution rates. You should not solely rely on TWAP prices when trading. GnoSwap will not be liable for any losses that occur from discrepancies between TWAP and the actual market rates.
{% 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.gnoswap.io/references/twap.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.