Sign in
latestOpenAPI 3.0.32026-08-224982,0272.8 MB

e445c15e5bee

Wallet

Add wallet (advanced only)

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.

post/api/v2/{coin}/wallet/add

Path parameters

coinstring required

A cryptocurrency or token ticker symbol.

Example:btc

Request body

enterprisestring
keysId[]
labelstring
multisigType'onchain' | 'tss'
addressstring

A custom address can be provided for EOS wallets. It must be exactly 12 alphanumeric characters.

minteger

Number of signatures required. This value must be 2 for hot wallets, 1 for ofc wallets, and not specified for custodial wallets.

ninteger

Number of keys provided. This value must be 3 for hot wallets, 1 for ofc wallets, and not specified for custodial wallets.

tagsId[]
type'cold' | 'custodial' | 'custodialPaired' | 'hot' | 'trading' | 'distributedCustody' | 'advanced'

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

walletVersioninteger

(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.

evmKeyRingReferenceWalletIdstring required

Optional reference wallet ID for EVM keyring child wallets. When provided, child wallets inherit properties from the parent wallet.

Example request

{
  "coinSpecific": {
    "xlm": {
      "stellarUsername": "foo_bar@baz.com"
    },
    "txlm": {
      "stellarUsername": "foo_bar@baz.com"
    },
    "lnbtc": {
      "keys": [
        "585951a5df8380e0e304a553",
        "585951a5df8380e0e30d645c",
        "585951a5df8380e0e30b6147"
      ]
    },
    "tlnbtc": {
      "keys": [
        "585951a5df8380e0e304a553",
        "585951a5df8380e0e30d645c",
        "585951a5df8380e0e30b6147"
      ]
    }
  },
  "enterprise": "59cd72485007a239fb00282ed480da1f",
  "keys": [
    "585951a5df8380e0e304a553",
    "585951a5df8380e0e30d645c",
    "585951a5df8380e0e30b6147"
  ],
  "label": "My Wallet",
  "address": "ivxzn3bdn4uo",
  "m": 2,
  "n": 3,
  "tags": [
    "59cd72485007a239fb00282ed480da1f"
  ]
}

Response

OK

allowBackupKeySigningboolean
approvalsRequiredinteger required
balanceStringstring
coinstring required

A cryptocurrency or token ticker symbol.

custodialWalletobject

The associated custodial wallet object

custodialWalletIdstring
deletedboolean required
disableTransactionNotificationsboolean required
enterprisestring
idstring required
isColdboolean
keysId[]
labelstring required
minteger

Number of signatures required. This value must be 2 for hot wallets, 1 for ofc wallets, and not specified for custodial wallets.

ninteger

Number of keys provided. This value must be 3 for hot wallets, 1 for ofc wallets, and not specified for custodial wallets.

nodeIdstring
recoverableboolean
tagsId[]
spendableBalanceStringstring
unspentCountnumber

Number of unspent outputs present in the wallet

startDatestring date-time
type'cold' | 'custodial' | 'custodialPaired' | 'hot' | 'trading' | 'distributedCustody' | 'advanced'

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

multisigType'onchain' | 'tss'
multisigTypeVersion'MPCv2'

Example response

{
  "admin": {
    "policy": {
      "id": "59cd72485007a239fb00282ed480da1f",
      "rules": [
        {
          "coin": "btc",
          "condition": {
            "amountString": "2000000"
          },
          "action": {
            "userIds": [
              "59cd72485007a239fb00282ed480da1f"
            ]
          }
        }
      ]
    }
  },
  "approvalsRequired": 1,
  "balanceString": "2000000",
  "buildDefaults": {
    "minFeeRate": 12000,
    "maxFeeRate": 18000,
    "feeMultiplier": 1.2,
    "changeAddressType": "p2wsh",
    "txFormat": "psbt",
    "autoReserveUnspentsOnBuildMins": 60
  },
  "coin": "btc",
  "coinSpecific": {
    "creationFailure": [
      "b8a828b98dbf32d9fd1875cbace9640ceb8c82626716b4a64203fdc79bb46d26"
    ]
  },
  "custodialWalletId": "59cd72485007a239fb00282ed480da1f",
  "enterprise": "59cd72485007a239fb00282ed480da1f",
  "id": "59cd72485007a239fb00282ed480da1f",
  "keys": [
    "585951a5df8380e0e304a553",
    "585951a5df8380e0e30d645c",
    "585951a5df8380e0e30b6147"
  ],
  "label": "My Wallet",
  "m": 2,
  "n": 3,
  "nodeId": "59cd72485007a239fb00282ed480da1f",
  "receiveAddress": {
    "id": "59cd72485007a239fb00282ed480da1f",
    "address": "2MvrwRYBAuRtPTiZ5MyKg42Ke55W3fZJfZS",
    "chain": 1,
    "wallet": "59cd72485007a239fb00282ed480da1f",
    "coinSpecific": {
      "xlm": {
        "memoId": "1",
        "rootAddress": "GCTTCPH4IIDK7P72FFAEJ3ZFN6WDHJH6GGMRPHPM56ZWGIQ7B3XTIJAM"
      },
      "txlm": {
        "memoId": "1",
        "rootAddress": "GCTTCPH4IIDK7P72FFAEJ3ZFN6WDHJH6GGMRPHPM56ZWGIQ7B3XTIJAM"
      }
    },
    "balance": {
      "balance": 50000,
      "balanceString": "50000",
      "confirmedBalanceString": "40000",
      "spendableBalanceString": "40000"
    },
    "label": "Bob's Hot Wallet Address",
    "addressType": "p2sh"
  },
  "tags": [
    "59cd72485007a239fb00282ed480da1f"
  ],
  "spendableBalanceString": "2000000",
  "unspentCount": 100,
  "users": [
    {
      "user": "55e8a1a5df8380e0e30e20c6",
      "permissions": [
        "admin",
        "view",
        "spend"
      ]
    }
  ]
}