List Settlements with Filtering and Pagination

Use this endpoint to retrieve all settlement expectations for your tenant. Filter by status to monitor pending transfers, identify unmatched settlements, or audit completed ones. Results are paginated and returned in reverse-chronological order.

Endpoint

GET /api/v1/settlements

Authorization

Requires an API key with the TRANSACTIONS_READ scope.

Query Parameters

string

Filter results by settlement status. One of: PENDING, SETTLED, UNMATCHED, CANCELLED.

string

Inclusive lower bound on createdAt. ISO-8601 datetime (e.g. 2024-01-01T00:00:00Z).

string

Inclusive upper bound on createdAt. ISO-8601 datetime.

integer

Maximum results per page. Range 1–200. Default: 50.

string

Opaque pagination cursor returned as nextCursor in the previous page’s response. Omit to start from the first page.

Request Example

# List all PENDING settlements
curl "https://api.your-domain.com/api/v1/settlements?status=PENDING&limit=20" \
  -H "Authorization: Bearer $IDEM_API_KEY"

# Paginate to the next page
curl "https://api.your-domain.com/api/v1/settlements?status=PENDING&limit=20&cursor=eyJpZCI6IjEyMyJ9" \
  -H "Authorization: Bearer $IDEM_API_KEY"

Response

array

Array of settlement objects for this page.

Show Settlement object fields

string

Settlement UUID.

string

UUID of the receiving account.

string

Expected stablecoin token.

string

Expected transfer amount.

string

Watched wallet address.

string

Chain being watched.

string

Expected sender wallet address, if provided. null otherwise.

string

PENDING, SETTLED, UNMATCHED, or CANCELLED.

string

UUID of the matched ledger transaction. null until matched.

string

On-chain hash of the matched transfer. null until matched.

integer

Block number of the matched transfer. null until matched.

string

ISO-8601 timestamp of when the settlement matched. null until matched.

string

ISO-8601 expiry timestamp. Only present while PENDING.

string

ISO-8601 creation timestamp.

string

Pass this value as the cursor query parameter to retrieve the next page. null when there are no more results.

Response Example

{
  "items": [
    {
      "settlementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "expectedToken": "USDC",
      "expectedAmount": "100.00",
      "expectedWalletAddress": "0xYourWallet...",
      "expectedChainId": "EVM",
      "expectedFromAddress": null,
      "status": "PENDING",
      "matchedTransactionId": null,
      "txHash": null,
      "blockNumber": null,
      "confirmedAt": null,
      "expiresAt": "2024-01-16T09:00:00Z",
      "createdAt": "2024-01-15T09:00:00Z"
    }
  ],
  "nextCursor": null
}

Error Codes

Code	Meaning
400	Invalid `status` value, invalid date range, or malformed cursor
401	Missing or invalid API key
403	API key does not have `TRANSACTIONS_READ` scope

Accounts

Transactions

Settlements

Reconciliation

Compliance

Administration

List Settlements with Filtering and Pagination

Endpoint

Authorization

Query Parameters

Request Example

Response

Response Example

Error Codes

​Endpoint

​Authorization

​Query Parameters

​Request Example

​Response

​Response Example

​Error Codes

Endpoint

Authorization

Query Parameters

Request Example

Response

Response Example

Error Codes