Wallets

Create wallet

Changed on

Creates a new wallet on the requested chain and for the requested owner.

post/v1/wallets

Request

  • Base URL
    https://api.privy.io
  • URL
    https://api.privy.io/v1/wallets
  • Auth
    HTTP basic

Headers

privy-app-idstring required

ID of your Privy app.

privy-idempotency-keystring

Idempotency keys ensure API requests are executed only once within a 24-hour window.

Request body

chain_type'ethereum' | 'solana' | 'cosmos' | 'stellar' | 'sui' | 'aptos' | 'movement' | 'tron' | 'bitcoin-segwit' | 'bitcoin-taproot' | 'pearl' | 'near' | 'ton' | 'starknet' | 'xrpl' | 'spark' required

The wallet chain types.

display_namestring

A human-readable label for the wallet.

external_idstring

A customer-provided identifier for mapping to external systems. URL-safe characters only ([a-zA-Z0-9_-]), max 64 chars. Write-once: cannot be changed after creation.

policy_idsstring[]

List of policy IDs for policies that should be enforced on the wallet. Currently, only one policy is supported per wallet.

owner_idstring cuid2 nullable

The key quorum ID to set as the owner of the resource. If you provide this, do not specify an owner.

Example request

{
  "chain_type": "ethereum",
  "external_id": "my-order-123"
}

Response

Newly created wallet.

idstring required

Unique ID of the wallet. This will be the primary identifier when using the wallet in the future.

addressstring required

Address of the wallet.

display_namestring

A human-readable label for the wallet.

external_idstring

A customer-provided identifier for mapping to external systems. URL-safe characters only ([a-zA-Z0-9_-]), max 64 chars. Write-once: cannot be changed once set.

public_keystring

The compressed, raw public key for the wallet along the chain cryptographic curve.

created_atnumber required

Unix timestamp of when the wallet was created in milliseconds.

chain_type'ethereum' | 'solana' | 'cosmos' | 'stellar' | 'sui' | 'aptos' | 'movement' | 'tron' | 'bitcoin-segwit' | 'bitcoin-taproot' | 'pearl' | 'near' | 'ton' | 'starknet' | 'xrpl' | 'spark' required

The wallet chain types.

policy_idsstring[] required

List of policy IDs for policies that are enforced on the wallet.

owner_idstring cuid2 nullable required

The key quorum ID of the owner of the wallet.

parent_wallet_idstring nullable

ID of the HD root wallet this wallet was derived from, or null if it was not derived from another wallet.

exported_atnumber nullable required

Unix timestamp of when the wallet was exported in milliseconds, if the wallet was exported.

imported_atnumber nullable required

Unix timestamp of when the wallet was imported in milliseconds, if the wallet was imported.

authorization_thresholdnumber

The number of keys that must sign for an action to be valid.

archived_atnumber nullable

Unix timestamp of when the wallet was archived in milliseconds, or null if the wallet is active.

chain'base' | 'solana' | 'tempo'

The chain of this wallet, only present for custodial wallets.

Example response

{
  "id": "id2tptkqrxd39qo9j423etij",
  "address": "0xF1DBff66C993EE895C8cb176c30b07A559d76496",
  "display_name": "Treasury",
  "external_id": "my-order-123",
  "chain_type": "ethereum",
  "policy_ids": [],
  "additional_signers": [],
  "owner_id": "rkiz0ivz254drv1xw982v3jq",
  "parent_wallet_id": null,
  "entity": {
    "id": "jorpjo4rfxj62nx1itt8y1zt",
    "type": "user"
  },
  "created_at": 1741834854578,
  "exported_at": null,
  "imported_at": null,
  "archived_at": null
}

Changes

  • 4facbfa7f9d4Revision changes
    • warning

      added the new xrpl enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new xrpl enum value to the request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      the response's property pattern ^[a-zA-Z0-9_-]+$ was added for the status

  • 41cbc1e43b72Revision changes
    • info

      added the optional property to the response with the status