Transactions

Every sandbox operation that touches the chain (faucet funding, mints, transfers, redemptions) writes a transaction row before submission and updates it as the chain confirms. Transactions are your audit trail and your polling target.

The transaction object

{
  "id": "cktxn0001…",
  "type": "REDEEM",
  "status": "SETTLED",
  "chainId": 11155111,
  "amount": "10.00",
  "token": "cAROUSD",
  "txHash": "0x6f2a…",
  "settlementTxHash": "0x91c4…",
  "explorerUrl": "https://sepolia.etherscan.io/tx/0x6f2a…",
  "fromAddress": "0x8Ba1…BA72",
  "toAddress": "0x52aE…9021",
  "counterparty": null,
  "walletId": "ckwlt0001…",
  "error": null,
  "metadata": { "mode": "backed" },
  "createdAt": "2026-08-13T10:02:11.000Z",
  "updatedAt": "2026-08-13T10:03:40.000Z"
}

Field	Notes
`type`	`FUND`, `MINT`, `TRANSFER`, `PRIVATE_TRANSFER`, or `REDEEM`.
`status`	See lifecycle below.
`amount` / `token`	Human-unit decimal string and the token it denominates.
`txHash`	First-leg transaction hash, once submitted.
`settlementTxHash`	Second-leg hash: redeem payout or the faucet’s stablecoin leg.
`explorerUrl`	Deep link to the block explorer for `txHash`.
`error`	Populated when `status` is `FAILED`.
`metadata`	Operation-specific context (e.g. redeem mode details).

Lifecycle

Most types go PENDING → CONFIRMED (terminal) or → FAILED.
Redeems have a second leg: PENDING → SETTLING → SETTLED, with the payout hash in settlementTxHash. See Redeem cAROUSD.

Synchronous-ish writes

Money-movement calls (/fund, /mint, /transfer, /redeem) block for up to ~90 seconds waiting for the on-chain receipt. If the receipt arrives in time you get back a CONFIRMED (or SETTLING) transaction; otherwise the call returns the transaction still PENDING, not an error.

Lazy reconciliation

There is no background cron. Transactions still in flight are reconciled whenever they are read: fetching a PENDING transaction triggers a receipt lookup, and reading a SETTLING redeem advances settlement if it can. The practical rule:

Poll GET /transactions/{id} until the status is terminal (CONFIRMED, SETTLED, or FAILED). Polling is not just how you observe progress; it’s what drives it forward.

until [ "$(curl -s "$BASE/transactions/$TX" -H "Authorization: Bearer $KEY" \
  | jq -r .data.transaction.status)" != "PENDING" ]; do
  sleep 5
done

Listing and filtering

GET /transactions returns a paginated, filterable history:

curl -s "$BASE/transactions?page=1&pageSize=20&type=REDEEM&status=SETTLED&walletId=$WALLET" \
  -H "Authorization: Bearer $KEY"

Responses carry items, page, pageSize (default 20, max 100), and total. See Track transactions for patterns.

Receipts

Once a transaction has reached the chain, GET /transactions/{id}/nota produces a notarized Notareum receipt file; see .nota files. Requesting a receipt for a transaction that can’t yet be represented (for example, one that never got a hash) returns 400.

Get started

Core concepts

Guides

Security & access

Support

The transaction object

Lifecycle

Synchronous-ish writes

Lazy reconciliation

Listing and filtering

Receipts

​The transaction object

​Lifecycle

​Synchronous-ish writes

​Lazy reconciliation

​Listing and filtering

​Receipts

The transaction object

Lifecycle

Synchronous-ish writes

Lazy reconciliation

Listing and filtering

Receipts