Wallets Overview

The concept of a wallet is central to Prime’s architecture. Each wallet has a unique Wallet ID, and there are three main types:

• Trading Balance: A wallet that is part of an omnibus account, directly available for trading. Each asset within a portfolio has exactly one Trading Balance Wallet ID.
• Custodial Vault Wallet: A wallet maintained within Coinbase Custody, where assets are held offline and segregated. Multiple vault wallets may be created for each asset by calling Create Wallet. Each vault wallet has its own Wallet ID.
• Onchain Wallet: To learn more about this wallet type, visit Onchain Wallet

The Wallet ID is required in many Prime API requests, such as those for querying balances, initiating transactions, and retrieving deposit instructions.

​

Creating a Wallet

Trading Balance Wallets are automatically created under one of the following conditions:

• When a user first navigates to an asset in the Prime UI
• When a user places a trade for that asset
• After calling Create Wallet with the TRADING wallet type

To create a Vault Wallet, the Create Wallet endpoint must be called with the VAULT type. Below are examples of this process.

After a wallet creation request for a vault wallet is submitted, the response will include an Activity ID. Since most actions within Prime require consensus approval, a review step in the UI must be completed. Once the wallet creation is approved, the new wallet’s details, including its Wallet ID, can be looked up.

WalletsService walletsService = PrimeServiceFactory.createWalletsService(client);

CreateWalletRequest request = new CreateWalletRequest.Builder()
    .portfolioId("PORTFOLIO_ID_HERE")
    .type(WalletType.VAULT)
    .name("PRIME_API_EXAMPLE")
    .symbol("ETH")
    .build();

CreateWalletResponse response = walletsService.createWallet(request);

​

Finding a Wallet ID

Use the List Portfolio Wallets endpoint to retrieve all wallets for a portfolio, optionally filtering by wallet type or other parameters. If preferred, wallets may be located by name using a utility script, such as the Get Wallet by Name example from the Coinbase Samples scripts repository.

Below is an example of how to list all vault wallets for a portfolio.

WalletsService walletsService = PrimeServiceFactory.createWalletsService(client);

ListWalletsRequest request = new ListWalletsRequest.Builder()
    .portfolioId("PORTFOLIO_ID_HERE")
    .type(WalletType.VAULT)
    .build();

ListWalletsResponse response = walletsService.listWallets(request);

Please note: All requests discussed above require proper authentication. For more information, visit REST API Authentication.