Transfers
Transfers allow you to initiate and complete fund movements between internal or external accounts. These endpoints enable secure, auditable transfers that support multiple stages such as initiation and finalization.
Use the following endpoints to manage your transfer workflows:
Initiate Transfers
Initiates a transfer using either an internal account or an external blockchain address.
Initiate Transaction Response Payload Schema
The amount to be sent, which is in lower denomination and in the unit of the assetType (e.g., 1000 USDT or 1000 SATS)
The recipient's wallet address. The address format must be valid and match the specified blockchain network. This is required for external (on-chain) transfers.
An internal unique wallet or account number within your system. Used for transferring funds to another wallet under your platform’s infrastructure (i.e., internal transfers).
The blockchain network where the asset will be sent. Supported values include bsc, eth, polygon, etc. Only required if the transfer is on-chain (external).
The type of asset to be transferred, such as USDT, USDC, or BTC. Must match a supported asset on the selected blockchain.
A unique identifier for a previously registered user in your system. It could be an email address or user id.
Defines the type of transfer: 'internal' for transfers within your platform or 'external' for blockchain-based transfers. The choice determines whether an address or wallet number is required.
A unique transaction reference provided by the client for idempotency. This ensures repeated requests with the same reference are not processed more than once.
An optional free-text note explaining the purpose of the transaction. Useful for audits, invoices, or providing customer context.
Initiate Transaction Request Payload Schema
A unique system-generated identifier for this transaction. This ID is immutable and can be used to track or reference the transaction across systems or audits.
The timestamp indicating when the transaction was initiated. ISO 8601 format ensures consistency across systems. Example: '2025-06-19T10:22:35Z'.
Timestamp representing the last update to the transaction. This is updated when the transaction status, amount, or metadata changes.
A unique external identifier, typically provided by the client, for tracking and ensuring idempotent transaction submission.
A brief human-readable note about the transaction's purpose. Helps categorize or annotate entries in financial dashboards.
Represents the user's or company's wallet balance immediately after this transaction, in the smallest denomination (e.g., cents or satoshis).
Total transaction amount in whole or major units (e.g., 15.75 USDC). This field is used in reporting and summaries.
Same as `amount`, but expressed in minor units for precision (e.g., 1575 cents for $15.75). Useful for APIs handling raw numbers.
Fee applied to the transaction in major units. May vary by channel (onchain, internal) or network congestion.
Fee represented in smallest denomination (e.g., 99 cents = $0.99). Provides granularity for accounting.
The blockchain address that received funds. Only relevant for onchain/external transactions (e.g., 0xabc...).
Internal identifier representing the wallet or account that received funds within the system.
Describes the business logic of the transaction (e.g., 'withdraw_btc', 'send_usdt', 'payout_vendor').
Transaction direction: 'credit' means wallet received funds; 'debit' means funds were sent out.
Current state of the transaction in the lifecycle. Examples: 'initiated', 'processing', 'success', or 'failed'.
The medium or processing route used. Options: 'onchain' (blockchain), 'internal' (within platform), 'manual', 'offchain' (e.g., via 3rd party).
Specifies which blockchain was used for the transaction (e.g., 'bitcoin', 'bsc', 'polygon'). Required only for onchain transfers.
Specifies the token or cryptocurrency involved (e.g., 'USDT', 'BTC'). Determines formatting, fees, and chain compatibility.
Unique identifier of the company or business that initiated the transaction. Supports auditing and organizational filtering.
Full name of the recipient company (internal transfers only). Provides visibility in dashboards and reporting tools.
Blockchain transaction hash (txid). Can be used to verify the transaction via block explorers (e.g., etherscan, mempool).
The number of blockchain confirmations received. Used to assess finality and reliability of the transaction.
An optional memo or tag used by chains like XRP, Stellar, or Binance. Required by some exchanges to complete transfers.
Denotes whether the transaction was 'internal' (within the platform) or 'external' (onchain). Helps route the transaction properly.
A unique identifier for a previously registered user in your system. It could be an email address or user id.
Finalize Transfer
Finalize a transfer that was previously initiated. This step is typically required for transfers that need additional verification, such as 2FA, transaction PIN, or manual approval. Finalization confirms and executes the transaction, updating its status accordingly. It ensures that sensitive or high-value transfers are not processed without explicit user authorization.
Finalize Transaction Request
Use Case:
Finalize Transaction Request Payload Schema
System-generated unique ID for the transaction. Used to finalize a specific transaction.
Finalize Transaction Response Payload Schema
A system-generated globally unique identifier for the transaction, used for tracking, referencing, and resolving disputes.
The exact timestamp when the transaction was created. Format follows ISO 8601 standard for consistency across systems.
Timestamp of the most recent status or data update on the transaction. Useful for audit logs and chronological tracking.
A unique client-provided or auto-generated identifier used to trace, filter, and prevent duplicate transactions (idempotency).
Optional human-readable note or label describing the purpose of the transaction (e.g., 'Vendor payout April').
The wallet's final balance after the transaction, typically in minor units like cents or satoshis for accuracy.
The total value of the transaction in standard units, such as 100.50 for USDC or 0.01 for BTC.
The exact transaction amount represented in the smallest denomination (e.g., 1050 cents for $10.50).
The total fee charged for the transaction, expressed in standard currency units.
The transaction fee in the smallest unit of currency (e.g., 120 cents = $1.20), useful for precise calculations.
The external blockchain address to which the funds were sent. Required only for onchain or external transfers.
The internal account or wallet number that received the funds in a platform-based (internal) transfer.
Describes the transaction operation such as 'send_usdc', 'withdraw_btc', 'fund_wallet'. Helps with filtering or categorization.
Indicates whether the transaction is a 'debit' (outflow) or 'credit' (inflow) to the wallet.
The current transaction state, such as 'pending', 'processing', 'completed', or 'failed'.
Specifies the route of transfer. Valid values include 'onchain', 'internal', 'manual', and 'offchain'.
The name of the blockchain used, e.g., 'bsc' (Binance Smart Chain), 'eth' (Ethereum). Required for onchain transfers.
The digital asset involved in the transaction such as 'USDC', 'BTC', 'ETH'.
UUID of the company initiating the transaction. Useful for multi-tenant or enterprise reporting.
Name of the receiving company or entity in internal transfers. Helps with traceability and reporting.