'/%3e%3cdefs%3e%3cpattern%20id='pattern0_2104_4598'%20patternContentUnits='objectBoundingBox'%20width='1'%20height='1'%3e%3cuse%20xlink:href='%23image0_2104_4598'%20transform='matrix(0.00376176%200%200%200.0172414%20-0.00219436%200)'/%3e%3c/pattern%3e%3cimage%20id='image0_2104_4598'%20width='267'%20height='58'%20preserveAspectRatio='none'%20xlink:href='data:image/png;base64,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'/%3e%3c/defs%3e%3c/svg%3e)
Transactions
The Transactions API provides access to your transaction history and account balances. Use these endpoints to retrieve detailed records of all financial activities including deposits, withdrawals, and transfers as well as realtime balance across supported currencies.
Get All Transactions
Use Case
This endpoint retrieves a paginated list of transactions, with support for filtering via query parameters. It is commonly used to list transaction histories, audit flows, or search for specific transactions across various dimensions.
Transaction Response
This is the standard shape of a transaction returned by the API.
Top-level flag indicating whether the request was processed successfully.
Top-level human-readable status message describing the outcome of the request.
Envelope containing the paginated transactions list and pagination cursors.
The page of transaction records matching the query.
Opaque base64 cursor to fetch the next page. Empty string when there are no more results.
Opaque base64 cursor to fetch the previous page. Empty string when on the first page.
Total number of transactions matching the query across all pages.
True when additional pages are available (use next_cursor to fetch them).
A unique identifier automatically generated by the system for each transaction. This is used to track and reference a specific transaction.
The account number associated with this transaction.
The currency of the transaction (e.g., 'USDT', 'USDC', 'BTC').
Specifies the type of transaction performed, e.g., 'WITHDRAWAL_INITIATED', 'DEPOSIT_CONFIRMED'.
The current state of the transaction: 'PENDING' for in-progress, 'SETTLED' for completed transactions.
The transaction amount in the smallest unit of the currency. Negative values indicate debits.
The total fee charged for the transaction in the smallest unit.
A unique reference string (system or custom-generated) used for idempotency and reliable transaction lookups.
A unique key used to ensure the transaction is not duplicated on retry. May be an empty string for system-generated records.
Identifier for an associated trade, if applicable. Empty string or null when the transaction is not tied to a trade.
Contextual details about the transaction. Shape varies by type — for blockchain deposits it includes address, chain, channel, company_id, deposit_type, explorer_url, tx_hash, original_amount, settlement_type, and is_simulated; for trade holds it includes hold_id, hold_type, order_id, order_side, side; may also carry btc_spot_price for BTC-priced legs.
The exact timestamp (ISO 8601 format) when the transaction was first recorded in the system.
The most recent timestamp (ISO 8601 format) when the transaction details were updated.
The date when the transaction value is effective (YYYY-MM-DD format).
Human-readable formatted amount with currency symbol (e.g., '-10.0 USDT').
Human-readable formatted fee with currency symbol (e.g., '1.2 USDT').
Indicates the direction of funds — 'Credit' for incoming, 'Debit' for outgoing.
Top-level request identifier useful for support and log correlation.
Top-level RFC 3339 / ISO 8601 server timestamp of when the response was generated (UTC).
Query Parameters
Use query parameters on GET /api/transactions to filter results and page through them. Pagination is cursor-based: the first request returns a next_cursor which you pass back in as the cursor parameter to fetch the next page.
Opaque base64 pagination cursor. Pass data.next_cursor from the previous response to fetch the next page, or data.previous_cursor to go back. Omit on the first request.
Maximum number of records to return per page. Default 20, max 100.
Transaction flow direction — 'credit' for incoming funds, 'debit' for outgoing.
Filter by transaction status, e.g. 'pending', 'completed', or 'failed'.
Filter by currency, e.g. 'BTC', 'USDT', 'USDC'.
Get Transaction By ID Or Reference
Use Case
Retrieve a single transaction using its UUID or reference.
You can pass either the system-generated id (UUID) or your own provided reference to retrieve the transaction. Useful for tracking or verifying transactions.
Path Parameters
A unique identifier used to fetch the transaction details. This can either be the system-generated UUID or a custom reference string provided during transaction creation. It helps ensure idempotency and traceability of transactions.
Get Transaction Sample Request By ID Or Reference
Returns a single | TransactionResponse.
Get Transaction By ID Sample Response
The response is identical to that of Transaction Response. Refer to the Transaction Response section for field explanations.
Transaction Types & States
Understanding the different transaction types and states helps you accurately track and reconcile financial activity in your system.
Transaction Types
The type field indicates the nature of the transaction. Possible values:
type | description |
|---|---|
DEPOSIT_CONFIRMED | An inbound deposit has been confirmed on-chain and credited to the account. |
DEPOSIT_DETECTED | An inbound deposit has been detected on-chain but not yet confirmed. |
DEPOSIT_PENDING | An inbound deposit is pending confirmation. |
WITHDRAWAL_INITIATED | An outbound withdrawal has been initiated and is being processed. |
WITHDRAWAL_FAILED | An outbound withdrawal has failed during processing. |
P2P_TRANSFER | A peer-to-peer transfer between accounts within the system. |
SWAP_INTERNAL | An internal swap or exchange between currencies. |
FX_REBALANCING | A foreign exchange rebalancing transaction. |
FEE_ONLY | A transaction representing only fee charges. |
REVERSAL | A reversal of a previous transaction. |
Transaction States
The state field indicates the current status of the transaction. Possible values:
state | description | terminal? |
|---|---|---|
PENDING | The transaction has been created and is awaiting processing. | No |
IN_PROGRESS | The transaction is currently being processed. | No |
SETTLED | The transaction has been completed successfully. | Yes |
FAILED | The transaction has failed and will not be processed. | Yes |
REVERSED | The transaction has been reversed after settlement. | Yes |
Typical Lifecycle
Only SETTLED, FAILED, and REVERSED are terminal — once a transaction reaches one of these, its state won't change again. Use them as checkpoints when reconciling balances or retrying webhooks.