Create an account

Accounts represent a grouping of wallets across multiple chain types and custody configurations. Think of accounts as a single unit of balance; create one account for each end user or customer of your service. When creating an account, specify:

a display name for the account
the account’s wallets, either by providing a wallets_configuration to create new wallets, or a list of wallet_ids to add existing wallets to the account. For each wallet in a wallets_configuration, the wallet’s owner can also be specified.

Accounts currently support non-custodial EVM wallets, custodial EVM wallets with Bridge, and non-custodial SVM wallets.

View the full API reference for creating an account.

Usage

REST API

To create an account via REST API, make a POST request to:

https://api.privy.io/v1/accounts

Body

display_name

string

An optional display name for the account.

Provide exactly one of the following (wallets_configuration or wallets_ids) to specify the account’s wallets:

wallets_configuration

object[]

required

New wallets to create for the account, each specified with a chain type and optional custody configuration. At least one wallet is required. Maximum of five wallets total per account.Mutually exclusive with wallet_ids.Each item in the array has the following fields:

Show wallets_configuration item fields

chain_type

'ethereum' | 'solana'

required

The chain type of the wallet to create.

custody

object

The custody configuration for the wallet. If omitted, the wallet is non-custodial.

Show custody fields

provider

string

required

The custody provider. Currently, 'bridge' is the only supported value.

provider_user_id

string

required

The custody provider’s unique ID for the KYC’ed entity associated with the wallet.

wallet_ids

string[]

required

IDs of existing wallets to include in the account. Must contain between one and five wallet IDs.Mutually exclusive with wallets_configuration.

Response

string

Unique ID of the created account.

display_name

string | null

The display name of the account, or null if not set.

wallets

object[]

The wallets included in the account. Each wallet contains:

id (string): The wallet ID
chain_type ('ethereum' | 'solana'): The chain type of the wallet
address (string): The on-chain address of the wallet
custody (object | undefined): The custody configuration, if the wallet is custodial

Examples

Using `wallets_configuration`

Use wallets_configuration to create new wallets as part of the account.Request

curl --request POST https://api.privy.io/v1/accounts \
  -u "your-app-id:your-app-secret" \
  -H "privy-app-id: your-app-id" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "<insert-display-name>",
    "wallets_configuration": [
      {
        "chain_type": "ethereum"
      },
      {
        "chain_type": "ethereum",
        "custody": {
          "provider": "bridge",
          "provider_user_id": "<insert-provider-user-id>"
        }
      },
      {
        "chain_type": "solana"
      }
    ]
  }'

Response

{
  "id": "<account-id>",
  "display_name": "<insert-display-name>",
  "wallets": [
    {
      "id": "<wallet-id>",
      "chain_type": "ethereum",
      "address": "<address>"
    },
    {
      "id": "<wallet-id>",
      "chain_type": "ethereum",
      "address": "<address>",
      "custody": {
        "provider": "bridge",
        "provider_user_id": "<insert-provider-user-id>"
      }
    },
    {
      "id": "<wallet-id>",
      "chain_type": "solana",
      "address": "<address>"
    }
  ]
}

Using `wallet_ids`

Use wallet_ids to group existing wallets into an account.Request

curl --request POST https://api.privy.io/v1/accounts \
  -u "your-app-id:your-app-secret" \
  -H "privy-app-id: your-app-id" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "<insert-display-name>",
    "wallet_ids": [
      "<wallet-id-1>",
      "<wallet-id-2>"
    ]
  }'

Response

{
  "id": "<account-id>",
  "display_name": "<insert-display-name>",
  "wallets": [
    {
      "id": "<wallet-id-1>",
      "chain_type": "ethereum",
      "address": "<address>"
    },
    {
      "id": "<wallet-id-2>",
      "chain_type": "solana",
      "address": "<address>"
    }
  ]
}

Digital asset accounts

Using accounts

Capabilities

Usage

Body

Response

Examples

Using `wallets_configuration`

Using `wallet_ids`

​Usage

​Body

​Response

​Examples

​Using wallets_configuration

​Using wallet_ids

Usage

Body

Response

Examples

Using `wallets_configuration`

Using `wallet_ids`