Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.privy.io/llms.txt

Use this file to discover all available pages before exploring further.

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

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:
​
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

​
id
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>"
    }
  ]
}