\[DEPRECATED\] Add wallet (advanced only)
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
-
coinstring requiredA cryptocurrency or token ticker symbol.
Body Params
object
label
or
evmKeyRingReferenceWalletId
-
coinSpecificobjectcoinSpecific object
-
xlmobjectxlm object
-
stellarUsernamestringUsername for the user's Stellar address. It's case insensitive, and it can't be changed after it's set.
-
-
txlmobjecttxlm object
-
stellarUsernamestringUsername for the user's Stellar address. It's case insensitive, and it can't be changed after it's set.
-
-
lnbtcobjectlnbtc object
-
keysarray of stringsLightning wallet only. Array of two key IDs for 'userAuthKey' and 'nodeAuthKey'.
-
-
tlnbtcobjecttlnbtc object
-
keysarray of stringsLightning wallet only. Array of two key IDs for 'userAuthKey' and 'nodeAuthKey'.
-
-
userKeySigningRequiredboolean(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).
-
-
enterprisestringThis is required for Ethereum wallets since they can only be created as part of an enterprise. -
keysarray of stringsThis 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 tocustodial. -
keySignaturesobjectkeySignatures object
-
backupstringa signature of the backup pub key using the user key (useful for change address verification) -
bitgostringa signature of the bitgo pub key using the user key (useful for change address verification)
-
-
labelstring -
multisigTypestring enumonchaintss -
addressstringA custom address can be provided for EOS wallets. It must be exactly 12 alphanumeric characters. -
mintegerThis 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 tocustodial. -
nintegerThis 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 tocustodial. -
tagsarray of strings -
typestring enumThe type describes who owns the keys to the wallet and how they are stored.coldwallets are wallets where the private key of the user key is stored exclusively outside of BitGo's system.custodialmeans that this wallet is a cold wallet where BitGo owns the keys. Only customers of the BitGo Trust can create this kind of wallet.custodialPairedmeans 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 ofhotwallets.tradingwallets are trading accounts where the coin isofc.distributedCustodymeans You manage one key and another key agent manages the second key. BitGo manages the third keycoldcustodialcustodialPairedhottradingdistributedCustodyadvanced -
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. -
eip1559object(ETH walletVersion: 0 wallets only) Specify eip1559 fee parameters in wallet creation transactions.eip1559 object
-
maxPriorityFeePerGasstring requiredMax priority tip price for EIP1559 transactions. Only for ETH and ERC20 tokens. -
maxFeePerGasstring requiredMax total gasPrice for EIP1559 transactions. Only for ETH and ERC20 tokens.
-
-
evmKeyRingReferenceWalletIdstringOptional reference wallet ID for EVM keyring child wallets. When provided, child wallets inherit properties from the parent wallet.
Responses
200
OK
Response Body
object
-
adminobjectadmin object
-
policyobjectpolicy object
-
idstring required -
datestring date-time -
labelstring -
latestboolean required -
rulesarray of objects requiredrules object
-
idstring required -
lockDatestring date-time requiredThe time at which this rule becomes immutable -
mutabilityConstraintstring enumSpecifies whether a BitGo admin can change
lockDatemanaged- Not locked, but requires approval from a BitGo admin to changepermanent-lockDatecannot be changed
managedpermanent -
coinstringA cryptocurrency or token ticker symbol. -
typestring enum requiredWhat causes this rule to triggeradvancedWhitelistallTxbitcoinAddressWhitelistcoinAddressWhitelistcoinAddressBlacklisttransactionLimitvelocityLimitwebhook -
conditionobjectParameters for the typeONE OF
-
amountStringstring -
timeWindowintegerTime window in seconds for a velocity limit, between 1 and a month
-
amountStringstring -
timeWindowintegerTime window in seconds for a velocity limit, between 1 and 30 days
-
addressesarray of objectsAddresses allowed/restricted for a whitelist/blacklistONE OF
string
string
-
entriesarray of objectsEntries specifying which addresses/ wallets/ enterprises are on the whitelistentries object
-
itemstring requiredA valid blockchain address, wallet ID, enterprise ID, or organization ID. Must be unique in this whitelist. -
metaDataobjectAny data about this entry that is not used to determine when to enforce the policymetaData object
-
labelstringA client-specified label for this entry. Label must be unique or not set. -
ownerstringThe legal owner of the address, wallet, enterprise, or organization. -
addressstringThe address of the receiver wallet if the whitelist is of type 'walletId'.
-
-
typestring enum requiredthe kind of resource a list rule entry refers toaddresswalletIdenterpriseIdlinkAccountId -
verificationStatestring enumA state denoting whether entries have already been verified.unverifiedverified -
verifiedBystring enumThe source that verified this entry (unverifiedRule or fastWithdrawal)unverifiedRulefastWithdrawal
-
-
urlstringthe url to query for the webhook
-
-
actionobject requiredWhat happens when this rule is triggeredaction object
-
typestring enum requireddenygetApprovalgetFinalApprovalgetCustodianApprovalgetIdVerification -
userIdsarray of stringsFor a final approver action, who can approve
-
-
-
versioninteger required
-
-
-
allowBackupKeySigningboolean -
approvalsRequiredinteger required -
balanceStringstringTotal balance in base units (e.g. Satoshis) -
buildDefaultsobjectbuildDefaults object
-
minFeeRateinteger 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
minFeeRateon a per transaction basis with thefeeRateparameter. -
maxFeeRateinteger nullable(BTC only) The maximum fee rate (in base units) per kilobyte (or virtual kilobyte). For example, satoshis per kvByte. The
maxFeeRatelimits the fee rate generated by bothfeeMultiplierandnumBlocks.Note: The you can override
maxFeeRateon a per transaction basis with thefeeRateparameter. -
feeMultipliernumber nullable(UTXO only) Custom multiplier to the
feeRate. The resulting fee rate is limited by themaxFeeRate. For replace-by-fee (RBF) transactions (that includerbfTxIds), thefeeMultipliermust be greater than 1, since it's an absolute fee multiplier to the transaction being replaced.Note: The
maxFeeRatelimits the fee rate generated byfeeMultiplier. -
changeAddressTypestring enum nullable(UTXO only) The default script type to use for change for this wallet. Per transaction, you override the default with thechangeAddressTypeparameter. Ifdefaultis provided, it will clear thechangeAddressTypedefault on the wallet. Note that each UTXO coin has different address types available. For example, Only BTC supportsp2tr.p2shp2shP2wshp2wshp2trp2trMusig2default -
txFormatstring enum(UTXO only) The default transaction format to use for this wallet. Per transaction, you can override the default with thetxFormatparameter.legacypsbtpsbt-lite -
autoReserveUnspentsOnBuildMinsnumber nullable(UTXO only) Automatically reserve unspents when building a transaction.
-
-
coinstring requiredA cryptocurrency or token ticker symbol. -
coinSpecificobjectONE OF
-
creationFailurearray of stringsIncludes list of fail initialization txids -
pendingChainInitializationbooleanWhether the wallet needs to be initialized on the chain
-
allowQuantumUnsafeAddressesbooleanIf true, the wallet allows creation of addresses which are vulnerable to quantum attacks. Defaults to false.
-
rootAddressstring requiredWallet address to send or receive assets. -
lastChainIndexnumberIndex of last address that was derived. -
lastMemoIdstring requiredA running counter of the last known memo id. The first one is 0. -
pendingEcdsaTssInitializationbooleanIf true, this wallet cannot sign transactions or messages as the enterprise has not finished MPC setup.
-
needsKeyReshareAfterPasswordResetboolean deprecatedDeprecated: legacy password-reset recovery flag. Retained only for backward compatibility and will be removed in a future release. Do not rely on its presence or value. -
pendingSystemInitializationbooleanTrue if the wallet is still pending initialization. While true, users cannot create addresses or initiate withdrawals. -
userKeySigningRequiredbooleanTrue if the wallet requires user signatures for all transactions and refuses BitGo KMS signing. Defaults to true when not explicitly set. Only applicable for OFC wallets.
-
rootAddressstringRoot address of the wallet -
stellarUsernamestringUsername for the user's Stellar address -
homeDomainstringHome domain of a Stellar account -
stellarAddressstringEmail-like address associated to a Stellar account
-
-
custodialWalletobjectThe associated custodial wallet object -
custodialWalletIdstring -
deletedboolean required -
disableTransactionNotificationsboolean required -
enterprisestring -
freezeobjectfreeze object
-
timestring dateTime -
expiresstring dateTime -
reasonstring enumReason why the wallet was frozenTxIntentMismatchTxIntentMismatchRecipientTxIntentMismatchContractTxIntentMismatchApprovalUserRequestAdminRequest -
referenceIdstringOptional reference ID for tracking purposes -
adminOrUserIdstringThe user who froze the wallet
-
-
idstring required -
isColdboolean -
keysarray of strings -
labelstring required -
mintegerNumber of signatures required. This value must be 2 for hot wallets, 1 for ofc wallets, and not specified for custodial wallets. -
nintegerNumber of keys provided. This value must be 3 for hot wallets, 1 for ofc wallets, and not specified for custodial wallets. -
nodeIdstring -
receiveAddressobjectreceiveAddress object
-
idstringplatform public id for an address -
addressstring -
chaininteger enum011011202130314041 -
indexinteger -
coinstring -
lastNonceinteger -
walletstringThe wallet which contains this address -
coinSpecificobjectProperties which are specific to certain coin typescoinSpecific object
-
xlmobjectxlm object
-
memoIdstringLatest memo id generated for the wallet -
rootAddressstringRoot address of the wallet
-
-
txlmobjecttxlm object
- Same shape as
AddressCoinSpecificXlm.
- Same shape as
-
-
balanceobjectBalance 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 whenincludeBalancesquery param is passed as true.balance object
-
updatedstring date-timeThe last time a transaction affected the balance of this address -
balanceintegerThe cleared balance of the address -
balanceStringstringString representation ofbalance. Guaranteed to not lose precision. -
totalReceivedintegerThe total amount received on this address (in the chain's base unit) -
totalSentintegerThe total amount send from this address (in the chain's base unit) -
confirmedBalanceStringstringThe total balance of confirmed transactions for the address (in the chain's base unit). Guaranteed to not lose precision. -
spendableBalanceStringstringThe 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.
-
-
labelstring nullableA human-readable label for the address. -
addressTypestring enump2shp2shP2wshp2wshp2trp2trMusig2
-
-
recoverableboolean -
tagsarray of strings -
spendableBalanceStringstringSpendable balance in base units (e.g. Satoshis) -
unspentCountnumberNumber of unspent outputs present in the wallet -
startDatestring date-timeWallet creation time -
typestring enumThe type describes who owns the keys to the wallet and how they are stored.coldwallets are wallets where the private key of the user key is stored exclusively outside of BitGo's system.custodialmeans that this wallet is a cold wallet where BitGo owns the keys. Only customers of the BitGo Trust can create this kind of wallet.custodialPairedmeans 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 ofhotwallets.tradingwallets are trading accounts where the coin isofc.distributedCustodymeans You manage one key and another key agent manages the second key. BitGo manages the third keycoldcustodialcustodialPairedhottradingdistributedCustodyadvanced -
usersarray of objectsusers object
-
userstring -
permissionsarray of string enumsadminspendtradeview
-
-
customChangeKeySignaturesobjectSignatures 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
-
userstring -
backupstring -
bitgostring
-
-
multisigTypestring enumonchaintss -
multisigTypeVersionstring enumMPCv2
400
Bad Request
Response Body
ONE OF
-
errorstring requiredHuman-readable error message -
requestIdstring requiredClient request id -
contextobjectProperties that apply to a specific error name -
namestring requiredError code
-
errorstring requiredHuman-readable error message -
requestIdstring requiredClient request id -
contextobject requiredcontext object
-
idstring
-
-
namestring enum requiredError codeInvalidEnterpriseId
403
Forbidden
Response Body
object
-
errorstring requiredHuman-readable error message -
requestIdstring requiredClient request id -
contextobjectProperties that apply to a specific error name -
namestring requiredError code