Requests and responses - Quoin Data

Requests

Base URL: https://portal.quoindata.com/api/v4
Method: every endpoint is GET. Parameters go in the path or query string.
Auth: Authorization: Bearer <API key>. See Authentication.
Idempotency: send Idempotency-Key on billable calls. See Idempotency.
Encoding: URL-encode query values, especially q and filter. curl -G --data-urlencode does it for you.

Unknown query parameters are rejected with 400 invalid_request, so typos surface immediately.

Response envelope

Every response, success or error, has the same shape:

{
  "contract_version": "quoin-v4",
  "operation": "records",
  "request_id": "7d3f0c52-1b8e-4c0a-9a43-2f3c7b0f6a11",
  "status": "ok",
  "data": {
    "q_id": "addr_01a12e0d-2ece-77ad-b5b0-430ab9658f29",
    "items": [],
    "next_cursor": "eyJhZnRlciI6InJlY18uLi4ifQ"
  },
  "error": null,
  "meta": {
    "served_at": "2026-10-13T12:00:00.000Z",
    "next_cursor": "eyJhZnRlciI6InJlY18uLi4ifQ"
  }
}

Field	Meaning
`contract_version`	Always `quoin-v4` for this API
`operation`	The endpoint that ran
`request_id`	Your `Idempotency-Key`, or a generated id. Include it when you contact support
`status`	`ok` or `error`
`data`	The result. `items` holds the rows; single-entity calls also echo `q_id` or `record_ref`
`error`	`null` on success; otherwise `code`, `message` and `retryable`. See Errors
`meta.next_cursor`	Present when more results exist. See Pagination

Responses are capped at 256 KiB. Larger results return 422 response_too_large; lower limit.

Response headers

Header	Meaning
`X-Quoin-Charged-Micro-USD`	Amount charged for this call, in millionths of a dollar. `0` for free calls and replays
`X-Quoin-Balance-Micro-USD`	Remaining account credit, in millionths of a dollar
`X-Quoin-Replayed`	`true` when this is a stored replay of an earlier call with the same `Idempotency-Key`
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`	Per-minute rate limit state. See Rate limits
`X-Quoin-API-Version`	`quoin-v4`