REST APIWallet & TransactWallet

POST

Note: This route is deprecated in favor of Add Wallet.

Add Wallet is for advanced API users. It lets you manually create and specify keys. The recommended (and simpler) method is Generate Wallet with the SDK or BitGo Express. You can also create wallets in the BitGo UI.

This API creates a new wallet for the user or enterprise. The keys to use with the new wallet (passed in the 'keys' parameter) must be registered with BitGo prior to using this API.

BitGo currently only supports 2-of-3 (e.g., m=2 and n=3) wallets. The third key, and only the third key, must be a BitGo key. The first key is by convention the user key, with its encrypted xprv stored on BitGo.

Ethereum and XRP wallets can only be created under an enterprise. Pass in the id of the enterprise to associate the wallet with. Your enterprise id can be seen by clicking on the "Manage Organization" link in the enterprise dropdown. Using the Add Wallet API, you can create a wallet using either the enterprise fee address (used by default for all wallets in the enterprise), or a unique fee address (created manually with the Keychains API). Pass the desired key as the third key ID in the 'keys' array. In either case, the fee address must be funded before creating the wallet.

You cannot generate a wallet by passing in a subtoken (i.e. ERC20 token) as the coin. Subtokens use the wallet of their parent coin and it is not possible to create a wallet specific to one token. For example, to create a wallet for an ERC20 token, create an Ethereum wallet. It can hold any ERC20 tokens as well as Ether.

BitGo Ethereum wallet is a smart-contract implementing multi-signature scheme. Because contracts itself can not initiate transactions, fee addresses are used for this purpose. Ethereum transactions initiated by a given address, are confirmed by the network in order of creation, so one lower fee transaction can potentially delay all subsequent transactions. To help lower network fee costs, two fee addresses are provided.

feeAddress is a main fee address usable for all operations. lowPriorityFeeAddress is a secondary fee address that can be used to pay lower fee for Create Address operations without risking delaying subsequent higher-priority transactions initiated by main fee address.

Path Params

  • coin string required
    A cryptocurrency or token ticker symbol.

Body Params

object

Requires one of label or evmKeyRingReferenceWalletId
  • coinSpecific object
    coinSpecific object
    • xlm object
      xlm object
      • stellarUsername string
        Username for the user's Stellar address. It's case insensitive, and it can't be changed after it's set.

        matches ^[a-zA-Z0-9-_.+@]+$

    • txlm object
      txlm object
      • stellarUsername string
        Username for the user's Stellar address. It's case insensitive, and it can't be changed after it's set.

        matches ^[a-zA-Z0-9-_.+@]+$

    • lnbtc object
      lnbtc object
      • keys array of strings
        Lightning wallet only. Array of two key IDs for 'userAuthKey' and 'nodeAuthKey'.
    • tlnbtc object
      tlnbtc object
      • keys array of strings
        Lightning wallet only. Array of two key IDs for 'userAuthKey' and 'nodeAuthKey'.
    • userKeySigningRequired boolean
      (OFC wallets only) Whether the wallet requires a user-key signature for every transaction. When false, BitGo KMS co-signs without user-key participation. Sending it for any other coin returns 400. When omitted the server resolves the default (true for CaaS enterprises).
  • enterprise string
    This is required for Ethereum wallets since they can only be created as part of an enterprise.
  • keys array of strings
    This is required for all wallets where the client supplies the keys to be used. The only case where this is not required is when the type is set to custodial.
  • keySignatures object
    keySignatures object
    • backup string
      a signature of the backup pub key using the user key (useful for change address verification)
    • bitgo string
      a signature of the bitgo pub key using the user key (useful for change address verification)
  • label string
  • multisigType string enum
    onchaintss
  • address string
    A custom address can be provided for EOS wallets. It must be exactly 12 alphanumeric characters.
  • m integer
    This is required for all wallets where the client supplies the keys to be used. The only case where this is not required is when the type is set to custodial.
  • n integer
    This is required for all wallets where the client supplies the keys to be used. The only case where this is not required is when the type is set to custodial.
  • tags array of strings
  • type string enum
    The type describes who owns the keys to the wallet and how they are stored. cold wallets are wallets where the private key of the user key is stored exclusively outside of BitGo's system. custodial means that this wallet is a cold wallet where BitGo owns the keys. Only customers of the BitGo Trust can create this kind of wallet. custodialPaired means that this is a hot wallet that is owned by the customer but it will be linked to a cold (custodial) wallet where BitGo owns the keys. This option is only available to customers of BitGo Inc. BitGo stores an encrypted private key for the user key of hot wallets. trading wallets are trading accounts where the coin is ofc. distributedCustody means You manage one key and another key agent manages the second key. BitGo manages the third key
    coldcustodialcustodialPairedhottradingdistributedCustodyadvanced
  • walletVersion integer
    (ETH only) Specify the wallet creation contract version used when creating a wallet contract. Use 0 for the old wallet creation, 1 for the new wallet creation, where it is only deployed upon receiving funds. 2 for wallets with the same functionality as v1 but with NFT support. 3 for MPC wallets. 4 is same as v2 but with some changes related to network identifier and encoding of tx data. v4 is applicable for Arbitrum, Optimism, ZkSync, and other EVM-compatible chains that we will onboard in the future. 5 for MPC MPCv2 wallets. 6 for EVM MPCv2 wallets with receive addresses.

    >= 0 · <= 6

    Defaults to 1

  • eip1559 object
    (ETH walletVersion: 0 wallets only) Specify eip1559 fee parameters in wallet creation transactions.
    eip1559 object
    • maxPriorityFeePerGas string required
      Max priority tip price for EIP1559 transactions. Only for ETH and ERC20 tokens.
    • maxFeePerGas string required
      Max total gasPrice for EIP1559 transactions. Only for ETH and ERC20 tokens.
  • evmKeyRingReferenceWalletId string
    Optional reference wallet ID for EVM keyring child wallets. When provided, child wallets inherit properties from the parent wallet.

Responses

200
OK

Response Body

object

  • admin object
    admin object
    • policy object
      policy object
      • id string required

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

      • date string date-time
      • label string
      • latest boolean required
      • rules array of objects required
        rules object
        • id string required
        • lockDate string date-time required
          The time at which this rule becomes immutable
        • mutabilityConstraint string enum

          Specifies whether a BitGo admin can change lockDate

          • managed - Not locked, but requires approval from a BitGo admin to change
          • permanent - lockDate cannot be changed
          managedpermanent
        • coin string
          A cryptocurrency or token ticker symbol.
        • type string enum required
          What causes this rule to trigger
          advancedWhitelistallTxbitcoinAddressWhitelistcoinAddressWhitelistcoinAddressBlacklisttransactionLimitvelocityLimitwebhook
        • condition object
          Parameters for the type

          ONE OF

          • amountString string

            matches ^-?\d+$

          • timeWindow integer
            Time window in seconds for a velocity limit, between 1 and a month

            >= 0 · <= 2.6784e+06

        • action object required
          What happens when this rule is triggered
          action object
          • type string enum required
            denygetApprovalgetFinalApprovalgetCustodianApprovalgetIdVerification
          • userIds array of strings
            For a final approver action, who can approve
      • version integer required
  • allowBackupKeySigning boolean
  • approvalsRequired integer required

    >= 1

  • balanceString string
    Total balance in base units (e.g. Satoshis)
  • buildDefaults object
    buildDefaults object
    • minFeeRate integer nullable

      (BTC only) The minimum fee rate (in base units) per kilobyte (or virtual kilobyte). For example, satoshis per kvByte. Must be greater than or equal to the default of 1000 satoshis/kvByte.

      Note: The you can override minFeeRate on a per transaction basis with the feeRate parameter.

      >= 1000

    • maxFeeRate integer nullable

      (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 you can override maxFeeRate on a per transaction basis with the feeRate parameter.

      >= 1000

    • feeMultiplier number nullable

      (UTXO only) Custom multiplier to the feeRate. The resulting fee rate is limited by the maxFeeRate. For replace-by-fee (RBF) transactions (that include rbfTxIds), the feeMultiplier must be greater than 1, since it's an absolute fee multiplier to the transaction being replaced.

      Note: The maxFeeRate limits the fee rate generated by feeMultiplier.

      >= 1

    • changeAddressType string enum nullable
      (UTXO only) The default script type to use for change for this wallet. Per transaction, you override the default with the changeAddressType parameter. If default is provided, it will clear the changeAddressType default on the wallet. Note that each UTXO coin has different address types available. For example, Only BTC supports p2tr.
      p2shp2shP2wshp2wshp2trp2trMusig2default
    • txFormat string enum
      (UTXO only) The default transaction format to use for this wallet. Per transaction, you can override the default with the txFormat parameter.
      legacypsbtpsbt-lite
    • autoReserveUnspentsOnBuildMins number nullable
      (UTXO only) Automatically reserve unspents when building a transaction.

      >= 1

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

    ONE OF

    • creationFailure array of strings
      Includes list of fail initialization txids
    • pendingChainInitialization boolean
      Whether the wallet needs to be initialized on the chain
  • custodialWallet object
    The associated custodial wallet object
  • custodialWalletId string

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

  • deleted boolean required
  • disableTransactionNotifications boolean required
  • enterprise string

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

  • freeze object
    freeze object
    • time string dateTime
    • expires string dateTime
    • reason string enum
      Reason why the wallet was frozen
      TxIntentMismatchTxIntentMismatchRecipientTxIntentMismatchContractTxIntentMismatchApprovalUserRequestAdminRequest
    • referenceId string
      Optional reference ID for tracking purposes
    • adminOrUserId string
      The user who froze the wallet
  • id string required

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

  • isCold boolean
  • keys array of strings
  • label string required
  • m integer
    Number of signatures required. This value must be 2 for hot wallets, 1 for ofc wallets, and not specified for custodial wallets.
  • n integer
    Number of keys provided. This value must be 3 for hot wallets, 1 for ofc wallets, and not specified for custodial wallets.
  • nodeId string

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

  • receiveAddress object
    receiveAddress object
    • id string
      platform public id for an address
    • address string

      up to 500 characters

    • chain integer enum
      011011202130314041
    • index integer
    • coin string
    • lastNonce integer

      Defaults to -1

    • wallet string
      The wallet which contains this address
    • coinSpecific object
      Properties which are specific to certain coin types
      coinSpecific object
      • xlm object
        xlm object
        • memoId string
          Latest memo id generated for the wallet
        • rootAddress string
          Root address of the wallet
      • txlm object
        txlm object
        • Same shape as AddressCoinSpecificXlm.
    • balance object
      Balance of the address. In case of Eth and Celo, if returnBalancesForToken is passed with includeBalances, then it will return token balance in the address object. This field will be present only when includeBalances query param is passed as true.
      balance object
      • updated string date-time
        The last time a transaction affected the balance of this address
      • balance integer
        The cleared balance of the address
      • balanceString string
        String representation of balance. Guaranteed to not lose precision.
      • totalReceived integer
        The total amount received on this address (in the chain's base unit)
      • totalSent integer
        The total amount send from this address (in the chain's base unit)
      • confirmedBalanceString string
        The total balance of confirmed transactions for the address (in the chain's base unit). Guaranteed to not lose precision.
      • spendableBalanceString string
        The total balance of the address (in the chain's base unit) which may be used as inputs for creating new transactions in string representation. Guaranteed to not lose precision.
    • label string nullable
      A human-readable label for the address.

      up to 250 characters

    • addressType string enum
      p2shp2shP2wshp2wshp2trp2trMusig2
  • recoverable boolean
  • tags array of strings
  • spendableBalanceString string
    Spendable balance in base units (e.g. Satoshis)
  • unspentCount number
    Number of unspent outputs present in the wallet
  • startDate string date-time
    Wallet creation time
  • type string enum
    The type describes who owns the keys to the wallet and how they are stored. cold wallets are wallets where the private key of the user key is stored exclusively outside of BitGo's system. custodial means that this wallet is a cold wallet where BitGo owns the keys. Only customers of the BitGo Trust can create this kind of wallet. custodialPaired means that this is a hot wallet that is owned by the customer but it will be linked to a cold (custodial) wallet where BitGo owns the keys. This option is only available to customers of BitGo Inc. BitGo stores an encrypted private key for the user key of hot wallets. trading wallets are trading accounts where the coin is ofc. distributedCustody means You manage one key and another key agent manages the second key. BitGo manages the third key
    coldcustodialcustodialPairedhottradingdistributedCustodyadvanced
  • users array of objects
    users object
    • user string

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

    • permissions array of string enums
      adminspendtradeview
  • customChangeKeySignatures object

    Signatures for the keys which will be used to derive custom change addresses.

    Note: These signatures may only be set once for each wallet and are not modifiable after being set.

    customChangeKeySignatures object
    • user string
    • backup string
    • bitgo string
  • multisigType string enum
    onchaintss
  • multisigTypeVersion string enum
    MPCv2
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
403
Forbidden

Response Body

object

  • 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