Pagination

Lists page by cursor when sorted by creation and by offset when sorted by deadline, and the response tells you which by returning only the relevant one.

{
  "object": "list",
  "data": [],
  "has_more": true,
  "sort": "deadline",
  "next_offset": 25,
  "next_cursor": null
}

The envelope

Field	Meaning
`object`	Always `"list"`.
`data`	The page.
`has_more`	Whether another page exists.
`sort`	Which ordering produced this page.
`next_offset`	Offset for the next page, or null.
`next_cursor`	Cursor for the next page, or null.

Exactly one of next_offset and next_cursor is ever non-null, and which one depends on sort. Read sort and follow the matching field rather than guessing.

sort=deadline is the default, because a warrant is a clock and the thing you usually want is what expires soonest. Warrants with no deadline sort last: a null is the absence of pressure, not infinite pressure.

Deadline order is offset-paged. Two warrants can share a deadline, so there is no single column that uniquely and stably orders them — a cursor would need one, and inventing a tiebreak would silently drop rows at page boundaries.

sort=created is cursor-paged on the id. Ids are ULIDs, which sort by creation time, so the cursor is exact and stable even while rows are being inserted.

Offset paging is not stable under writes

Under sort=deadline, a warrant settling between two requests shifts everything after it. That is acceptable for working a queue, which is what the console does, and wrong for an export. If you are reconciling, use sort=created and the cursor.

Parameters

Parameter	Applies to	Default	Notes
`sort`	both	`deadline`	`deadline` or `created`.
`limit`	both	25	1 to 100.
`offset`	`sort=deadline`	0	Ignored otherwise.
`starting_after`	`sort=created`	—	A warrant id.
`ending_before`	`sort=created`	—	A warrant id.

GET /v1/warrants?sort=created&limit=2 HTTP/1.1
Host: api.gowarrant.xyz
Authorization: Bearer wr_test_8f0c1b4e2b1a4d599d0e3a2f7c1b9e44

200

{
"object": "list",
"data": [
  {
    "id": "wrt_01J8Z3M4YQ7K2V9XABCDEFGHJK",
    "object": "warrant",
    "state": "held",
    "version": 1,
    "amount": "8400000",
    "asset": "USDC",
    "released_bps": null,
    "payee": "api.exampledata.io",
    "spec_hash": "b1946ac92492d2347c6235b4d2611184",
    "spec": { "clauses": [{ "kind": "http.status", "equals": 200 }] },
    "agent_id": null,
    "verifier_id": null,
    "policy_id": null,
    "policy_version": null,
    "deadline": "2026-08-16T12:00:00.000Z",
    "opened_at": "2026-08-15T12:00:00.000Z",
    "settled_at": null,
    "created_at": "2026-08-15T12:00:00.000Z"
  }
],
"has_more": true,
"sort": "created",
"next_offset": null,
"next_cursor": "wrt_01J8Z3M4YQ7K2V9XABCDEFGHJK"
}

curl -sS "https://api.gowarrant.xyz/v1/warrants?sort=created&limit=2" \
-H "Authorization: Bearer $WARRANT_API_KEY"

Then pass it forward:

curl -sS "https://api.gowarrant.xyz/v1/warrants?sort=created&limit=2&starting_after=wrt_01J8Z3M4YQ7K2V9XABCDEFGHJK" \
  -H "Authorization: Bearer $WARRANT_API_KEY"

Stop when has_more is false. Do not stop on an empty data array alone, and do not keep going while a cursor is merely non-null — has_more is the authority.

Amounts inside a page

Unchanged by paging: integer strings of the asset's smallest unit, ^[0-9]+$.

"8400000"    8.40 USDC
8400000      rejected — a JSON number
"8.40"       rejected — not the smallest unit

Pagination

The envelope

Why there are two

Parameters

Amounts inside a page

On this page