Ctrl+K

Add wallet (advanced only)

post/api/v2/{coin}/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 Parameters

  • coinstringRequired
    A cryptocurrency or token ticker symbol.
    Example: btc

Request Body

coinSpecific object
xlm object
txlm object
lnbtc object
tlnbtc object
enterprise string
This is required for Ethereum wallets since they can only be created as part of an enterprise.
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
keys array[string]
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'.
Example: 59cd72485007a239fb00282ed480da1f
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 required
Example: My Wallet
multisigType string
Allowed values: onchain tss blsdkg
address string
A custom address can be provided for EOS wallets. It must be exactly 12 alphanumeric characters.
Example: ivxzn3bdn4uo
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'.
Example: 2
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'.
Example: 3
tags array[string]
Example: 59cd72485007a239fb00282ed480da1f
type string
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
Allowed values: cold custodial custodialPaired hot trading distributedCustody
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.
Minimum: >= 0
Maximum: <= 6
Default: 1
eip1559 object
(ETH walletVersion: 0 wallets only) Specify eip1559 fee parameters in wallet creation transactions.
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.

200 Response

admin object
policy object
allowBackupKeySigning boolean
approvalsRequired integer required
Minimum: >= 1
Example: 1
balanceString string
Total balance in base units (e.g. Satoshis)
Example: 2000000
Match pattern: ^-?\d+$
buildDefaults object
minFeeRate
integer or null
(UTXO only) Wallet-level minimum fee rate that must be greater than or equal to the default of 1000 satoshis/kvByte. Per transaction, you can override 'minFeeRate' with the 'feeRate' parameter.
Minimum: >= 1000
Example: 12000
maxFeeRate
integer or null
(UTXO only) Wallet-level maximum fee rate that must be greater than or equal to the default of 1000 satoshis/kvByte. Per transaction, you can override 'maxFeeRate' with the 'feeRate' parameter.
Minimum: >= 1000
Example: 18000
feeMultiplier
number or null
(UTXO only) Wallet-level custom multiplier for fee rate that must be greater than 1. The default multiplier is 1.2. The maximum fee rate still limits the new fee.
Minimum: >= 1
Example: 1.2
changeAddressType string
(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'.
Allowed values: p2sh p2shP2wsh p2wsh p2tr p2trMusig2 default
Example: p2wsh
txFormat string
(UTXO only) The default transaction format to use for this wallet. Per transaction, you can override the default with the 'txFormat' parameter.
Allowed values: legacy psbt psbt-lite
Example: psbt
coin string required
A cryptocurrency or token ticker symbol.
Example: btc
coinSpecificOne of
creationFailure array[string]
The on-chain transaction id
Example: b8a828b98dbf32d9fd1875cbace9640ceb8c82626716b4a64203fdc79bb46d26
pendingChainInitialization boolean
Whether the wallet needs to be initialized on the chain
custodialWallet object
The associated custodial wallet object
custodialWalletId string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
deleted boolean required
disableTransactionNotifications boolean required
enterprise string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
freeze object
time string <dateTime>
expires string <dateTime>
id string required
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
isCold boolean
keys array[string]
Example: 59cd72485007a239fb00282ed480da1f
label string required
Example: My Wallet
m integer
Number of signatures required. This value must be 2 for hot wallets, 1 for **ofc** wallets, and not specified for custodial wallets.
Example: 2
n integer
Number of keys provided. This value must be 3 for hot wallets, 1 for **ofc** wallets, and not specified for custodial wallets.
Example: 3
nodeId string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
receiveAddress object
id string
platform public id for an address
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
address string
Max length: <= 250 characters
Example: 2MvrwRYBAuRtPTiZ5MyKg42Ke55W3fZJfZS
chain integer
Allowed values: 0 1 10 11 20 21 30 31 40 41
Example: 1
index integer
coin string
lastNonce integer
Default: -1
wallet string
The wallet which contains this address
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
coinSpecific object
Properties which are specific to certain coin types
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.
label
string or null
A human-readable label for the address.
Max length: <= 250 characters
Example: Bob's Hot Wallet Address
addressType string
Allowed values: p2sh p2shP2wsh p2wsh p2tr p2trMusig2
Example: p2sh
recoverable boolean
tags array[string]
Example: 59cd72485007a239fb00282ed480da1f
spendableBalanceString string
Spendable balance in base units (e.g. Satoshis)
Example: 2000000
Match pattern: ^-?\d+$
unspentCount number
Number of unspent outputs present in the wallet
Example: 100
startDate string <date-time>
Wallet creation time
Example: {}
type string
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
Allowed values: cold custodial custodialPaired hot trading distributedCustody
users array[object]
Example: {"user":"55e8a1a5df8380e0e30e20c6","permissions":["admin","view","spend"]}
user string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
permissions array[string]
Comma-separated list of privileges for a wallet. Includes: - 'admin' - Can manage wallet policies and users and approve or reject pending approvals. - 'freeze' - Can freeze a wallet, disabling all withdrawals. - 'spend' - Can initiate withdrawals and generate new receive addresses. - 'trade' - Can initiate trades from a Go Account ('trading' wallet type). - 'view' - Can view balances and transactions. Permissions don't overlap. Required parameter if 'reshare' is false.
Allowed values: admin spend trade view
Example: spend,view
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.
user string
backup string
bitgo string
multisigType string
Allowed values: onchain tss blsdkg
multisigTypeVersion string
Allowed value: MPCv2

400 Response

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 Response

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