Retrieve an x402 settlement

GET

/x402/settlements/{id}

Required scope: x402.list.

Authorizations

• TENANT_API_KEY

Parameters

Path Parameters

id

required

string

Responses

200

Media typeapplication/json

object

data

required

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

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

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

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"
}

404

No settlement with this id belongs to the tenant.

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

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"
}