Tracking transactions

Transaction types, lifecycle statuses, and how to list them across all your accounts.

Once a transaction is created, you typically want to know what kind it is, where it sits in its lifecycle, and how to retrieve it. This page covers the types, the statuses they move through, and the endpoint for listing them.

Transaction types

Type	What it means
authorization	EIP-7702 delegation that upgrades the user’s EOA into a smart account by setting its code to the Atlas contract. After confirmation, the wallet is also whitelisted on our vaults.
approve	Standalone ERC-20 approval, granting an allowance over the user’s tokens without a deposit bundled in.
approve_deposit	Bundled ERC-20 approval and deposit in a single Atlas batch. Used the first time a user deposits an asset into a vault that has not yet been approved.
deposit	Deposit idle balance into a vault.
onramp	Convert fiat to stablecoins and receive them in the wallet. No deposit.
onramp_deposit	Convert fiat to stablecoins and deposit them into a specific vault.
withdraw	Withdraw from a vault to idle balance.
offramp	Convert idle stablecoins to fiat into a bank account. Not supported yet.
withdraw_offramp	Withdraw from a vault and convert to fiat into a bank account.
transfer	Send stablecoins from the account wallet straight to any destination wallet address on-chain, leaving the vault flow entirely. See Stablecoin transfer.

The signing window

Initiating a transaction (eg. Get withdraw payload, Get deposit payload) creates a draft transaction and returns its transaction_id together with the payload to sign. Until the signature is submitted through Sign a payload, this draft only exists internally - in a created or claimed status the API never returns. It is not listed by List all transactions or List all transactions across every account, and Get single transaction returns 404 Not Found for its ID.

Draft transactions are also ephemeral. At most one unsigned draft exists per account: initiating a new transaction discards any previous unsigned draft, and its transaction_id becomes permanently invalid.

Do not persist or poll a transaction_id before Sign a payload has succeeded. Treat the ID returned at creation as valid only for the signing step that immediately follows.

Once the payload is signed, the transaction becomes visible with one of the statuses documented below (withdrawal_initiated, processing, completed, …). A 404 from Get single transaction therefore means one of three things:

• the ID never existed;
• it belonged to an unsigned draft that has been superseded by a newer one;
• the transaction is still inside the brief signing window, and will appear once signed.

Transaction statuses

The transaction status can be checked by calling the Get transaction endpoint. Only signed transactions carry a status - drafts waiting to be signed are not returned by the API at all, as described in the signing window above.

Onramp deposit statuses

• waiting_for_funds - The transaction has been signed. The system is waiting for the bank transfer to trigger the broadcasting of the transaction.
• funds_in_transfer - The funds have been scheduled to arrive with Bridge soon.
• processing - The funds have arrived with Bridge and are currently being on-ramped. The transaction is being broadcasted.
• completed - The transaction has been broadcasted and executed. The funds have been transferred to the vault.

Offramp withdrawal statuses

• processing - The transaction is being broadcasted.
• waiting_for_funds - On-chain receipt confirms - assets landed at liquidation address, waiting for Bridge to pick them up.
• funds_in_transfer - Bridge has picked up the assets and is in the process of converting them to fiat.
• completed - Fiat funds have been transferred to the user’s bank account.

Queued withdrawal statuses

A withdrawal that a vault cannot serve immediately is placed in the vault’s withdrawal queue instead of being broadcast straight away. Sign a payload then answers 202 Accepted rather than 200 OK, and the transaction carries an extra withdrawalRequest object.

• withdrawal_initiated - The withdrawal has been signed and queued. It has not left the vault yet.
• cancelled - The queued withdrawal was cancelled before it settled.

withdrawalRequest describes the queue entry itself:

• requestId - UUID of the queued withdrawal request.
• status - pending, settled, or cancelled.

See Withdrawing from a vault for the full flow, including how to cancel a queued withdrawal.

Retrieving transactions

Three endpoints are available depending on what you need: a single transaction by ID, all transactions for one account, or every transaction across all your accounts.

Single transaction

Get single transaction returns one transaction by its ID.

Query parameters

• transaction_id - UUID of the transaction.

You can use this to poll the status of a specific transaction (deposit, withdrawal, etc.) after the user has signed it.

By account

List all transactions returns every active transaction for a specific account. Transactions still in an internal status (created, claimed) are excluded.

Query parameters

• account_id - UUID of the account.

Across all accounts

List all transactions across every account returns every active transaction across all your accounts, paginated. Transactions still in an internal status (created, claimed) are excluded.

Query parameters

• limit - page size, clamped to [1, 100]. Defaults to 20.
• offset - number of records to skip. Defaults to 0.
• order - sort direction over updatedAt. desc (default) returns the most recently updated first; asc returns the oldest first.

Response

{
  "transactions": [ /* TransactionView, ... */ ],
  "total":  8753,
  "limit":  20,
  "offset": 0
}

total is the total number of active transactions across all your accounts.