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.

Observation Window: The block-based time span used for TWAP calculation.

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.

TWAP Calculation Example

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.

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.

Root Token: A token considered core to the ecosystem. Initially includes GNOT, GNS, and reputable stablecoins.

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.

Method	URL
GET	https://api.gnoswap.io/v1/tokens/prices?grade=ORACLE

2. Informational Prices

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

Method	URL
GET	https://api.gnoswap.io/v1/tokens/prices?grade=INFORMATIONAL

3. No Price Available

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

Method	URL
GET	https://api.gnoswap.io/v1/tokens/prices?grade=NONE

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.

Method	URL
GET	https://api.gnoswap.io/v1/tokens/prices?window=600

Examples:

• window=600 → 10-minute TWAP

• window=1800 → 30-minute TWAP

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.