Response format

Every /api/v1 data endpoint returns JSON in a consistent envelope. Once you understand it, you can parse any endpoint the same way.

Success envelope

A successful response always contains success, data, and meta. List endpoints add a pagination block.

{
  "success": true,
  "data": { },
  "meta": {
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-01-15T09:24:11.482Z",
    "version": "1.0.0"
  }
}

success — always true for a 2xx response.
data — the endpoint-specific payload. It is an object for single-resource endpoints and an array for list endpoints.
meta — response metadata, present on every enveloped response.

The `meta` block

Field	Type	Description
`request_id`	string	Unique identifier for this request (UUID). Use it when contacting support or correlating logs.
`timestamp`	string	Server response time, ISO 8601.
`version`	string	API version that produced the response. Currently `1.0.0`.

Request tracing

The request_id in meta is also returned as the X-Request-ID response header. You may supply your own X-Request-ID request header (it must be a valid UUID) to correlate a call across your systems and Qeychain’s; if you omit it, the server generates one.

Pagination

List endpoints (transactions, lots, and similar) add a pagination block alongside data:

{
  "success": true,
  "data": [
    {
      "lot_id": "a1b2c3",
      "symbol": "ETH",
      "chain": "ethereum",
      "status": "OPEN",
      "remaining_quantity": "1.5",
      "remaining_cost": "4500.00"
    }
  ],
  "meta": {
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-01-15T09:24:11.482Z",
    "version": "1.0.0"
  },
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 128,
    "total_pages": 3,
    "has_more": true
  }
}

Field	Type	Description
`page`	integer	Current page (1-indexed).
`per_page`	integer	Items per page.
`total`	integer or null	Total matching items. May be `null` on high-volume endpoints that skip a full count for efficiency.
`total_pages`	integer or null	Total pages. `null` when `total` is `null`.
`has_more`	boolean	Whether another page exists. Always present.

Control pagination with the page and per_page query parameters, for example ?page=2&per_page=100.

Error envelope

Errors keep the same envelope, with success: false and an error object instead of data:

{
  "success": false,
  "error": {
    "code": "INVALID_ADDRESS",
    "message": "Invalid wallet address. Supported: Ethereum (0x…), Bitcoin (bc1… / 1… / 3…), Solana.",
    "details": { "provided": "0xnothex" },
    "field": "address"
  },
  "meta": {
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-01-15T09:24:11.482Z",
    "version": "1.0.0"
  }
}

The `error` object

Field	Type	Description
`code`	string	Machine-readable error code — branch on this, not on the message.
`message`	string	Human-readable explanation.
`details`	object	Additional context. Omitted when there is none.
`field`	string	The offending field, for validation errors. Omitted when not applicable.

details and field are only present when they carry information, so treat both as optional.

HTTP status codes and error codes

HTTP	`error.code`	When it happens
400	`INVALID_REQUEST`, `VALIDATION_ERROR`, `INVALID_ADDRESS`	Malformed request, failed validation, or an unsupported wallet address.
401	`UNAUTHORIZED`	Missing, expired, or invalid credentials.
403	`FORBIDDEN`	Authenticated but not permitted.
404	`RESOURCE_NOT_FOUND`, `WALLET_NOT_FOUND`, `LOT_NOT_FOUND`	The requested resource does not exist.
429	`RATE_LIMIT_EXCEEDED`	Too many requests — slow down and retry.
500	`INTERNAL_ERROR`	Unexpected server error.
502	`DATA_PROVIDER_ERROR`, `PROVIDER_ENTITLEMENT_ERROR`	An upstream blockchain data provider failed, or rejected the request at the plan/quota level.
503	`SERVICE_UNAVAILABLE`	Temporarily unavailable.