Redeem cAROUSD

Redeeming is the exit from the confidential rail: cAROUSD is burned and the same amount of public test stablecoin is paid back to your wallet. Unlike the other operations, redemption is two-legged: the burn and the payout are separate on-chain transactions, both driven by the background worker.

Make the call

curl -s "$BASE/redeem" \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d "{\"walletId\":\"$WALLET\",\"amount\":\"10\"}"

{
  "ok": true,
  "data": {
    "transaction": {
      "id": "cktxn0004…",
      "type": "REDEEM",
      "status": "QUEUED",
      "amount": "10.00",
      "token": "cAROUSD",
      "txHash": null,
      "settlementTxHash": null,
      "explorerUrl": null,
      "error": null,
      "errorCode": null,
      "walletId": "ckwlt0001…",
      "createdAt": "2026-08-13T10:02:11.000Z",
      "updatedAt": "2026-08-13T10:02:11.000Z"
    }
  }
}

Requirements mirror the other spending calls: a custodial wallet, enough cAROUSD, ETH for gas, and amount as a decimal string. The 201 means the redeem is validated and queued; everything after that happens in the background.

The two legs

Leg 1 (burn). The worker checks your decrypted cAROUSD balance, then signs and broadcasts the burn; the cAROUSD leaves your confidential balance and txHash is set. In backed mode the burned amount is then publicly decrypted (that single value becomes public, a requirement of verifiable payout); in float mode the funds move to the operator confidentially.
Leg 2 (payout). Once the burn confirms (SETTLING), the operator pays stablecoin 1:1 to your wallet. Its transaction hash lands in settlementTxHash, and the row becomes SETTLED.

Status flows QUEUED → PENDING → SETTLING → SETTLED. FAILED is terminal and only reachable before anything moved on-chain: a failed pre-flight check while QUEUED, or a reverted burn while PENDING, with the reason in error and errorCode. Once the burn has confirmed, the row stays SETTLING until the payout lands; it is never failed with your cAROUSD already burned.

Poll to completion

Settlement runs in the background worker; polling only observes it. Poll until a terminal status:

TX="cktxn0004…"
while true; do
  STATUS=$(curl -s "$BASE/transactions/$TX" -H "Authorization: Bearer $KEY" \
    | jq -r .data.transaction.status)
  echo "$STATUS"
  case "$STATUS" in CONFIRMED|SETTLED|FAILED) break;; esac
  sleep 5
done

Backed-mode settlement waits for the Zama KMS to publish the public decryption of the burned amount, so SETTLING normally lasts a little longer than a plain confirmation; the worker re-checks every 30 seconds. A redeem that sits in SETTLING for much longer usually means the decryption is delayed or the operator is short of gas or liquidity; both are platform-side. See Troubleshooting.

Failure modes

Request problems fail the POST; execution problems fail the transaction row later (status: "FAILED" with error and errorCode), and a failed redeem never burned anything.

Response	Meaning
`400 validation_error` / `invalid_amount`	Bad amount.
`400 wallet_not_custodial`	`walletId` refers to an external wallet.
`404 not_found`	Unknown wallet.
`503 fhe_*`	The confidential rail is not configured on this deployment; nothing was queued.
`FAILED` with `errorCode: "insufficient_confidential_balance"`	The decrypted cAROUSD balance (minus other queued debits) cannot cover `amount`. The worker re-checks for a few minutes before failing.
`FAILED` with `errorCode: "redeem_failed"`	The burn/request leg reverted on-chain.

There is no redeem_settlement_failed any more: a payout that cannot be sent yet keeps the row in SETTLING and is retried, never failed. Once settled, grab the notarized receipt with GET /transactions/{id}/nota; it reflects both legs.

Get started

Core concepts

Guides

Security & access

Support

Redeem cAROUSD

Make the call

The two legs

Poll to completion

Failure modes

​Make the call

​The two legs

​Poll to completion

​Failure modes

Make the call

The two legs

Poll to completion

Failure modes