K-Line API — Introduction

Service overview

Service overview

The K-Line API is a K-line data service. It provides these core capabilities:

• Query historical OHLCV candlestick data for a pool
• Dynamically subscribe to real-time K-line updates through WebSocket
• Query market data, top holders, and token metadata

All HTTP APIs are mounted under the /kline/api/v1 prefix. Public endpoints use the X-API-Key request header for API authentication and billing identification.

---

Base URL

Use the following production host as the root path for all API requests:

https://api.gelabs.org

Example:

curl -H "X-API-Key: $API_KEY" "https://api.gelabs.org/kline/api/v1/kline/ohlcv?interval=1h&from=1776679200&to=1776765600&chain_type=evm&chain_id=1&pool_address=0xabc123def456"

---

Unified response shape

Most successful HTTP APIs return:

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Field	Type	Always returned	Description
code	integer	Yes	Business status code. 0 means success.
message	string	Yes	Response message. Successful responses use ok.
data	object / array / string	Yes	Business payload. Shape depends on the endpoint.

Failed responses usually look like:

{
  "code": 10001,
  "message": "Invalid query params",
  "error": {
    "type": "ValidationError",
    "details": {
      "formErrors": [],
      "fieldErrors": {
        "chain_type": ["String must contain at least 1 character(s)"]
      }
    }
  }
}

---

Error codes

Code	Meaning	Common trigger
0	Success	Normal response
10001	Validation failed	Invalid query, path, or body fields
10002	Invalid argument	Value violates business rules
10003	Resource not found	Unknown route or resource
10004	Resource conflict	Creating a duplicate pool
10005	Bad request	WebSocket preflight or malformed request
20001	Unauthenticated	Reserved, currently not enabled
20002	Forbidden	Reserved, currently not enabled
60001	K-line resource not found	Querying a missing pool
60002	K-line sync failed	Reserved
60003	Invalid symbol	Reserved
60004	Invalid interval	Reserved
99001	Internal server error	Uncaught exception, service error, or rate limit
99002	Database error	Reserved
99003	Cache error	Reserved

---

Common conventions

Item	Description
Common request header	All public endpoints require X-API-Key for API authentication and billing identification.
Content-Type	POST bodies use application/json; WebSocket messages use JSON text frames.
Timestamps	HTTP query parameters from and to accept Unix seconds or milliseconds. Values greater than 10000000000 are treated as milliseconds.
Chain type	chain_type is normalized to lowercase. Common aliases include eth/ethereum → evm, sol/solana → svm, trx/tron → tvm, btc/bitcoin → utxo, atom → cosmos, and sui/aptos/apt → move.
Token side	token supports base and quote; default is base.
K-line intervals	Supported intervals are 1s, 1m, 15m, 1h, 4h, 1d, 1w, 1M, and 1Y. 1w, 1M, and 1Y are aggregated from 1d data.
Pagination	Request fields use page and page_size; response pagination uses page, pageSize, total, and totalPages.
Cache	HTTP query APIs do not currently promise a fixed Cache-Control policy. After a WebSocket subscription succeeds, the server may send the latest in-memory snapshot.

Note: 1w, 1M, and 1Y are queried by aggregating persisted 1d candles.

---

Integration flow

Recommended integration steps:

1. Call GET /kline/api/v1/kline/ohlcv to query historical K-line data.
2. Connect to GET /kline/api/v1/kline/ws and subscribe to real-time updates.

---