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

# Wallet Transactions

> Reconciling deposits, fees, adjustments, refunds, and withdrawals.

Use wallet transaction reads to reconcile account activity across fiat deposits, stablecoin deposits, fees, adjustments, refunds, and withdrawals initiated through the API or Stabyl Pro.

| Endpoint                                 | Purpose                                   |
| ---------------------------------------- | ----------------------------------------- |
| `GET /partner/wallets/transactions`      | List wallet activity                      |
| `GET /partner/wallets/transactions/{id}` | Read one transaction by public identifier |

The timeline can include deposits, fees, adjustments, refunds, and withdrawals. Use transaction `id` as the stable public identifier.

Use `rail`, `currency`, and `settlement_rail` to distinguish NGN fiat, USD cash, USDT, and USDC activity.

## Required Actions

Some crypto deposits may be confirmed on-chain but unavailable until additional
Travel Rule information is submitted through the partner API. These rows keep
`status: "hold"` and include `required_action`:

```json theme={null}
{
  "type": "travel_rule",
  "status": "required",
  "submission_url": "/partner/wallets/crypto/deposits/019bd2d1-4e10-77ab-88d4-93f43d6a6df2/travel-rule"
}
```

Call `GET` on `submission_url` to retrieve the required fields and `POST` to the
same path to submit sender information. `required_action.status` changes to
`submitted` after a successful submission and before the deposit is credited.
Once credited, `required_action` is omitted.

## Listing Transactions

```bash theme={null}
curl "https://api-staging.stabyl.com/v1/partner/wallets/transactions?currency=USD&limit=50" \
  -H "X-Api-Key: $STABYL_API_KEY"
```

Use cursor pagination for backfills. Do not assume a page boundary is stable while new activity is happening; store the highest processed transaction timestamp and transaction ID in your own reconciliation job.

## Reading One Transaction

```bash theme={null}
curl https://api-staging.stabyl.com/v1/partner/wallets/transactions/0198b755-a2a2-76ee-9f4f-a650cd51586c \
  -H "X-Api-Key: $STABYL_API_KEY"
```

Use the detail route when an operator opens a record, when a reconciliation job finds a gap, or when your system needs to refresh the status of a known transaction.

## Status Handling

| Status     | Meaning                                                                       |
| ---------- | ----------------------------------------------------------------------------- |
| pending    | Activity is known but not final                                               |
| processing | Activity is progressing and is not final                                      |
| hold       | Activity is blocked by compliance or a required action                        |
| success    | Activity completed successfully and any resulting balance update is available |
| failed     | Activity did not complete                                                     |
| cancelled  | Activity was cancelled before completion                                      |

Treat `success`, `failed`, and `cancelled` as terminal. A transaction can move
from `pending`, `processing`, or `hold` to a terminal status.

## Reconciliation Pattern

1. Process deposit and withdrawal webhooks as the primary source of timely changes.
2. Upsert transactions by public `id`; a later status updates the existing record.
3. Run a cursor-based reconciliation job periodically and after webhook downtime.
4. Use the detail endpoint for operator lookups and targeted gap recovery, not continuous polling.
5. Keep transaction IDs, webhook event IDs, and timestamps in your support logs.

## Required Headers

Transaction reads require `X-Api-Key` enabled for wallet reads.

Common failures include invalid filters, requesting a transaction outside the account context, or querying a transaction before it appears in the timeline.