REST APIWallet & TransactTransaction request

GET

Get a paginated list of transaction requests filtered by enterprise.

Path Params

  • enterpriseId string required

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

Query Params

  • txRequestIds array of strings
    If provided, only the specified transaction requests will be returned.
  • idempotencyKeys array of strings
    If provided, only transaction requests with the matching idempotencyKeys will be returned.
  • sequenceIds array of strings
    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.
  • intentTypes array of string enums
    If provided, only transaction requests with the specified intent types will be returned.
    paymentconsolidateconsolidateTokenfanoutvotecreateAccountupdateAccountaddTrustLineremoveTrustLinesignMessagesignTypedStructuredDataenableTokenaccelerationtransferTokenfillNoncewalletRecoverycontractCallcustomTxcloseAssociatedTokenAccountexportimportimporttoctransferAcknowledgetransferAccepttransferRejecttransferOfferWithdrawncosignDelegationProposalcosignDelegationAcceptallocationRequestallocationAllocatecantonCommandcantonEndInvestorOnboardingOffercantonEndInvestorOnboardingAcceptcantonEndInvestorOnboardingRejectcantonParticipantOnboardingRequeststakeunstakedelegateundelegateswitchValidatorclaimstakeClaimRewardspledgevoteDelegationauthorizedeactivatecreateBtcDelegationgoUnstakestakeWithCallDataunstakeWithCallDatavalidatorRegistrationincreaseStakedecreaseStakesignalExitwithdrawStakeswitchValidatorWithCallDataspotTransferdelegateResourceundelegateResource
  • excludeIntentTypes array of string enums
    If provided, transaction requests with the specified intent types will be excluded.
    paymentconsolidateconsolidateTokenfanoutvotecreateAccountupdateAccountaddTrustLineremoveTrustLinesignMessagesignTypedStructuredDataenableTokenaccelerationtransferTokenfillNoncewalletRecoverycontractCallcustomTxcloseAssociatedTokenAccountexportimportimporttoctransferAcknowledgetransferAccepttransferRejecttransferOfferWithdrawncosignDelegationProposalcosignDelegationAcceptallocationRequestallocationAllocatecantonCommandcantonEndInvestorOnboardingOffercantonEndInvestorOnboardingAcceptcantonEndInvestorOnboardingRejectcantonParticipantOnboardingRequeststakeunstakedelegateundelegateswitchValidatorclaimstakeClaimRewardspledgevoteDelegationauthorizedeactivatecreateBtcDelegationgoUnstakestakeWithCallDataunstakeWithCallDatavalidatorRegistrationincreaseStakedecreaseStakesignalExitwithdrawStakeswitchValidatorWithCallDataspotTransferdelegateResourceundelegateResource
  • states array of string enums

    If provided, only transaction requests of the specified state will be returned.

    • canceled: Canceled by a wallet spender before approval or sending.
    • delivered: Inserted into the send queue (or rejected by BitGo through circuit breakers). This state is only used with apiVersion "full".
    • failed : Catch-all state indicating an unrecoverable failure (such as a duplicate key error when creating a transfer).
    • initialized: First state when a transaction request is created (before any policy evaluation occurs).
    • pendingApproval: Triggered a policy that requires approval to proceed.
    • pendingDelivery: Requires further action to proceed (such as pending signature, or accepting/rejecting due to triggering a circuit breaker). This state is only used with apiVersion "full".
    • pendingUserCommitment: Ready to receive your user commitments. This state is only used with apiVersion "lite" and EdDSA assets with commitment signing states.
    • pendingUserGShare: Ready to receive your gShare.
    • pendingUserRShare: Ready to receive your rShare.
    • pendingUserSignature: Ready to receive your user signature (get the unsigned transaction from BitGo and sign it). This state is only used with apiVersion "lite" and EdDSA assets without commitment signing states.
    • readyToSend: Ready send (share combination is complete).
    • rejected: Rejected by an approver.
    • signed: All transactions in the transaction request were signed. All future updates will be in the transfer document.
    pendingApprovalcanceledrejectedinitializedpendingDeliverydeliveredpendingUserSignaturependingUserCommitmentpendingUserRSharependingUserGSharereadyToSendsignedfailed
  • latest boolean
    If provided, only the latest transaction request version will be returned.
  • limit string number
    Maximum number of results to return. If the result set is truncated, use the "nextBatchPrevId" value to get the next batch.

    >= 1 · <= 500

    Defaults to 25

  • prevId string
    Return the next batch of results, based on the "nextBatchPrevId" value from the previous batch.

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

  • version string number
  • sortBy string enum
    Sorts by specified field, default sorting by id.
    idcreatedDate
  • sortDirection string enum
    Sorts order by field in specified sort direction, default ascending.
    ASCDESC
  • dateLt string date-time
    Optional get transaction requests less than date
  • dateGte string date-time
    Optional get transaction requests greater than or equal to date
  • includeEvmKeyringTxRequests boolean
    If true, include transaction requests for all EVM keyring related wallets (main + derived).

Responses

200
OK

Response Body

object

  • nextBatchPrevId string uuid
    When 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 the "prevId" query parameter.
  • txRequests array of objects required

    ONE OF

    • intent object
      The intent of the transaction request

      ONE OF

      • unspents array of strings
      • intentType string enum required
        Must be "consolidate".
        consolidate
      • receiveAddress string required
        Destination address for consolidated funds. Must be a wallet-owned address.
      • senderAddressIndex number
        Index of the wallet address to use as the sender.
      • consolidateId string
        Opaque identifier used to correlate consolidation requests.
      • recipients array of objects
        recipients object
        • tokenData object
          tokenData object
          • tokenQuantity string required
          • tokenType string required
          • tokenId string
          • tokenName string required
          • tokenContractAddress string
          • decimals number
        • address object required
          address object
          • address string
          • option map of objects
            option object
            • <key> object
        • amount object required
          amount object
          • value string required
          • symbol string required
        • data string
      • keepAlive boolean
        When true, leaves a small amount in the source address to keep it alive.
      • nonce string or number
        Override the on-chain nonce for this transaction.
    • unsignedTxs array of objects
      unsignedTxs object
      • parsedTx object required
        parsedTx object
        • inputs array of objects required
          inputs object
          • valueString string required
          • _id string
          • address string
          • chain number
          • derivationIndex number
          • index number
          • value number
        • minerFee string or number required
        • outputs array of objects required
          outputs object
          • valueString string required
          • address string
          • change boolean
          • coinName string
          • data string
          • isPayGo boolean
          • value number
          • wallet string
          • walletV1 string
          • baseAddress string
          • enterprise string
        • spendAmount string or number required
        • gasPrice number
        • hasUnvalidatedData boolean
        • payGoFee string or number
        • spendAmounts array of objects
          spendAmounts object
          • <key> object
        • type string
      • serializedTxHex string required
        The unsigned transaction as a hex string.
      • signableHex string required
        The portion of a transaction used to generate a signature (may or may not be the same as serializedTxHex) as a hex string.
      • derivationPath string
        A bip32 path.
      • coinSpecific object
        Coin specific information.
        coinSpecific object
        • nonceAddress string
        • stakingAddress string
        • signature string
        • <key> object
      • feeInfo object
        feeInfo object
        • fee string or number required
        • feeString string required
    • signatureShares array of objects
      signatureShares object
      • vssProof string
        The VSS proof of the signature share
      • privateShareProof string
        The private share proof
      • publicShare string
        The public share
      • from string enum required
        The source of the signature share.
        userbackupbitgo
      • to string enum required
        The recipient of the signature share.
        userbackupbitgo
      • share string required
        The signature share
    • commitmentShares array of objects
      commitmentShares object
      • type string enum required
        The type of the commitment share
        commitment
      • from string enum required
        The source of the commitment share
        userbackupbitgo
      • to string enum required
        The recipient of the commitment share.
        userbackupbitgo
      • share string required
        The commitment share.
    • txHashes array of strings
    • apiVersion string enum
      The API version of the transaction request
      litefull
    • txRequestId string uuid required
      A unique ID for the TxRequest document across all wallets. The combination of the txRequestId and version will always be unique.
    • idempotencyKey string
      The idempotency key of the transaction request
    • walletId string required
      The id of the Wallet the TxRequest is for.
    • walletType string enum
      The type describes who owns the keys to the wallet associated to the TxRequest.
      backingcoldcustodialcustodialPairedhotadvancedtrading
    • version number required
      The version of the transaction request
    • enterpriseId string
      If the wallet that owns the TxRequest is owned by an enterprise then this is the Id of said enterprise.

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

    • state string enum required
      pendingApprovalcanceledrejectedinitializedpendingDeliverydeliveredpendingUserSignaturependingUserCommitmentpendingUserRSharependingUserGSharereadyToSendsignedfailed
    • date string date-time required
      The date and time this version of the TxRequest document was created.
    • createdDate string date-time required
      The date and time the version 1 TxRequest document was created.
    • userId string required
      The Id of the User that produced this version of the TxRequest document. Could have created a new document or updated an existing document.
    • initiatedBy string required
      The Id of the User that originally created the TxRequest document (initiated the TxRequest).
    • updatedBy string required
      The Id of the User that last updated the TxRequest document. This is an alias for the userId field.
    • intent object
      The intent of the transaction request
    • intents array of objects required
    • pendingApprovalId string
      The id of the Pending Approval that was created for the TxRequest if one was required.
    • policiesChecked boolean
    • latest boolean required
      Indicates if this is the latest transaction request
    • isCanceled boolean
      True, if the transaction request is canceled.
    • initiatedByDAppClient boolean
      True when the txRequest was initiated by a dApp OAuth client (e.g. Narval).
    • txChannel object
      Immutable DeFi / marketplace channel classification (DEFI-300).
      txChannel object
      • clientId string
        OAuth dApp client id (Narval).
      • connector string enum
        External entry connector (narval, walletconnect). Omitted for internal BitGo flows.
        narvalwalletconnect
      • defiAction string enum
        approvedepositwithdraw
      • protocol string enum
        DeFi protocol (morpho, aave, concrete).
        morphoaaveconcrete
      • source string enum required
        internalexternal
      • type string enum required
        defi
      • vaultId string
      • walletConnectRequestId string
        defi-service walletconnect_requests.id when supplied on the intent.
400
Bad Request

Response Body

object

  • name string
    Error code
  • context map of objects required
    Properties that apply to a specific error name
    context object
    • <key> object
  • error string required
    Human-readable error message
  • requestId string required
    Client request id