> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aropay.aro.media/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions

> The transaction object, its lifecycle from PENDING to terminal states, and how lazy reconciliation keeps statuses current.

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

```json theme={null}
{
  "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

```mermaid theme={null}
stateDiagram-v2
  direction LR
  [*] --> PENDING : submitted
  PENDING --> CONFIRMED : receipt success
  PENDING --> FAILED : reverted / submission error
  PENDING --> SETTLING : redeem request confirmed
  SETTLING --> SETTLED : stable paid out
  CONFIRMED --> [*]
  SETTLED --> [*]
  FAILED --> [*]
```

* **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](/guides/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:

<Tip>
  **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.
</Tip>

```bash theme={null}
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:

```bash theme={null}
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](/guides/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](/concepts/nota-files). Requesting a receipt for a transaction
that can't yet be represented (for example, one that never got a hash) returns
`400`.