Tracking transactions

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
Offramp withdrawal statuses
Queued withdrawal 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.

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.

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.

Lifecycle events, review, and refunds

The public payment_in_review status means a payment is under review; do not treat it as funding completion. refunded means the payment was refunded. Other observable statuses include funds_received, simulation_failed, and reverted; transactions do not necessarily visit every status. Transaction webhooks now emit version 2 events for observable status transitions, including review, refunds, and cancellation. Read the current summary from data.transaction and its previous observable status from data.previousStatus (which can be null). Continue accepting the original version on retried historical deliveries.

Retrieving transactions

The lookup query keys below are transactionId and accountId (camelCase), as already defined in the previous OpenAPI. This is a correction to the handwritten guide, not a new API parameter rename.

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
By account
Across all accounts

Get single transaction returns one transaction by its ID.Query parameters

transactionId - 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.

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

accountId - UUID of the account.

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.

Integrator API

API endpoints

Transaction types

The signing window

Transaction statuses

Lifecycle events, review, and refunds

Retrieving transactions

​Transaction types

​The signing window

​Transaction statuses

​Lifecycle events, review, and refunds

​Retrieving transactions

Transaction types

The signing window

Transaction statuses

Lifecycle events, review, and refunds

Retrieving transactions