Express

POST

Generate wallet

Generate a new wallet for a coin. If you want a wallet to hold tokens, generate a wallet for the native coin of the blockchain (e.g. generate an ETH wallet to hold ERC20 tokens).

Calling this endpoint does all of the following:

  • Creates the user keychain locally on your machine and encrypts it with the provided passphrase (skipped if you pass a userKey).
  • Creates the backup keychain locally on your machine.
  • Uploads the encrypted user keychain and public backup keychain to BitGo.
  • Creates the BitGo key (and the backup key if you pass backupXpubProvider) on the service.
  • Creates the wallet on BitGo with the 3 public keys above.

ⓘ Many account-based assets, including Ethereum, require you to Fund Gas Tanks to initialize new wallets on chain. Ensure your gas tank has a sufficient balance to cover this cost before generating a new wallet.

Path Params

  • coin string required
    A cryptocurrency or token ticker symbol.

Query Params

  • includeKeychains boolean
    Include user, backup and bitgo keychains along with generated wallet

    Defaults to false

Body Params

object

  • label string required
  • multisigType string enum
    If absent, BitGo uses the default wallet type for the asset. This is relevant only for assets that support both multisignature (onchain) and MPC (tss) on the BitGo platform. These assets are: arbeth, eth, opeth, polygon, and soneium. These assets all default to tss. TRX (trx, ttrx) also supports MPC wallets — set multisigType to tss to create one; when omitted, TRX wallet creation is unchanged.
    onchaintss
  • type string enum
    The type of wallet, defined by key management and signing protocols. 'hot' and 'cold' are both self-managed wallets. If absent, defaults to 'hot'. 'trading' for Go Account wallets.
    hotcoldcustodialtrading
  • 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
  • backupXpubProvider string enum
    Optional key recovery service to provide and store the backup key
    dai
  • enterprise string required
    Enterprise id. This is required for Ethereum wallets since they can only be created as part of an enterprise
  • 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. 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

  • 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.
  • commonKeychain string
    Common keychain for self-managed cold MPC wallets.

Responses

200
OK

Response Body

ONE OF

  • id string

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

  • users array of objects
    Ids of users with access to the wallet
    users object
    • user string

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

    • permissions array of strings
      Array of permissions for the user
  • coin string
    Name of the blockchain the wallet is on
  • label string
    Name the user assigned to the wallet
  • m integer
    Number of signatures required for the wallet to send
  • n integer
    Number of signers on the wallet
  • keys array of strings
    Ids of wallet keys
  • keySignatures object
    Signatures for the backup and BitGo public keys signed by the user key
    keySignatures object
    • backupPub string
      Signature for the backup pub
    • bitgoPub string
      Signature for the BitGo pub
  • tags array of strings
    Tags set on the wallet
  • 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
  • balance integer
    Wallet balance as number
  • balanceString string
    Wallet balance as string
  • confirmedBalance integer
    Confirmed wallet balance as number
  • confirmedBalanceString string
    Confirmed wallet balance as string
  • spendableBalance integer
    Spendable wallet balance as number
  • spendableBalanceString string
    Spendable wallet balance as string
  • deleted boolean
    Flag which indicates the wallet has been deleted
  • isCold boolean
    Flag for identifying cold wallets
  • freeze object
    Freeze state (used to stop the wallet from spending)
    freeze object
    • 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
  • admin object
    Admin data (wallet policies)
  • approvalsRequired integer
    Number of admin approvals required for an action to fire
  • pendingApprovals array of objects
    Pending approvals on the wallet
    pendingApprovals object
    • id string

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

    • coin string
      A cryptocurrency or token ticker symbol.
    • wallet string

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

    • enterprise string

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

    • organization string

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

    • creator string

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

    • createDate string date-time
    • info object

      ANY OF

      • transactionRequest object
        transactionRequest object
        • buildParams object
        • coinSpecific object
        • comment string
        • fee string or integer
        • isUnsigned boolean
        • recipients array of objects
          recipients object
          • address string

            up to 500 characters

          • amount string or integer
          • data string
        • requestedAmount object
          requestedAmount object
          • Same shape as IntegerOrIntegerString.
        • sourceWallet string

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

        • triggeredPolicy string

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

        • validTransaction string
        • validTransactionHash string
      • type string enum
        transactionRequest
    • state string

      ANY OF

      string enum

    • scope string enum
      What kind of entity the Pending Approval is tied to
      enterprisewallet
    • userIds array of strings
      All the Users who should see this Pending Approval
    • approvalsRequired integer

      >= 1

    • walletLabel string
    • resolvers array of objects
      resolvers object
      • user string required
      • date string required
      • resolutionType string enum required
        approvedawaitingSignaturependingpendingBitGoAdminApprovalpendingCryptographicApprovalpendingCustodianApprovalpendingFinalApprovalpendingIdVerificationpendingVideoApprovalprocessingrejected
      • signatures array of strings required
      • videoApprover string
      • videoLink string
      • videoException string
    • addressLabels array of objects
      addressLabels object
      • address string required

        up to 500 characters

      • label string nullable required
        A human-readable label for the address.

        up to 250 characters

      • walletLabel string
  • allowBackupKeySigning boolean
    Flag for allowing signing with backup key
  • coinSpecific object
    Coin-specific data
  • clientFlags array of strings
  • 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