List transfers
Returns deposits and withdrawals for a wallet. Transfers are sorted
in descending order by height, then id. Transfers with rejected
and pendingApproval states are excluded by default.
Path Params
-
coinstring requiredA cryptocurrency or token ticker symbol. -
walletIdstring requiredThe wallet ID.
Query Params
-
allTokensbooleanInclude data for all subtokens (i.e. ERC20 Tokens, Stellar Tokens) -
dateGtestring date-timeReturn transfers with adatethat is greater than or equal to the given timestamp -
dateLtstring date-timeReturn transfers with adatethat is less than the given timestamp -
heightstringThe block or ledger height -
limitintegerMaximum number of results to return. If the result set is truncated, use thenextBatchPrevIdvalue to get the next batch. -
prevIdstringReturn the next batch of results, based on thenextBatchPrevIdvalue from the previous batch. -
statearray of string enumsThe status of the transfer. •confirmedindicates the transaction is confirmed on chain. •failedindicates the transaction failed.initializedis the first state of a transaction and indicates the transaction is initialized. •pendingApprovalindicates the transaction is initialized and pending approval. •rejectedindicates the transaction was rejected by an approver. •removedindicates the transaction was reorganized from the mempool (it's still possible recieve confirmation in another block). •replacedindicates the transaction was replaced with a new transaction with higher fees. •signedindicates the transaction is signed and pending on-chain confirmation. •unconfirmedindicates the transaction is pending on-chain confirmation.confirmedfailedinitializedpendingApprovalrejectedremovedreplacedsignedunconfirmed -
typestring enumFilter on sending or receivingTransferssendreceive -
valueGteintegerReturn transfers with avaluethat is greater than or equal to the given number -
valueLtintegerReturn transfers with avaluethat is less than the given number -
sortBystring enumCustomize sort order for the transfers by specifying the sort key.heightIdid -
reversebooleanTrue, if returning results in reverse order. -
idstringFilter for a transfer by one or more transfer ids -
pendingApprovalIdstringFilter for a transfer with a matching pendingApprovalId -
addressarray of stringsReturn transfers with elements inentriesthat have anaddressfield set to this value -
includeHexbooleanInclude the raw hex data of the transaction in the response (this may be a large amount of data) -
memoIdarray of stringsReturn transfers with any of the payment identifiers in this array. Available for Stellar and EOS. -
includeRbfbooleanTrue, if including Replace-By-Fee (RBF) transfers. -
includeOperationalbooleanInclude operational transfers (channel opening/closing) in the response. Only applicable for Lightning wallets (lnbtc/tlnbtc).
Responses
200
OK
Response Body
object
-
transfersarray of objects requiredtransfers object
-
coinstring requiredA cryptocurrency or token ticker symbol. -
idstring required -
walletstring required -
enterprisestring -
txidstring requiredThe on-chain transaction id.
Go Account / OFC wallets: For
ofc_withdrawaltransfers the top-leveltxid(andnormalizedTxHash) is the internal front-transfer hash, not the on-chain transaction hash. The on-chain hash is available inmetadata[].onChainTxIdonce the transfer reaches stateconfirmed. For standardofc_deposittransfers (non-lightning) all three values are identical. For OFC lightning deposits the payment hash is inmetadata[].lightningPaymentHash;onChainTxIdis absent. -
normalizedTxHashstringA normalized form of
txidused for deduplication. For most coins this is identical totxid. For account-model coins (e.g. ETH and its tokens) it may differ fromtxidwhen the transaction is regenerated. For lightning transfers,normalizedTxHashis identical totxid(no transformation is applied).Go Account / OFC withdrawals: Like
txid, this field holds the internal front-transfer hash, not the on-chain hash. Usemetadata[].onChainTxIdfor the on-chain transaction hash. -
txidTypestring enumThe type of the transaction idtransactionHashblockHash -
heightinteger requiredThe height of the block this Transfer was confirmed in (999999999 if unconfirmed) -
heightIdstringThe unique height id of the block -
datestring date-time requiredThe date this Transfer was last updated -
confirmationsinteger requiredThe number of blocks that have been confirmed since this Transfer's block was confirmed -
typestring enum requiredDefines whether or not this Transfer was sent or received by the usersendreceive -
valueintegerThe total value (in base units) sent by this Transfer (may be approximate for ETH and other coins where amounts in base units can exceed 2^53 - 1) -
valueStringstring requiredThe total value (in base units) sent by this Transfer represented as a String -
intendedValueStringstringA string representation (in base units) of the initial value for the transfer. This is present because when a transaction fails on chain, its value is mutated to be zero. This string is immutable and will always be the intended value of the initial transfer regardless of the final state of the transaction. -
baseValueintegerThe value (in base units) sent by this transfer, excluding network fees. BitGo is deprecating this field in the future. Instead, use baseValueWithoutFees. -
baseValueStringstringThe value (in base units) sent by this transfer, excluding network fees represented as a string. BitGo is deprecating this field in the future. Instead, use baseValueWithoutFees. -
baseValueWithoutFeesintegerThe value (in base units) sent by this transfer excluding network fees. -
baseValueWithoutFeesStringstringThe value (in base units) sent by this transfer, excluding network fees, represented as a string -
feeStringstringThe Transfer's fee (in base units) represented as a String -
payGoFeeintegerThe Transfer's BitGo fee (in base units) -
payGoFeeStringstringThe Transfer's BitGo fee (in base units) represented as a String -
usdnumber requiredThe amount of USD of this Transfer (will be negative if it's a send) -
usdRatenumber requiredThe USD price at the time this Transfer was created -
statestring enum requiredThe state of the transfer. Includes the following:
confirmed: The transfer is confirmed on chain.failed: BitGo failed to confirm the transfer on chain. You must retry the transaction.initialized: The initial state when creating a transfer.pendingApproval: The transfer requires admin approval to proceed.rejected: The transfer was rejected by an admin.removed: A network re-org occurred, causing the confirmed transfer to be removed from the blockchain.replaced: The transfer was stuck due to having a low fee and was replaced by a new transfer with a higher fee.signed: The transfer was approved by an admin (if required) and then signed by BitGo.unconfirmed: The signed transaction was sent to the network, and is pending on-chain validation.
confirmedfailedinitializedpendingApprovalrejectedremovedreplacedsignedunconfirmed -
tagsarray of strings requiredThe tags to be used on this Transfer (used in Policies) -
historyarray of objects requiredAn audit log of events that have happened to the Transfer during its lifecyclehistory object
-
datestring date-timeThe date of this history object -
userstring -
actionstring enumcreatedsignedunconfirmedconfirmedapprovedcommentedremovedfailedrejected -
commentstringIf this history object is of actioncommented, this is the comment from the user
-
-
commentstring requiredA comment from the user -
vSizeintegerThe size of the transaction -
coinSpecificobject requiredTransfer fields specific to each coin type -
sequenceIdstringAsequenceIdis a unique and arbitrary wallet identifier applied to transfers and transactions at creation. It is optional but highly recommended. With asequenceIdyou can easily reference transfers and transactions—for example, to safely retry sending. Because the system only confirms one send request persequenceId(and fails all subsequent attempts), you can retry sending without the risk of double spending. ThesequenceIdis only visible to users on the wallet and is not shared publicly. -
consolidateIdstringConsolidation ID if this transfer is part of a consolidation -
txRequestIdstringAssociated transaction request ID -
goStakingRequestIdstringAssociated GO staking request ID -
subTypestring enumTransfer subtypeofc_withdrawalofc_depositofc_unstakeofc_stakeofc_book_transfer -
feeCoinstringThe coin used to pay the fee (for cross-chain transactions) -
instantbooleanWhether this is an instant transaction -
instantIdstringThe instant transaction ID if applicable -
isFeebooleanWhether this transfer represents a fee -
isRewardbooleanWhether this transfer represents a staking reward -
isUnlockbooleanWhether this transfer represents an unlock operation -
metadataarray of objectsKey-value pairs carrying additional metadata about the transfer. The same key may appear more than once.
Known keys (alphabetical). This list reflects all keys defined in the current server release; additional keys may be added in future releases without a breaking-change notice.
backingTransferBroadcastTimestamp— Timestamp (ISO 8601) at which the backing on-chain transaction was broadcast to the network.lightningPaymentHash— (OFC lightning transfers only) The Lightning Network payment hash for the transfer. Present on bothofc_withdrawalandofc_depositlightning transfers; forofc_depositlightning transfers this key is used instead ofonChainTxId.onChainTxId— (Go Account / OFC non-lightning transfers only) The on-chain transaction hash of the backing transfer. Forofc_withdrawaltransfers this key is absent while the transfer is in statesigned; it is populated once the transfer reaches stateconfirmed(i.e. once the backing on-chain transaction is confirmed). Poll untilstate === 'confirmed'before reading this field. Use this value — not the top-leveltxid— when reconciling against a block explorer or external ledger. For standardofc_deposittransfers (non-lightning) this value equals the top-leveltxid.replacedBy— Transfer ID of the transfer that replaced this entry.replaces— Transfer ID of the transfer this entry replaces.reversedBy— Transfer ID of the transfer that reversed this entry.reverses— Transfer ID of the transfer this entry reverses.rtId— Internal routed-transaction ID linking a front transfer to its backing Go Account routed transaction.stablecoinTxType— Transaction type for stablecoin transfers (e.g.mint,reward,burn).tokenizationUniquenessId— (Tokenization withdrawals only) Internal identifier used to prevent double-spends on a tokenization withdrawal. Derived from the tokenization order ID; not guaranteed to equal the order ID in rare same-merchant/same-amount/same-instant collisions.
metadata object
-
keystringThe metadata key name. See themetadataarray description for documented values. Additional keys may be present. -
valuestring
-
sendAccountingarray of objectsAccounting breakdown for send transactionssendAccounting object
-
typestring -
amountStringstring -
nOutsinteger -
amountinteger -
idstring
-
-
createdTimestring date-timeThe time this transfer was created -
approvedTimestring date-timeThe time this transfer was approved -
rejectedTimestring date-timeThe time this transfer was rejected -
signedTimestring date-timeThe time this transfer was signed -
unconfirmedTimestring date-timeThe time this transfer became unconfirmed -
confirmedTimestring date-timeThe time this transfer was confirmed -
removedTimestring date-timeThe time this transfer was removed -
commentedTimestring date-timeThe time this transfer was commented on -
failedTimestring date-timeThe time this transfer failed -
regeneratedTimestring date-timeThe time this transfer was regenerated -
replacedTimestring date-timeThe time this transfer was replaced -
replacingTimestring date-timeThe time this transfer started replacing another -
abandonedTimestring date-timeThe time this transfer was abandoned -
signedDatestring date-timeThe date this transfer was signed (legacy field) -
customerApprovedTimestring date-timeThe time this transfer was approved by the customer (trust transfers) -
idVerificationTimestring date-timeThe time identity verification was completed (trust transfers) -
trustSignedTimestring date-timeThe time this transfer was signed by trust (trust transfers) -
trustFinalApprovalTimestring date-timeThe time this transfer received final trust approval (trust transfers) -
walletLabelstringLabel of the wallet associated with this transfer -
enterpriseNamestringName of the enterprise associated with this transfer -
ellipticstringElliptic risk score information (trust transfers) -
senderInformationVerifiedbooleanWhether sender information has been verified (trust transfers) -
buildParamsmapParameters used to build the transaction -
entriesarray of objectsAn array of objects describing the change in address balances made as a result of this Transferentries object
-
addressstringAn address affected by this Transfer -
walletstringOnly visible when the user has access to the wallet -
valueintegerThe change (in base units) in the address's balance -
valueStringstringThe change (in base units) in the address's balance represented as a String -
isChangebooleanTrue if this address is a change address (only exists for UTXO coins) and if this is asentTransfer -
isPayGobooleanTrue if this address is the BitGo PayGo wallet -
tokenstringIf this is a token entry, the token's symbol -
labelstringNames of addresses given by the user. -
failedbooleantrue if this entry is failed. -
associatedNativeCoinAddressstringThe native coin receive address associated with the solana ATA address. This is currently present only for BitGo addresses. -
memostringMemo associated with this entry. Only available for STX, EOS, SOL, NEAR, and POLYX. For other coins (XLM, XRP, Cosmos-based, TON, Tempo), memo is stored at the transaction level or appended to the address. -
typestringThe type of this entry (e.g., transfer, fee, contract_call). -
nftIdstringNFT ID associated with this entry. Only present for NFT transfers. -
nftSymbolstringNFT symbol associated with this entry. Only present for NFT transfers.
-
-
usersNotifiedbooleanWhether BitGo already sent notifications to the users of the transfer wallet -
labelstringAddress labels (if any) from entries concatenated. -
replacesarray of stringsTransaction IDs that this transfer replaces. -
replacedByarray of stringsTransaction IDs that replace this transfer. -
riskIndicatorsarray of string enumsRisk indicators detected on this transfer (e.g. SELFDESTRUCT opcode). Transfers with risk indicators will not trigger webhook or email notifications.SELFDESTRUCT -
confirmationsinteger requiredThe number of blocks that have been confirmed since this Transfer's block was confirmed -
entriesarray of objectsentries object
-
labelstringIf this address was labeled by the user, this is the label
-
-
inputsarray of objectsIf this is a Transfer on a UTXO coin, the array of inputsinputs object
-
idstringThe id of the unspent in the form:<tx_index> -
addressstringThe address of this unspent -
valueinteger -
valueStringstring -
blockHeightintegerThe block this Unspent was created in -
datestring date-timeThe date this unspent was created -
coinbasebooleanTrue if this unspent came from the coinbase transaction -
walletstring -
fromWalletstring -
chainintegerThe type of this unspent's address (P2SH, P2WSH, etc...) -
indexintegerA monotonic counter used when creating new addresses -
redeemScriptstringThe Script program used to cryptographically verify spending this unspent -
witnessScriptstringThe segwit Script program used to cryptographically verify spending this unspent -
isSegwitboolean
-
-
outputsarray of objectsIf this is a Transfer on a UTXO coin, the array of outputsoutputs object
- Same shape as
Unspent.
- Same shape as
-
-
coinstring requiredA cryptocurrency or token ticker symbol. -
nextBatchPrevIdstring uuidWhen a result set is truncated, this field returns the id of the last object in the previous batch. To get the next batch of results, pass this value via theprevIdquery parameter.
400
Bad Request
Response Body
ONE OF
-
errorstring requiredHuman-readable error message -
requestIdstring requiredClient request id -
contextobjectProperties that apply to a specific error name -
namestring requiredError code
-
errorstring requiredHuman-readable error message -
requestIdstring requiredClient request id -
contextobject requiredcontext object
-
idstring
-
-
namestring enum requiredError codeInvalidWalletId
404
Not Found
Response Body
object
-
errorstring requiredHuman-readable error message -
requestIdstring requiredClient request id -
contextobjectProperties that apply to a specific error name -
namestring requiredError code