Create address

post/api/v2/{coin}/wallet/{walletId}/address

This API call is used to create a new receive address for your wallet. You may choose to call this API whenever a deposit is made. The BitGo API supports millions of addresses. Please check the “Coin-Specific Implementation” with regards to fee address management for Ethereum and consolidation transactions for Algorand and Tezos.

Note, in Ethereum, new addresses are not returned immediately. This is because creating a new Ethereum address requires a blockchain transaction, which must be confirmed before the address can be used. You can save the "id" field in the response and use it to query for the address value after a short delay.

Path Parameters

  • coinstringRequired
    A cryptocurrency or token ticker symbol.
    Example: "btc"
  • walletIdstringRequired
    Example: "59cd72485007a239fb00282ed480da1f"
    Pattern: ^[0-9a-f]{32}$

Request Body

chain integer
Allowed values: 0 1 10 11 20 21 30 31 40 41
Default: 1
Example: 1
labelOne of
A human-readable label for the address.
lowPriority boolean
Whether the deployment of the address forwarder contract should use a low priority fee key (ETH only)
Default: false
gasPriceOne of
Explicit gas price to use when deploying the forwarder contract (ETH only). If not given, defaults to the current estimated network gas price.
eip1559 object
(ETH forwarderVersion: 0 wallets only) Specify eip1559 fee parameters in forwarder 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.
forwarderVersion integer
(ETH only) Specify forwarder version to use in address creation. In an effort to improve the cost of creating ETH forwarders, we have developed a new set of forwarder contracts that take advantage of several improvements. Specifically, forwarders are deployed as a simple proxy to a single implementation (https://eips.ethereum.org/EIPS/eip-1167), and forwarders are deployed using the CREATE2 opcode, enabling them to only be deployed when needed (https://eips.ethereum.org/EIPS/eip-1014). These new forwarders operate identically to current ETH forwarders. This flag is used to specify the forwarder contract version desired when deploying a forwarder contract. Use 0 for the old forwarder (https://github.com/BitGo/eth-multisig-v2), 1 for the new fee-improved forwarder (https://github.com/BitGo/eth-multisig-v4), 2 for NFT supported forwarders, and 3 for TSS forwarders. Please note that for wallet version 2, you can only create forwarders with version 2. For TSS wallets, you can only create forwarders with version 3.
Minimum: >= 0
Maximum: <= 3
format string
Format to use for the new address, if the coin which supports multiple formats for an address. Currently, Bitcoin Cash is the only coin which has support for multiple address formats. For Bitcoin Cash, BitGo supports both the base58 (legacy) address format, as well as the newer CashAddr format. The default address format is base58. To request a CashAddr formatted address instead, use the value "cashaddr" as the format.
Example: cashaddr
javascript
1 2 3 4 wallet.createAddress({ label: 'My address' }).then(function (address) { // print new address console.dir(address); });

200 Response

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
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
xlm object
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.
updated string <date-time>
The last time a transaction affected the balance of this address
balance integer
The cleared balance of the address
Example: 50000
balanceString string
String representation of "balance". Guaranteed to not lose precision.
Example: 50000
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.
Example: 40000
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.
Example: 40000
addressType string
Allowed values: p2sh p2sh-p2wsh p2wsh
Example: p2sh

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