Base URL

All API requests use the following base URL:

https://kwery-api.com/v1

All endpoints are under this prefix (e.g., https://kwery-api.com/v1/candles).

Authentication

Authenticate every request with your API key. Recommended: use the X-API-Key header so the key never appears in URLs or logs:

X-API-Key: kwery_live_abc123

You can also pass the key as a query parameter (api_key=kwery_live_abc123) for quick tests; the header takes priority if both are present. See Authentication for key format and security practices.

Example with header:

curl "https://kwery-api.com/v1/candles?symbol=BTCUSDT&source=binance&interval=1h" \
  -H "X-API-Key: kwery_live_YOUR_KEY"

Response Envelope

Every successful response (200 OK) follows this structure:

{
  "data": [
    { "open_time": "2025-01-15T12:00:00Z", "open": 99250.10, "high": 99480.00, "low": 99100.55, "close": 99350.75, "volume": 1234.5678 },
    { "open_time": "2025-01-15T11:00:00Z", "open": 99050.00, "high": 99300.20, "low": 98980.30, "close": 99250.10, "volume": 987.6543 }
  ],
  "meta": {
    "symbol": "BTCUSDT",
    "source": "binance",
    "interval": "1h",
    "count": 2,
    "next_cursor": null
  }
}

• data — Array of result objects. Always present, even if empty ([]).
• meta.symbol — The symbol queried.
• meta.source — The data source.
• meta.interval — The interval used (when applicable).
• meta.count — Number of rows in data.
• meta.next_cursor — Opaque pagination cursor. null when no more results exist. Pass as ?after= to fetch the next page.

Error Format

Error responses use a consistent JSON structure:

{
  "error": "invalid_parameter",
  "message": "Parameter 'interval' must be one of: 1s, 5m, 15m, 1h, 4h, 24h, 1d."
}

Some errors include additional fields:

{
  "error": "plan_required",
  "message": "Order book snapshots require a Pro plan or higher.",
  "required_tier": "pro",
  "upgrade_url": "https://kwery.xyz/dashboard/billing"
}

• error — Machine-readable error code.
• message — Human-readable explanation.
• required_tier — (Optional) The minimum plan needed for the requested feature.
• upgrade_url — (Optional) Direct link to upgrade your plan.

HTTP Status Codes

Content Type

All responses are application/json with UTF-8 encoding.

Timestamps

All timestamps in request parameters and response bodies use UTC ISO 8601 format:

2025-01-15T12:00:00Z