Wallets Overview

The concept of a wallet is central to Prime’s architecture. Each wallet has a unique Wallet ID. A portfolio is either Prime Trading or Prime Custody, and the wallet type available to a portfolio depends on which it is. There are four main wallet types:

• Trading Balance (Prime Trading portfolios): The omnibus wallet for Prime Trading portfolios, enabling clients for trading and finance. Each asset within a portfolio has exactly one Trading Balance Wallet ID.
• Prime Custody Wallet (Prime Custody portfolios): The omnibus wallet for Prime Custody portfolios, enabling clients to trade, finance, and hold crypto assets fully within a qualified custodian. Each asset within a portfolio has exactly one Prime Custody Wallet ID.
• Custodial Vault Wallet (Available in both portfolio types): A wallet type 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. Assets are secured by a qualified custodian for eligible jurisdictions. In Europe, MiCA compliant custodial vault wallets are available.
• Onchain Wallet (Available in both portfolio types): 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 and Prime Custody 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
• When the Create Wallet API is called with the TRADING wallet type (or QC for Prime Custody Wallets)

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.

Java

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);

To learn more about this SDK, please visit the Prime Java SDK.

.NET

var walletsService = new WalletsService(client);

var request = new CreateWalletRequest("PORTFOLIO_ID_HERE")
{
    Type = WalletType.VAULT,
    Name = "PRIME_API_EXAMPLE",
    Symbol = "ETH",
}

var response = walletsService.CreateWallet(request);

To learn more about this SDK, please visit the Prime .NET SDK.

Go

walletsService := users.NewWalletsService(client)

request := &users.CreateWalletRequest{
    PortfolioId: "PORTFOLIO_ID_HERE",
    Type: "VAULT",
    Name: "PRIME_API_EXAMPLE",
    Symbol: "ETH",
}

response, err := walletsService.CreateWallet(context.Background(), request)

To learn more about this SDK, please visit the Prime Go SDK.

Python

from prime_sdk.credentials import Credentials
from prime_sdk.client import Client
from prime_sdk.services.wallets import WalletsService, CreateWalletRequest

credentials = Credentials.from_env("PRIME_CREDENTIALS")
client = Client(credentials)
wallets_service = WalletsService(client)

request = CreateWalletRequest(
    portfolio_id="PORTFOLIO_ID_HERE",
    name="PRIME_API_EXAMPLE",
    symbol="ETH",
    wallet_type="VAULT",
)

response = wallets_service.create_wallet(request)

To learn more about this SDK, please visit the Prime Python SDK.

CLI

primectl create-wallet --help

TS/JS

const walletsService = new WalletsService(client);

walletsService.getWalletDepositInstructions({
    portfolioId: 'PORTFOLIO_ID_HERE',
    type: WalletType.VAULT,
    name: "PRIME_API_EXAMPLE",
    symbol: "ETH",
}).then(async (response) => {
    console.log('Wallet: ', response);
})

To learn more about this SDK, please visit the Prime TS SDK.

Finding a Wallet ID

Use the List Portfolio Wallets endpoint to retrieve all wallets for a portfolio, optionally filtering by wallet type (e.g., ‘TRADING’ for Trading Balance, ‘QC’ for Prime Custody Wallets, ‘VAULT’ for Custodial Vault Wallets or ‘ONCHAIN’ for Onchain Wallets) 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. The same endpoint applies when listing Prime Custody Wallets — substitute the Prime Custody wallet type for VAULT in the type filter.

Java

WalletsService walletsService = PrimeServiceFactory.createWalletsService(client);

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

ListWalletsResponse response = walletsService.listWallets(request);

To learn more about this SDK, please visit the Prime Java SDK.

.NET

var walletsService = new WalletsService(client);

var request = new ListWalletsRequest("PORTFOLIO_ID_HERE")
{
    Type = WalletType.VAULT,
}

var response = walletsService.ListWallets(request);

To learn more about this SDK, please visit the Prime .NET SDK.

Go

walletsService := users.NewWalletsService(client)

request := &users.ListWalletsRequest{
    PortfolioId: "PORTFOLIO_ID_HERE",
    Type: "VAULT",
}

response, err := walletsService.ListWallets(context.Background(), request)

To learn more about this SDK, please visit the Prime Go SDK.

Python

from prime_sdk.credentials import Credentials
from prime_sdk.client import Client
from prime_sdk.services.wallets import WalletsService, ListWalletsRequest

credentials = Credentials.from_env("PRIME_CREDENTIALS")
client = Client(credentials)
wallets_service = WalletsService(client)

request = ListWalletsRequest(
    portfolio_id="PORTFOLIO_ID_HERE",
    type="VAULT",
)

response = wallets_service.list_wallets(request)

To learn more about this SDK, please visit the Prime Python SDK.

TS/JS

const walletsService = new WalletsService(client);

walletsService.listWallets({
    portfolioId: 'PORTFOLIO_ID_HERE',
    type: WalletType.VAULT,
}).then(async (response) => {
    console.log('Wallets: ', response);
})

To learn more about this SDK, please visit the Prime TS SDK.

CLI

primectl list-wallets --help

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