qoery | The Affordable Crypto Market Data API

Getting Latest vs Historical Data

Latest/Real-Time Data

To get the most recent candles (real-time data), omit the from parameter. The API will automatically calculate the start time based on your interval and limit, and the to parameter defaults to the current time.

# Get latest 10 candles with 15-minute intervals
curl "https://api.qoery.com/v0/candles?pool=0x88e6...&interval=15m&limit=10" \
  -H "X-API-KEY: your_api_key_here"

This returns the most recent candles up to the current moment.

Historical Data

To get historical data for a specific time range, provide both from and to parameters with ISO 8601 timestamps:

# Get historical candles for a specific date range
curl "https://api.qoery.com/v0/candles?pool=0x88e6...&interval=1h&from=2023-11-01T00:00:00Z&to=2023-11-30T23:59:59Z&limit=100" \
  -H "X-API-KEY: your_api_key_here"

Note: When requesting historical data, the limit parameter still applies. For large time ranges, you may need to make multiple requests with different from/to ranges to get all the data you need.

Parameters

symbolstring

Trading pair (e.g., "WETH-USDT"). Provide either symbol OR pool.

poolstring

Pool address. Provide either symbol OR pool.

intervalstringrequired

Time interval (format: [number][unit] where unit is s, m, h, or d). Examples: 30s, 1m, 5m, 15m, 1h, 4h, 1d, 12h, 45m. Maximum: 1d (86400 seconds)

fromstring

Start time (ISO 8601). Default: Calculated based on interval and limit to fetch only the requested number of candles (e.g., with limit=5 and interval=15m, defaults to 75 minutes ago)

tostring

End time (ISO 8601). Default: now

networksstring

Comma-separated networks: ethereum,arbitrum,polygon,base,optimism. Default: If not specified, queries ethereum first (fastest), then expands to ethereum,arbitrum,polygon if no results found. Note: Base and Optimism are configured but not yet verified.

limitinteger

Max candles (1-100). Default: 5

Response

dataarray

Array of OHLCV candles

Candle

timestring

ISO 8601 timestamp

opennumber

Opening price

highnumber

Highest price

lownumber

Lowest price

closenumber

Closing price

volumenumber

Trading volume

credits_usedinteger

Credits consumed (1+). The actual number depends on the amount of data fetched (number of swaps, time range, and whether pool discovery is needed).

warningobjectoptional

Warning object included when using symbol parameter instead of pool. Contains suggestions for optimizing credit usage.

Warning

messagestring

Warning message

documentation_urlstring

URL to best practices documentation

tipstring

Helpful tip for reducing credit usage

curl "https://api.qoery.com/v0/candles?symbol=WETH-USDT&interval=15m&limit=10" \
  -H "X-API-KEY: your_api_key_here"

const response = await fetch(
  'https://api.qoery.com/v0/candles?symbol=WETH-USDT&interval=15m&limit=10',
  { headers: { 'X-API-KEY': 'your_api_key_here' } }
);

import requests

response = requests.get(
    'https://api.qoery.com/v0/candles',
    headers={'X-API-KEY': 'your_api_key_here'},
    params={'symbol': 'WETH-USDT', 'interval': '15m', 'limit': 10}
)

{
  "data": [
    {
      "time": "2023-11-30T12:00:00Z",
      "open": 2050.50,
      "high": 2060.00,
      "low": 2045.20,
      "close": 2055.80,
      "volume": 1500000.50
    }
  ],
  "credits_used": 2
}

{
  "data": [
    {
      "time": "2023-11-30T12:00:00Z",
      "open": 2050.50,
      "high": 2060.00,
      "low": 2045.20,
      "close": 2055.80,
      "volume": 1500000.50
    }
  ],
  "credits_used": 3,
  "warning": {
    "message": "Using a symbol parameter consumes more credits than using a pool address. Consider using a pool address instead.",
    "documentation_url": "https://qoery.com/docs/best-practices",
    "tip": "Get pool addresses from the /pools endpoint or Uniswap UI, then use the pool parameter instead of symbol."
  }
}

Response Headers

X-API-Suggestionstringoptional

Suggestion header included when using symbol parameter. Contains a message about using pool addresses to reduce credit usage.

Notes

Credit usage depends on the amount of data fetched (number of swaps, time range, pagination).
Using pool is generally more efficient than symbol as it skips the pool discovery phase, which can require multiple GraphQL queries.
When using symbol, the response includes a warning field and X-API-Suggestion header with optimization suggestions.