Ctrl+K

Generate wallet

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

This API call creates a new wallet. Under the hood, the SDK (or BitGo Express) does the following:

  1. Creates the user keychain locally on the machine, and encrypts it with the provided passphrase (skipped if userKey is provided).
  2. Creates the backup keychain locally on the machine.
  3. Uploads the encrypted user keychain and public backup keychain.
  4. Creates the BitGo key (and the backup key if backupXpubProvider is set) on the service.
  5. Creates the wallet on BitGo with the 3 public keys above.

ⓘ Ethereum 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 on the enterprise dropdown. Each enterprise has a fee address which will be used to pay for transaction fees on all Ethereum wallets in that enterprise. The fee address is displayed in the dashboard of the website, please fund it before creating a wallet.

ⓘ You cannot generate a wallet by passing in a subtoken as the coin. Subtokens share wallets with their parent coin and it is not possible to create a wallet specific to one token.

ⓘ This endpoint should be called through BitGo Express if used without the SDK, such as when using cURL.

Path Parameters

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

Query Parameters

  • includeKeychainsbooleanDefault: false
    Include user, backup and bitgo keychains along with generated wallet

Request Body

label string required
Example: My Wallet
multisigType string
If absent, BitGo uses the default wallet type for the asset.
Allowed values: onchain tss blsdkg
type string
The type of wallet, defined by key management and signing protocols. 'hot' and 'cold' are both self-managed wallets. If absent, defaults to 'hot'.
Allowed values: hot cold custodial
passphrase string
Passphrase to be used to encrypt the user key on the wallet
userKey string
User provided public key
backupXpub string
public part of a key pair
Example: xpub661MyMwAqRbcGMVhmc7wqQRYMtcX9LAvSj1pjB213y5TsrkV2uuzJjWnjBrT1FUeNWGPjaVm5p7o6jdNcQJrV1cy3a1R8NQ9m7LuYKA8RpH
backupXpubProvider string
Optional key recovery service to provide and store the backup key
Allowed value: dai
enterprise string required
Enterprise id. 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}$
disableTransactionNotifications boolean
Flag for disabling wallet transaction notifications
passcodeEncryptionCode string
The passphrase used for decrypting the encrypted wallet passphrase during wallet recovery
coldDerivationSeed string
Seed that derives an extended user key or common keychain for a cold wallet.
gasPrice integer
Gas price to use when deploying an Ethereum wallet
disableKRSEmail boolean
Flag for preventing KRS from sending email after creating backup key
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.
Minimum: >= 0
Maximum: <= 3
Default: 1
isDistributedCustody boolean
True, if the wallet type is a distributed-custodial. If passed, you must also pass the 'enterprise' parameter.
bitgoKeyId string
BitGo key ID for self-managed cold MPC wallets.
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
commonKeychain string
Common keychain for self-managed cold MPC wallets.

200 Response

One of
id string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
users array[object]
Ids of users with access to the wallet
user string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
permissions array[string]
Array of permissions for the user
Example: ["admin","view","spend"]
coin string
Name of the blockchain the wallet is on
Example: tbtc4
label string
Name the user assigned to the wallet
Example: My TBTC4 Wallet
m integer
Number of signatures required for the wallet to send
Example: 2
n integer
Number of signers on the wallet
Example: 3
keys array[string]
Ids of wallet keys
Example: 59cd72485007a239fb00282ed480da1f
keySignatures object
Signatures for the backup and BitGo public keys signed by the user key
backupPub string
Signature for the backup pub
Example: 1fe81d0c91457d89993b01475bfb9e5809067ae046926faeab6e63beea009d8dd460387e0c3843034570798a9c2bcc1dbbea2988ee5a36979e0bbe6e02f7840af2
bitgoPub string
Signature for the BitGo pub
Example: 209d0e9a6d4352b66fae0a35ce62c1059bcc4db9e2883abc4f1b3d20481c5cebb7299c581efd9e0151abaf2496da7c6d75d276de36ed3de37c94e9cc5a2ea77e59
tags array[string]
Tags set on the wallet
Example: 59cd72485007a239fb00282ed480da1f
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
balance integer
Wallet balance as number
Example: 0
balanceString string
Wallet balance as string
Example: 0
confirmedBalance integer
Confirmed wallet balance as number
Example: 0
confirmedBalanceString string
Confirmed wallet balance as string
Example: 0
spendableBalance integer
Spendable wallet balance as number
Example: 0
spendableBalanceString string
Spendable wallet balance as string
Example: 0
deleted boolean
Flag which indicates the wallet has been deleted
Example: false
isCold boolean
Flag for identifying cold wallets
Example: false
freeze object
Freeze state (used to stop the wallet from spending)
Example: {}
time string <date-time>
Time when the wallet becomes frozen
expires string <date-time>
Time when the wallet is unfrozen and allowed to spend
disableTransactionNotifications boolean
Flag for disabling wallet transaction notifications
Example: false
admin object
Admin data (wallet policies)
Example: {}
approvalsRequired integer
Number of admin approvals required for an action to fire
Example: 1
pendingApprovals array[object]
Pending approvals on the wallet
Example: []
id string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
coin string
A cryptocurrency or token ticker symbol.
Example: btc
wallet string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
enterprise string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
organization string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
creator string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
createDate string <date-time>
infoAny of
stateAny of
Allowed values: pending awaitingSignature pendingFinalApproval pendingCustodianApproval pendingVideoApproval pendingIdVerification
scope string
What kind of entity the Pending Approval is tied to
Allowed values: enterprise wallet
userIds array[string]
All the Users who should see this Pending Approval
Example: 59cd72485007a239fb00282ed480da1f
approvalsRequired integer
Minimum: >= 1
Example: 1
walletLabel string
resolvers array[object]
addressLabels array[object]
Address labels of recipients in this Pending Approval
allowBackupKeySigning boolean
Flag for allowing signing with backup key
Example: false
coinSpecific object
Coin-specific data
clientFlags array[string]
recoverable boolean
Flag indicating whether this wallet's user key is recoverable with the passphrase held by the user.
startDate string <date-time>
Time when this wallet was created
hasLargeNumberOfAddresses boolean
Flag indicating that this wallet is large (more than 100,000 addresses). If this is set, some APIs may omit properties which are expensive to calculate for wallets with many addresses (for example, the total address counts returned by the List Addresses API).
config object
Custom configuration options for this wallet