Skip to content
CryptonlyCryptonlyCryptonly

List x402 settlements

GET
/x402/settlements

Settlements for this tenant, newest first. A settlement is the on-chain payment itself: the token went to payTo, not to a Cryptonly balance.

Required scope: x402.list.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
page
number
default: 1 >= 1

1-indexed page number.

limit
number
default: 20 >= 1 <= 100

Items per page. Capped at 100.

status
string
Allowed values: submitted confirmed failed
from
string format: date-time

Include settlements created at or after this instant.

to
string format: date-time

Include settlements created at or before this instant.

payer
string

Payer address. Compared case-insensitively.

payTo
string

Recipient address. Compared case-insensitively.

transaction
string

Transaction hash, exact match.

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
total
required

Total number of matching rows.

number
page
required

1-indexed page number that was returned.

number
limit
required

Items per page that were returned.

number
hasMore
required

True if there is at least one more page after this one.

boolean
data
required
Array<object>
object
id
required
string format: uuid
status
required
string
Allowed values: submitted confirmed failed
network
required

CAIP-2 network id.

string
asset
required

Token contract.

string
amount
required

Atomic units of asset.

string
payer
required
string
payTo
required
string
transaction
required

Transaction hash. Empty until the settlement is broadcast.

string
errorReason
required

Set when status is failed.

string
nullable
createdAt
required
string format: date-time
confirmedAt
required
string format: date-time
nullable

Example 

{
  "data": [
    {
      "status": "submitted",
      "network": "eip155:84532",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "amount": "1000",
      "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "transaction": "0xabababababababababababababababababababababababababababababababab",
      "errorReason": null
    }
  ]
}

400

Section titled “400”

Request validation failed (e.g. missing or malformed body / query).

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

401

Section titled “401”

Missing or invalid x-tenant-api-key header. Code: exceptions.auth.invalidApiKey.

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

403

Section titled “403”

Request origin IP is not on the tenant API allowlist (exceptions.auth.ipNotAllowed), or the API key is missing the scope required by this operation (exceptions.auth.insufficientScope).

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

429

Section titled “429”

Rate limit exceeded for this endpoint. Retry after the window resets. Code: exceptions.rateLimit.exceeded. The extension.msBeforeNext field tells you how long to wait.

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

500

Section titled “500”

Unexpected server error. Safe to retry idempotent operations after a backoff.

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}