Register a Settlement Expectation for Wallet Watching

Register a settlement expectation to tell Idem which wallet address to watch for an incoming stablecoin transfer. Once registered with PENDING status, Idem monitors the specified chain and automatically reconciles the settlement when the transfer is detected.

Endpoint

POST /api/v1/settlements

Authorization

Requires an API key with the TRANSACTIONS_WRITE scope.

Headers

string

required

A client-generated unique key (max 255 characters) that prevents duplicate settlement registration on retries.

Request Body

string

required

UUID of the account that will receive the on-chain transfer.

string

required

The stablecoin token identifier to watch for (e.g. USDC, USDT). Must be a non-empty string.

string

required

Expected transfer amount as a string (e.g. "100.00").

string

required

The wallet address to watch for the incoming transfer.

string

required

The chain to monitor. One of: EVM, SOLANA, TRON.

string

Optional expected sender wallet address. When provided, Idem only matches transfers from this specific address (sender-confirmed matching).

Request Example

curl -X POST https://api.your-domain.com/api/v1/settlements \
  -H "Authorization: Bearer $IDEM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stl-expect-001" \
  -d '{
    "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "expectedToken": "USDC",
    "expectedAmount": "250.00",
    "expectedWalletAddress": "0xYourCustodialWallet...",
    "expectedChainId": "EVM",
    "expectedFromAddress": "0xSenderWallet..."
  }'

Response

string

UUID of the registered settlement expectation.

string

Initial status is always PENDING.

string

ISO-8601 timestamp after which an unmatched PENDING settlement is considered expired. Only present while the settlement is PENDING.

string

ISO-8601 creation timestamp.

The response also echoes back accountId, expectedToken, expectedAmount, expectedWalletAddress, expectedChainId, and expectedFromAddress, plus matchedTransactionId, txHash, blockNumber, and confirmedAt — all null until the settlement matches (see Get Settlement for their meaning once populated).

Response Example

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

Error Codes

Code	Meaning
400	Missing/invalid `Idempotency-Key`, malformed body, or invalid token/chainId
401	Missing or invalid API key
403	API key does not have `TRANSACTIONS_WRITE` scope
409	Duplicate `Idempotency-Key` for an in-progress registration
422	Account not found for this tenant

Accounts

Transactions

Settlements

Reconciliation

Compliance

Administration

Register a Settlement Expectation for Wallet Watching

Endpoint

Authorization

Headers

Request Body

Request Example

Response

Response Example

Error Codes

​Endpoint

​Authorization

​Headers

​Request Body

​Request Example

​Response

​Response Example

​Error Codes

Endpoint

Authorization

Headers

Request Body

Request Example

Response

Response Example

Error Codes