qoery | The Affordable Crypto Market Data API

Use Pool Addresses Instead of Symbols

Save credits per request by querying with pool addresses. The exact savings depends on how many networks and protocols need to be queried during pool discovery.

Why Pool Addresses Are Better

More efficient: Skips the pool discovery step
Faster responses: Direct queries eliminate one network round-trip
Lower cost: Consumes fewer credits by skipping discovery
More reliable: No ambiguity when multiple pools exist for the same pair

How to Implement

Step 1: Get the pool address (one-time lookup)

# Option A: Use our API
curl "https://api.qoery.com/v0/pools?symbol=WETH-USDT" \
  -H "X-API-KEY: your_api_key_here"

# Option B: Get from Uniswap UI (0 credits)
# Visit https://app.uniswap.org and copy the pool address

Step 2: Store and reuse the pool address

// Store pool addresses in your application
const POOLS = {
  'WETH-USDT-ethereum': '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
  'WBTC-USDC-ethereum': '0x99ac8ca7087fa4a2a1fb6357269965a2014abc35',
  // ... more pools
};

// Use them in your requests
const poolAddress = POOLS['WETH-USDT-ethereum'];
const response = await fetch(
  `https://api.qoery.com/v0/candles?pool=${poolAddress}&interval=15m&limit=100`,
  { headers: { 'X-API-KEY': 'your_api_key_here' } }
);

Optimize Time Ranges

Request only the data you need to minimize credits and improve response times.

Use the `limit` Parameter

Instead of fetching all data and filtering client-side, use limit:

# Good: Request exactly what you need
curl "https://api.qoery.com/v0/candles?pool=0x88e6...&interval=1h&limit=24" \
  -H "X-API-KEY: your_api_key_here"

# Avoid: Fetching excessive data
curl "https://api.qoery.com/v0/candles?pool=0x88e...&interval=1h&limit=1000" \
  -H "X-API-KEY: your_api_key_here"

Choose Appropriate Intervals

Select an interval that matches your analysis needs. Note that credit usage is primarily determined by the time range of data fetched (and the number of swaps within that range), not just the interval itself.

Format: [number][unit] where unit is s (seconds), m (minutes), h (hours), or d (days). Maximum: 1d (86400 seconds). Any valid combination is accepted (e.g., 30s, 45m, 12h).

High-frequency monitoring: 30s, 1m, 5m
Real-time monitoring: 15m
Intraday analysis: 1h, 4h, 12h
Daily charts: 1d (maximum interval is 1 day)

Specify Networks

Narrow your search to specific networks for faster responses and lower credit usage.

Default Behavior

When you don't specify a networks parameter:

The API first queries ethereum only (fastest, most likely to have pools)
If no results are found, it automatically expands to ethereum,arbitrum,polygon
This optimization reduces credit usage for common queries

Explicit Network Selection

# Good: Specify the network you need (faster, fewer credits)
curl "https://api.qoery.com/v0/candles?symbol=WETH-USDT&interval=15m&networks=ethereum" \
  -H "X-API-KEY: your_api_key_here"

# Also good: Multiple networks (comma-separated)
curl "https://api.qoery.com/v0/candles?symbol=WETH-USDT&interval=15m&networks=ethereum,arbitrum" \
  -H "X-API-KEY: your_api_key_here"

# Default: Queries ethereum first, then expands if needed
curl "https://api.qoery.com/v0/candles?symbol=WETH-USDT&interval=15m" \
  -H "X-API-KEY: your_api_key_here"

Fully verified networks: ethereum (V3 and V4), arbitrum (V3 and V4), polygon (V3 only)

Note: base and optimism are configured but not yet verified. They may work but are not guaranteed.

Monitor Your Usage

Track your credit consumption to optimize costs.

Check Usage Regularly

curl "https://api.qoery.com/v0/usage" \
  -H "X-API-KEY: your_api_key_here"

Response Includes Credits Used

Every API response includes credits_used:

{
  "data": [...],
  "credits_used": 3
}

Error Handling

Implement robust error handling for production applications.

Rate Limits (429): Respect the Retry-After header if you hit rate limits.
Validation: Always check that the returned data array is not empty. An empty array usually means the pool doesn't exist or has no liquidity in the requested range.

Security Best Practices

Protect your API key and user data.

Never Expose API Keys Client-Side

Do not use your API key directly in frontend code (React, Vue, etc.). Always route requests through your own backend server to keep your keys secret.

Summary

Use pool addresses instead of symbols (saves credits by skipping pool discovery)
Optimize time ranges with appropriate limits
Specify networks when you know which one you need
Monitor usage to identify optimization opportunities
Secure your API key by using a backend proxy

Following these practices will help you build efficient, cost-effective applications with the qoery API.

Best Practices