GitHub - qoery-com/qoery-py: Python SDK for real-time & historical DEX data. 50% cheaper than alternatives.

qoery-py

Professional Crypto Data at Indie Prices.

The Official Python SDK for Qoery - The Cheapest DeFi Data API

Access real-time and historical DeFi data from Uniswap and other DEXs with the most cost-effective API on the market.

Documentation | OHLCV Data | Tick-Level Data

Features

Simple & Intuitive: Clean, Pythonic API that feels natural
OHLCV Candles: Get aggregated price data with flexible intervals
Raw Tick Data: Access individual swap transactions for detailed analysis
Pool Discovery: Find the best liquidity pools across multiple networks
Multi-Network Support: Ethereum, Arbitrum, Polygon, Base, and Optimism
Usage Tracking: Monitor your API usage and rate limits
Type-Safe: Full type hints and dataclasses for better IDE support

Installation

Authentication

Get your free API key at qoery.com

Set your API key as an environment variable:

export QOERY_API_KEY="your-api-key-here"

Quick Start

import qoery

# Initialize - it's that simple!
client = qoery.Client()

# Get analyzed data instantly as Pandas DataFrame
df = client.candles.get(symbol="ETH-USDC", interval="15m").df
print(df.head())

Why This SDK?

This SDK provides two layers:

qoery (recommended) - Clean, developer-friendly wrapper
qoery._internal - Auto-generated OpenAPI client (lower-level)

The clean wrapper provides:

Cleaner, more intuitive API
Better error handling
Pythonic naming conventions
Type-safe dataclasses instead of dictionaries
Context manager support
Sensible defaults

Examples

Get OHLCV Candles

# Simple - using symbol
candles = client.candles.get(
    symbol="ETH-USDC",
    interval="15m",
    limit=10
)

# Advanced - using pool address (faster, cheaper)
candles = client.candles.get(
    pool="0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
    interval="1h",
    limit=100,
    networks="ethereum"
)

Get Raw Tick Data

ticks = client.ticks.get(
    symbol="WBTC-USDT",
    limit=100
)

for tick in ticks:
    print(f"{tick.timestamp}: ${tick.price} ({tick.side})")

Find Liquidity Pools

pools = client.pools.find(symbol="ETH-USDC")

for pool in pools:
    print(f"{pool.network}: TVL ${pool.tvl_usd}")

Check API Usage

usage = client.account.usage()

print(f"Plan: {usage.subscription_plan}")
print(f"Credits: {usage.credits_month.used}/{usage.credits_month.limit}")
print(f"Remaining: {usage.credits_month.remaining}")

Using Context Manager

with qoery.Client() as client:
    candles = client.candles.get(symbol="ETH-USDC", interval="15m")
    # Client automatically closes when exiting context

Error Handling

try:
    candles = client.candles.get(symbol="ETH-USDC", interval="15m")
except qoery.AuthenticationError:
    print("Invalid API key")
except qoery.InvalidRequestError as e:
    print(f"Bad request: {e}")
except qoery.RateLimitError:
    print("Rate limit exceeded")
except qoery.APIError as e:
    print(f"API error: {e}")

Full Examples

Check out the examples/ directory:

simple_usage.py: Clean, modern examples using qoery
basic_usage.py: Examples using the auto-generated client directly

Run the examples:

python examples/simple_usage.py

Testing

Run the test suite:

Documentation

API Resources

The client provides the following resources:

client.candles - OHLCV candle data
- get() / list() - Get candles
client.ticks - Raw tick/swap data
- get() / list() - Get ticks
client.pools - Pool discovery
- find() / search() / list() - Find pools
client.account - Account management
- usage() / get_usage() - Get usage stats

Data Models

All responses use clean dataclasses:

Candle - OHLCV data
Tick - Raw swap data
Pool - Pool information
Token - Token details
Usage - Usage statistics
Response - Generic response wrapper with data and credits_used

Configuration

client = qoery.Client(
    api_key="your-key",           # Or use QOERY_API_KEY env var
    base_url="https://api.qoery.com/v0",  # Custom base URL
    timeout=30                     # Request timeout in seconds
)

Advanced Usage

Using Pool Addresses (Recommended)

Using pool addresses is faster and uses fewer credits:

# Step 1: Find the best pool
pools = client.pools.find(symbol="ETH-USDC")
best_pool = pools.data[0]  # Sorted by liquidity

# Step 2: Use the pool address
candles = client.candles.get(
    pool=best_pool.id,
    interval="15m",
    limit=100
)

Time Range Queries

from datetime import datetime, timedelta

# Get candles from last 24 hours
candles = client.candles.get(
    symbol="ETH-USDC",
    interval="1h",
    from_time=datetime.now() - timedelta(days=1),
    to_time=datetime.now()
)

Multi-Network Queries

# Query specific networks
candles = client.candles.get(
    symbol="ETH-USDC",
    interval="15m",
    networks="ethereum,arbitrum,polygon"
)

Development

Project Structure

qoery-py/
├── qoery/               # Main package (clean wrapper - use this!)
│   ├── client.py        # Main client
│   ├── models.py        # Clean dataclass models
│   ├── exceptions.py    # Custom exceptions
│   ├── resources/       # Resource endpoints
│   │   ├── candles.py
│   │   ├── ticks.py
│   │   ├── pools.py
│   │   └── account.py
│   └── _internal/       # Auto-generated OpenAPI client (private)
│       ├── api/
│       ├── models/
│       └── ...
├── examples/            # Usage examples
└── docs/                # Documentation

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

Website: qoery.com
Documentation: qoery.com/docs
Issues: GitHub Issues

Made by the Qoery team