Skip to main content
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. 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:
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

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

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

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.