Express

POST

Fan out unspents

Fan out unspents on a wallet

Path Params

  • coin string required
    A cryptocurrency or token ticker symbol.
  • walletId string required
    The wallet ID.

    matches ^[0-9a-f]{32}$

Body Params

object

  • walletPassphrase string
    Passphrase to decrypt the user key on the wallet
  • xprv string
    Private key in string form, if walletPassphrase is not available
  • feeRate object

    Custom fee rate (in base units) per kilobyte (or virtual kilobyte). For example, satoshis per kvByte.

    If the feeRate is less than the minimum required network fee, then the minimum fee applies. For example, 1000 sat/kvByte, a flat 1000 microAlgos, or a flat 10 drops of xrp. For XRP, the actual fee is usually 4.5 times the open ledger fee.

    Note: The feeRate overrides the maxFeeRate and minFeeRate.

  • maxFeeRate object

    (BTC only) The maximum fee rate (in base units) per kilobyte (or virtual kilobyte). For example, satoshis per kvByte. The maxFeeRate limits the fee rate generated by both feeMultiplier and numBlocks.

    Note: The feeRate overrides the maxFeeRate.

  • maxFeePercentage integer
    Maximum relative portion that can be spent towards fees
  • feeTxConfirmTarget integer
    Block target for fee estimation
  • minValue object
    Minimum value of unspents to use in base units (e.g. satoshis). For doge, only string is allowed.
  • maxValue object
    Maximum value of unspents to use in base units (e.g. satoshis). For doge, only string is allowed.
  • minHeight integer
    Minimum height of unspents on the block chain to use
  • minConfirms integer
    Minimum confirmation threshold for external inputs
  • enforceMinConfirmsForChange boolean
    Flag for enforcing minConfirms for change inputs
  • unspents array of strings
    Unspents to fan out in the transaction. Mutually exclusive with maxNumInputsToUse.
  • maxNumInputsToUse integer
    Maximum number of unspents to use in the transaction. Mutually exclusive with unspents.
  • numUnspentsToMake integer
    Number of new unspents to make
  • targetAddress string
    address to use for generated outputs. Must be wallet address.
  • txFormat string enum
    [UTXO only] Format of the returned transaction hex serialization. legacy for serialized transaction in custom bitcoinjs-lib format. psbt for BIP174 serialized transaction

    Defaults to legacy

    legacypsbtpsbt-lite

Responses

200
OK

Response Body

ANY OF

  • transfer object
    transfer object
    • coin string required
      A cryptocurrency or token ticker symbol.
    • id string required

      matches ^[0-9a-f]{32}$

    • wallet string required

      matches ^[0-9a-f]{32}$

    • enterprise string

      matches ^[0-9a-f]{32}$

    • txid 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.

    • normalizedTxHash string

      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 string enum
      The type of the transaction id
      transactionHashblockHash
    • height integer required
      The height of the block this Transfer was confirmed in (999999999 if unconfirmed)
    • heightId string
      The unique height id of the block
    • date string date-time required
      The date this Transfer was last updated
    • confirmations integer required
      The number of blocks that have been confirmed since this Transfer's block was confirmed
    • type string enum required
      Defines whether or not this Transfer was sent or received by the user
      sendreceive
    • value integer
      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)
    • valueString string required
      The total value (in base units) sent by this Transfer represented as a String
    • intendedValueString string
      A 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.
    • baseValue integer
      The value (in base units) sent by this transfer, excluding network fees. BitGo is deprecating this field in the future. Instead, use baseValueWithoutFees.
    • baseValueString string
      The 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.
    • baseValueWithoutFees integer
      The value (in base units) sent by this transfer excluding network fees.
    • baseValueWithoutFeesString string
      The value (in base units) sent by this transfer, excluding network fees, represented as a string
    • feeString string
      The Transfer's fee (in base units) represented as a String
    • payGoFee integer
      The Transfer's BitGo fee (in base units)
    • payGoFeeString string
      The Transfer's BitGo fee (in base units) represented as a String
    • usd number required
      The amount of USD of this Transfer (will be negative if it's a send)
    • usdRate number required
      The USD price at the time this Transfer was created
    • state string enum 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.
      confirmedfailedinitializedpendingApprovalrejectedremovedreplacedsignedunconfirmed
    • tags array of strings required
      The tags to be used on this Transfer (used in Policies)
    • history array of objects required
      An audit log of events that have happened to the Transfer during its lifecycle
      history object
      • date string date-time
        The date of this history object
      • user string

        matches ^[0-9a-f]{32}$

      • action string enum
        createdsignedunconfirmedconfirmedapprovedcommentedremovedfailedrejected
      • comment string
        If this history object is of action commented, this is the comment from the user
    • comment string required
      A comment from the user
    • vSize integer
      The size of the transaction
    • coinSpecific object required
      Transfer fields specific to each coin type
    • sequenceId string
      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.
    • consolidateId string
      Consolidation ID if this transfer is part of a consolidation
    • txRequestId string
      Associated transaction request ID
    • goStakingRequestId string
      Associated GO staking request ID
    • subType string enum
      Transfer subtype
      ofc_withdrawalofc_depositofc_unstakeofc_stakeofc_book_transfer
    • feeCoin string
      The coin used to pay the fee (for cross-chain transactions)
    • instant boolean
      Whether this is an instant transaction
    • instantId string
      The instant transaction ID if applicable
    • isFee boolean
      Whether this transfer represents a fee
    • isReward boolean
      Whether this transfer represents a staking reward
    • isUnlock boolean
      Whether this transfer represents an unlock operation
    • metadata array of objects

      Key-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 both ofc_withdrawal and ofc_deposit lightning transfers; for ofc_deposit lightning transfers this key is used instead of onChainTxId.
      • onChainTxId — (Go Account / OFC non-lightning transfers only) The on-chain transaction hash of the backing transfer. For ofc_withdrawal transfers this key is absent while the transfer is in state signed; it is populated once the transfer reaches state confirmed (i.e. once the backing on-chain transaction is confirmed). Poll until state === 'confirmed' before reading this field. Use this value — not the top-level txid — when reconciling against a block explorer or external ledger. For standard ofc_deposit transfers (non-lightning) this value equals the top-level txid.
      • 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
      • key string
        The metadata key name. See the metadata array description for documented values. Additional keys may be present.
      • value string
    • sendAccounting array of objects
      Accounting breakdown for send transactions
      sendAccounting object
      • type string
      • amountString string
      • nOuts integer
      • amount integer
      • id string
    • createdTime string date-time
      The time this transfer was created
    • approvedTime string date-time
      The time this transfer was approved
    • rejectedTime string date-time
      The time this transfer was rejected
    • signedTime string date-time
      The time this transfer was signed
    • unconfirmedTime string date-time
      The time this transfer became unconfirmed
    • confirmedTime string date-time
      The time this transfer was confirmed
    • removedTime string date-time
      The time this transfer was removed
    • commentedTime string date-time
      The time this transfer was commented on
    • failedTime string date-time
      The time this transfer failed
    • regeneratedTime string date-time
      The time this transfer was regenerated
    • replacedTime string date-time
      The time this transfer was replaced
    • replacingTime string date-time
      The time this transfer started replacing another
    • abandonedTime string date-time
      The time this transfer was abandoned
    • signedDate string date-time
      The date this transfer was signed (legacy field)
    • customerApprovedTime string date-time
      The time this transfer was approved by the customer (trust transfers)
    • idVerificationTime string date-time
      The time identity verification was completed (trust transfers)
    • trustSignedTime string date-time
      The time this transfer was signed by trust (trust transfers)
    • trustFinalApprovalTime string date-time
      The time this transfer received final trust approval (trust transfers)
    • walletLabel string
      Label of the wallet associated with this transfer
    • enterpriseName string
      Name of the enterprise associated with this transfer
    • elliptic string
      Elliptic risk score information (trust transfers)
    • senderInformationVerified boolean
      Whether sender information has been verified (trust transfers)
    • buildParams map
      Parameters used to build the transaction
    • entries array of objects
      An array of objects describing the change in address balances made as a result of this Transfer
      entries object
      • address string
        An address affected by this Transfer
      • wallet string
        Only visible when the user has access to the wallet
      • value integer
        The change (in base units) in the address's balance
      • valueString string
        The change (in base units) in the address's balance represented as a String
      • isChange boolean
        True if this address is a change address (only exists for UTXO coins) and if this is a sent Transfer
      • isPayGo boolean
        True if this address is the BitGo PayGo wallet
      • token string
        If this is a token entry, the token's symbol
      • label string
        Names of addresses given by the user.
      • failed boolean
        true if this entry is failed.
      • associatedNativeCoinAddress string
        The native coin receive address associated with the solana ATA address. This is currently present only for BitGo addresses.
      • memo string
        Memo 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.
      • type string
        The type of this entry (e.g., transfer, fee, contract_call).
      • nftId string
        NFT ID associated with this entry. Only present for NFT transfers.
      • nftSymbol string
        NFT symbol associated with this entry. Only present for NFT transfers.
    • usersNotified boolean
      Whether BitGo already sent notifications to the users of the transfer wallet
    • label string
      Address labels (if any) from entries concatenated.
    • replaces array of strings
      Transaction IDs that this transfer replaces.
    • replacedBy array of strings
      Transaction IDs that replace this transfer.
    • riskIndicators array of string enums
      Risk indicators detected on this transfer (e.g. SELFDESTRUCT opcode). Transfers with risk indicators will not trigger webhook or email notifications.
      SELFDESTRUCT
  • txid string
    Unique transaction identifier
  • tx string
  • status string enum
    Transfer status
    signedsigned (suppressed)pendingApproval
400
Bad Request

Response Body

ONE OF

  • error string required
    Human-readable error message
  • requestId string required
    Client request id
  • context object
    Properties that apply to a specific error name
  • name string required
    Error code