Cancel a Pending Settlement and Stop Transfer Watching

Cancel a settlement expectation that is still in the PENDING state. Once cancelled, Idem stops watching for the transfer. Cancellation is permanent and cannot be undone.

Endpoint

DELETE /api/v1/settlements/{id}

Authorization

Requires an API key with the TRANSACTIONS_WRITE scope.

Path Parameters

string

required

The UUID of the settlement to cancel.

Request Example

curl -X DELETE "https://api.your-domain.com/api/v1/settlements/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $IDEM_API_KEY"

Response

Returns 200 OK with the full updated settlement object (same shape as Get Settlement) showing status: CANCELLED. Cancellation does not set a dedicated timestamp field — confirmedAt stays null and expiresAt is dropped once the settlement leaves PENDING.

{
  "settlementId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "expectedToken": "USDC",
  "expectedAmount": "250.00",
  "expectedWalletAddress": "0xYourCustodialWallet...",
  "expectedChainId": "EVM",
  "expectedFromAddress": null,
  "status": "CANCELLED",
  "matchedTransactionId": null,
  "txHash": null,
  "blockNumber": null,
  "confirmedAt": null,
  "createdAt": "2024-01-15T09:00:00Z"
}

Error Codes

A 409 error means the settlement has already reached a terminal state (SETTLED or UNMATCHED). Terminal settlements cannot be cancelled.

Code	Meaning
401	Missing or invalid API key
403	API key does not have `TRANSACTIONS_WRITE` scope
404	Settlement not found for this tenant
409	Settlement is already in a terminal status and cannot be cancelled

Accounts

Transactions

Settlements

Reconciliation

Compliance

Administration

Cancel a Pending Settlement and Stop Transfer Watching

Endpoint

Authorization

Path Parameters

Request Example

Response

Error Codes

​Endpoint

​Authorization

​Path Parameters

​Request Example

​Response

​Error Codes

Endpoint

Authorization

Path Parameters

Request Example

Response

Error Codes