Sign in
latestOpenAPI 3.0.32026-08-224982,0272.8 MB

e445c15e5bee

Transfer

Get transfer

A transfer is a wallet specific object. Each transfer will only output the respective wallet id which the transfer is associated with.

If there is a transaction between two BitGo wallets, then two transfers will be created, one for wallet A, and one for wallet B. Transfer A will only annotate the walletId on entries where the address belongs to wallet A. Transfer B will only annotate the walletId on entries where the address belongs to wallet B.

Go Account / OFC transfers (front/backing transfer model):

For Go Account (OFC) wallets, a withdrawal is represented as two transfers:

  1. Front transfer — the record returned by this endpoint. Its txid and normalizedTxHash hold an internal BitGo front-transfer hash (e.g. prefixed with the OFC coin identifier). This value does not appear on any block explorer.
  2. Backing transfer — the actual on-chain transaction that settles the withdrawal. The on-chain transaction hash is stored in the front transfer's metadata array under the key onChainTxId.

When reconciling a Go Account withdrawal against an on-chain explorer or an external ledger, use metadata[].onChainTxId rather than the top-level txid. The onChainTxId entry is absent while the transfer is in state signed; it is populated once the transfer reaches state confirmed. Poll until state === 'confirmed' before reading this field.

For standard ofc_deposit transfers (non-lightning) the top-level txid and metadata[].onChainTxId are identical. For OFC lightning deposits the payment hash is stored under metadata[].lightningPaymentHash instead; onChainTxId is not present on lightning deposits.

See the subType field for whether a transfer is an ofc_withdrawal, ofc_deposit, ofc_book_transfer, ofc_stake, or ofc_unstake.

get/api/v2/{coin}/wallet/{walletId}/transfer/{transferId}

Path parameters

coinstring required

A cryptocurrency or token ticker symbol.

Example:btc
walletIdstring required
Example:59cd72485007a239fb00282ed480da1f

The wallet ID.

string required
OR
string required

The on-chain transaction id.

Go Account / OFC wallets: For ofc_withdrawal transfers the top-level txid (and normalizedTxHash) is the internal front-transfer hash, not the on-chain transaction hash. The on-chain hash is available in metadata[].onChainTxId once the transfer reaches state confirmed. For standard ofc_deposit transfers (non-lightning) all three values are identical. For OFC lightning deposits the payment hash is in metadata[].lightningPaymentHash; onChainTxId is absent.

Example:59cd72485007a239fb00282ed480da1f

a transfer or transaction id

Query parameters

includeTxRequestCreatedDateboolean

True, if returning the txRequestCreatedDate. This field is only present on transfers associated with a transaction request.

Response

OK

coinstring required

A cryptocurrency or token ticker symbol.

idstring required
walletstring required
enterprisestring
txidstring required

The on-chain transaction id.

Go Account / OFC wallets: For ofc_withdrawal transfers the top-level txid (and normalizedTxHash) is the internal front-transfer hash, not the on-chain transaction hash. The on-chain hash is available in metadata[].onChainTxId once the transfer reaches state confirmed. For standard ofc_deposit transfers (non-lightning) all three values are identical. For OFC lightning deposits the payment hash is in metadata[].lightningPaymentHash; onChainTxId is absent.

normalizedTxHashstring

A normalized form of txid used for deduplication. For most coins this is identical to txid. For account-model coins (e.g. ETH and its tokens) it may differ from txid when the transaction is regenerated. For lightning transfers, normalizedTxHash is identical to txid (no transformation is applied).

Go Account / OFC withdrawals: Like txid, this field holds the internal front-transfer hash, not the on-chain hash. Use metadata[].onChainTxId for the on-chain transaction hash.

txidType'transactionHash' | 'blockHash'

The type of the transaction id

heightinteger required

The height of the block this Transfer was confirmed in (999999999 if unconfirmed)

heightIdstring

The unique height id of the block

datestring date-time required

The date this Transfer was last updated

confirmationsinteger required

The number of blocks that have been confirmed since this Transfer's block was confirmed

type'send' | 'receive' required

Defines whether or not this Transfer was sent or received by the user

valueinteger

The 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 required
intendedValueStringstring
baseValueinteger

The value (in base units) sent by this transfer, excluding network fees. BitGo is deprecating this field in the future. Instead, use baseValueWithoutFees.

baseValueStringstring
baseValueWithoutFeesinteger

The value (in base units) sent by this transfer excluding network fees.

baseValueWithoutFeesStringstring
feeStringstring

The Transfer's fee (in base units) represented as a String

payGoFeeinteger

The Transfer's BitGo fee (in base units)

payGoFeeStringstring

The Transfer's BitGo fee (in base units) represented as a String

usdnumber required

The amount of USD of this Transfer (will be negative if it's a send)

usdRatenumber required

The USD price at the time this Transfer was created

state'confirmed' | 'failed' | 'initialized' | 'pendingApproval' | 'rejected' | 'removed' | 'replaced' | 'signed' | 'unconfirmed' required

The 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.
tagsId[] required

The tags to be used on this Transfer (used in Policies)

commentstring required

A comment from the user

vSizeinteger

The size of the transaction

coinSpecificobject required

Transfer fields specific to each coin type

sequenceIdstring

A sequenceId is a unique and arbitrary wallet identifier applied to transfers and transactions at creation. It is optional but highly recommended. With a sequenceId you can easily reference transfers and transactions—for example, to safely retry sending. Because the system only confirms one send request per sequenceId (and fails all subsequent attempts), you can retry sending without the risk of double spending. The sequenceId is only visible to users on the wallet and is not shared publicly.

consolidateIdstring
txRequestIdstring

Associated transaction request ID

goStakingRequestIdstring

Associated GO staking request ID

subType'ofc_withdrawal' | 'ofc_deposit' | 'ofc_unstake' | 'ofc_stake' | 'ofc_book_transfer'

Transfer subtype

feeCoinstring

The coin used to pay the fee (for cross-chain transactions)

instantboolean

Whether this is an instant transaction

instantIdstring

The instant transaction ID if applicable

isFeeboolean

Whether this transfer represents a fee

isRewardboolean

Whether this transfer represents a staking reward

isUnlockboolean

Whether this transfer represents an unlock operation

createdTimestring date-time

The time this transfer was created

approvedTimestring date-time

The time this transfer was approved

rejectedTimestring date-time

The time this transfer was rejected

signedTimestring date-time

The time this transfer was signed

unconfirmedTimestring date-time

The time this transfer became unconfirmed

confirmedTimestring date-time

The time this transfer was confirmed

removedTimestring date-time

The time this transfer was removed

commentedTimestring date-time

The time this transfer was commented on

failedTimestring date-time

The time this transfer failed

regeneratedTimestring date-time

The time this transfer was regenerated

replacedTimestring date-time

The time this transfer was replaced

replacingTimestring date-time

The time this transfer started replacing another

abandonedTimestring date-time

The time this transfer was abandoned

signedDatestring date-time

The date this transfer was signed (legacy field)

customerApprovedTimestring date-time

The time this transfer was approved by the customer (trust transfers)

idVerificationTimestring date-time

The time identity verification was completed (trust transfers)

trustSignedTimestring date-time

The time this transfer was signed by trust (trust transfers)

trustFinalApprovalTimestring date-time

The time this transfer received final trust approval (trust transfers)

walletLabelstring

Label of the wallet associated with this transfer

enterpriseNamestring

Name of the enterprise associated with this transfer

ellipticstring

Elliptic risk score information (trust transfers)

senderInformationVerifiedboolean

Whether sender information has been verified (trust transfers)

buildParamsobject

Parameters used to build the transaction

usersNotifiedboolean

Whether BitGo already sent notifications to the users of the transfer wallet

labelstring

Address labels (if any) from entries concatenated.

replacesstring[]

Transaction IDs that this transfer replaces.

replacedBystring[]

Transaction IDs that replace this transfer.

riskIndicatorsstring[]

Risk indicators detected on this transfer (e.g. SELFDESTRUCT opcode). Transfers with risk indicators will not trigger webhook or email notifications.

Example response

{
  "coin": "btc",
  "id": "59cd72485007a239fb00282ed480da1f",
  "wallet": "59cd72485007a239fb00282ed480da1f",
  "enterprise": "59cd72485007a239fb00282ed480da1f",
  "txid": "b8a828b98dbf32d9fd1875cbace9640ceb8c82626716b4a64203fdc79bb46d26",
  "normalizedTxHash": "b8a828b98dbf32d9fd1875cbace9640ceb8c82626716b4a64203fdc79bb46d26",
  "valueString": "2000000",
  "intendedValueString": "2000000",
  "baseValueString": "2000000",
  "baseValueWithoutFeesString": "2000000",
  "state": "confirmed",
  "tags": [
    "59cd72485007a239fb00282ed480da1f"
  ],
  "history": [
    {
      "user": "59cd72485007a239fb00282ed480da1f"
    }
  ],
  "consolidateId": "59cd72485007a239fb00282ed480da1f",
  "entries": [
    {
      "address": "2NAUwNgXaoFj2VVnSEvNLGuez8CfdU2UCMZ",
      "wallet": "59cd72485007a239fb00282ed480da1f",
      "valueString": "2000000",
      "token": "omg"
    }
  ],
  "inputs": [
    {
      "id": "003f688cc349f1fca8ac5ffa21671ca911b6ef351085c60733ed8c2ebf162cb8:2",
      "address": "2MsKxhhkDo5WaLaYRGA9Cr3iSQPyXsu6Fi2",
      "valueString": "2000000",
      "date": "2017-03-25T23:01:40.248Z",
      "wallet": "59cd72485007a239fb00282ed480da1f",
      "fromWallet": "59cd72485007a239fb00282ed480da1f",
      "redeemScript": "522102f1e990044d2a8be43d5b500bbdcb36277b97a4b07e01c5101ae8ec1568bfd6532103dab7dc82f2fc8c28200c1bdeca9c4cf181e0ca257395829cbd599395048afb57210205422e711827d8356f2fb75334d863941dd7eb45bd5788fa231dc5fa755135b653ae",
      "witnessScript": "52210351311cd81144e6cbdba561d24dfc22644cb02d053339d4beace03231b3be4f372103a8d0c1a375b9ee1a2411f9f8e18373be7f228b18260f63bbfca48809170ed08b2103c3bd8bd074657bbe9ee6714b31a4a54b6fd5b5cda0e1030122f9bf46b5034f6b53ae"
    }
  ],
  "outputs": [
    {
      "id": "003f688cc349f1fca8ac5ffa21671ca911b6ef351085c60733ed8c2ebf162cb8:2",
      "address": "2MsKxhhkDo5WaLaYRGA9Cr3iSQPyXsu6Fi2",
      "valueString": "2000000",
      "date": "2017-03-25T23:01:40.248Z",
      "wallet": "59cd72485007a239fb00282ed480da1f",
      "fromWallet": "59cd72485007a239fb00282ed480da1f",
      "redeemScript": "522102f1e990044d2a8be43d5b500bbdcb36277b97a4b07e01c5101ae8ec1568bfd6532103dab7dc82f2fc8c28200c1bdeca9c4cf181e0ca257395829cbd599395048afb57210205422e711827d8356f2fb75334d863941dd7eb45bd5788fa231dc5fa755135b653ae",
      "witnessScript": "52210351311cd81144e6cbdba561d24dfc22644cb02d053339d4beace03231b3be4f372103a8d0c1a375b9ee1a2411f9f8e18373be7f228b18260f63bbfca48809170ed08b2103c3bd8bd074657bbe9ee6714b31a4a54b6fd5b5cda0e1030122f9bf46b5034f6b53ae"
    }
  ]
}