Skip to content

Every list route in the API — /pools, /pairs, /candles and /prices/history — now pages with the same cursor and limit parameters and the same opaque cursor shape that /screener already used, backed by keyset pagination so rows inserted while a client pages can never shift a page boundary, with all defaults and maxima documented per route in openapi.yaml and the behaviour locked down by tests including one that inserts a row mid-page. #429

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DevScoopee wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Every list route in the API — /pools, /pairs, /candles and /prices/history — now pages with the same cursor and limit parameters and the same opaque cursor shape that /screener already used, backed by keyset pagination so rows inserted while a client pages can never shift a page boundary, with all defaults and maxima documented per route in openapi.yaml and the behaviour locked down by tests including one that inserts a row mid-page. #429

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
90e33e8
Every list route in the API — /pools, /pairs, /candles and /prices/hi…
DevScoopee Oct 17, 2026
3eec8fd
Merge branch 'main' into Only-/screener-can-be-paged
DevScoopee Oct 18, 2026
281bce5
Merge branch 'main' into Only-/screener-can-be-paged
DevScoopee Oct 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 161 additions & 14 deletions openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -514,6 +514,7 @@
"get": {
"operationId": "getPools",
"summary": "Get AMM liquidity pool reserves and spot prices",
"description": "Latest snapshot per pool for one network. Paginated with the shared keyset convention: ordered by pool_id ascending, default limit 50, maximum 200.",
"security": [
{
"x402": []
Expand All @@ -522,6 +523,21 @@
"parameters": [
{
"$ref": "#/components/parameters/NetworkQuery"
},
{
"$ref": "#/components/parameters/CursorQuery"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Page size. Out-of-range values are clamped into [1, 200].",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
}
],
"responses": {
Expand All @@ -536,6 +552,11 @@
"application/json": {
"schema": {
"type": "object",
"required": [
"pools",
"nextCursor",
"hasMore"
],
"properties": {
"pools": {
"type": "array",
Expand Down Expand Up @@ -569,12 +590,22 @@
}
}
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"hasMore": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"description": "Invalid limit or cursor"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
Expand All @@ -588,6 +619,7 @@
"get": {
"operationId": "getCandles",
"summary": "Get OHLCV candle data",
"description": "OHLCV candles for a pair. Paginated with the shared keyset convention: ordered by bucket start time ascending, default limit 500, maximum 5000.",
"security": [
{
"x402": []
Expand Down Expand Up @@ -644,6 +676,21 @@
"type": "string",
"format": "date-time"
}
},
{
"$ref": "#/components/parameters/CursorQuery"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Page size. Out-of-range values are clamped into [1, 5000].",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 5000,
"default": 500
}
}
],
"responses": {
Expand All @@ -658,6 +705,15 @@
"application/json": {
"schema": {
"type": "object",
"required": [
"pairKey",
"interval",
"from",
"to",
"candles",
"nextCursor",
"hasMore"
],
"properties": {
"pairKey": {
"type": "string"
Expand All @@ -666,10 +722,12 @@
"type": "string"
},
"from": {
"type": "string"
"type": "string",
"format": "date-time"
},
"to": {
"type": "string"
"type": "string",
"format": "date-time"
},
"candles": {
"type": "array",
Expand Down Expand Up @@ -697,6 +755,13 @@
}
}
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"hasMore": {
"type": "boolean"
}
}
}
Expand All @@ -719,7 +784,7 @@
"get": {
"operationId": "getPriceSnapshots",
"summary": "Get historical 1-minute price snapshots",
"description": "Returns minute-resolution price snapshots for a pair over [from, to], optionally aggregated into 5m or 1h buckets. Snapshots are retained for ~30 days. Gated by x402 (matches the /price prefix).",
"description": "Returns minute-resolution price snapshots for a pair over [from, to], optionally aggregated into 5m or 1h buckets. Snapshots are retained for ~30 days. Paginated with the shared keyset convention: ordered by bucket start time ascending, default limit 1000, maximum 10000 points. With format=csv the pagination envelope travels in the X-Next-Cursor and X-Has-More response headers; with format=json it is in the body. Gated by x402 (matches the /price prefix).",
"security": [
{
"x402": []
Expand Down Expand Up @@ -781,16 +846,44 @@
"default": "json"
}
},
{
"$ref": "#/components/parameters/CursorQuery"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Page size (number of buckets). Out-of-range values are clamped into [1, 10000].",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"default": 1000
}
},
{
"$ref": "#/components/parameters/NetworkQuery"
}
],
"responses": {
"200": {
"description": "Historical price snapshots",
"description": "Historical price snapshots. When more buckets exist beyond this page, the response carries X-Next-Cursor (pass it back as ?cursor=) and X-Has-More: true.",
"headers": {
"Cache-Control": {
"$ref": "#/components/headers/CacheControl"
"X-Next-Cursor": {
"description": "Opaque cursor for the next page; absent on the last page.",
"schema": {
"type": "string"
}
},
"X-Has-More": {
"description": "'true' when another page exists, 'false' otherwise.",
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
}
}
},
"content": {
Expand All @@ -803,6 +896,17 @@
"application/json": {
"schema": {
"type": "object",
"required": [
"pair",
"network",
"interval",
"from",
"to",
"count",
"points",
"nextCursor",
"hasMore"
],
"properties": {
"pair": {
"type": "string"
Expand All @@ -826,7 +930,8 @@
"format": "date-time"
},
"count": {
"type": "integer"
"type": "integer",
"description": "Number of points in this page (not the total across pages)."
},
"points": {
"type": "array",
Expand All @@ -845,6 +950,13 @@
}
}
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"hasMore": {
"type": "boolean"
}
}
}
Expand All @@ -867,10 +979,26 @@
"get": {
"operationId": "listPairs",
"summary": "List all active trading pairs",
"description": "Active trading pairs with their latest price metadata. Paginated with the shared keyset convention: ordered by pairKey ascending, default limit 50, maximum 200.",
"security": [],
"parameters": [
{
"$ref": "#/components/parameters/NetworkQuery"
},
{
"$ref": "#/components/parameters/CursorQuery"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Page size. Out-of-range values are clamped into [1, 200].",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
}
],
"responses": {
Expand All @@ -885,6 +1013,11 @@
"application/json": {
"schema": {
"type": "object",
"required": [
"pairs",
"nextCursor",
"hasMore"
],
"properties": {
"pairs": {
"type": "array",
Expand All @@ -911,12 +1044,22 @@
}
}
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"hasMore": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"description": "Invalid limit or cursor"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
Expand Down Expand Up @@ -1572,18 +1715,13 @@
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor returned as `nextCursor` by the previous page.",
"schema": {
"type": "string"
}
"$ref": "#/components/parameters/CursorQuery"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Page size. Out-of-range values are clamped into [1, 100].",
"schema": {
"type": "integer",
"minimum": 1,
Expand Down Expand Up @@ -2208,6 +2346,15 @@
],
"default": "testnet"
}
},
"CursorQuery": {
"name": "cursor",
"in": "query",
"required": false,
"description": "Opaque cursor returned as `nextCursor` by the previous page. Every list route uses the same keyset-cursor convention: pass it unchanged to fetch the next page; rows inserted while paging never shift a page boundary. An invalid cursor is rejected with 400.",
"schema": {
"type": "string"
}
}
},
"responses": {
Expand Down
Loading
Loading