> ## 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.

# Create custodial wallets

> Create a new wallet custodied by a third-party provider.



## OpenAPI

````yaml post /v1/custodial_wallets
openapi: 3.1.0
info:
  version: 0.0.1
  title: Privy API
  description: >-
    REST API for Privy's wallet infrastructure — provision and manage wallets
    across EVM, Solana, and Bitcoin, authenticate users, sign transactions, and
    configure programmable policies and authorization intents.
  contact:
    name: Privy
    url: https://www.privy.io/
    email: support@privy.io
servers:
  - url: https://api.privy.io
security: []
tags:
  - name: Accounts
    description: Operations related to asset accounts
  - name: Aggregations
    description: Operations related to aggregations for tracking and measuring metrics
  - name: Apps
    description: Operations related to app settings and allowlist management
  - name: Client Auth
    description: OAuth token exchange and device authorization operations
  - name: Condition Sets
    description: Operations related to condition sets
  - name: Embedded wallets
    description: Operations related to embedded wallet creation and authentication
  - name: Fiat
    description: Operations related to fiat onramping and offramping
  - name: Intents
    description: Operations related to authorization intents for wallet actions
  - name: Key quorums
    description: Operations related to key quorums
  - name: Kraken Embed
    description: >-
      Operations for Kraken Embed integration, including quotes, trades, user
      management, and portfolio operations
  - name: OAuth
    description: >-
      OAuth 2.0 endpoints including Device Authorization Grant (RFC 8628) for
      CLI and limited-input device login flows
  - name: Organizations
    description: Operations related to organization secret management
  - name: Policies
    description: Operations related to policies
  - name: Shared
    description: Common schemas shared across resources
  - name: Swaps
    description: Operations for swapping tokens within wallets
  - name: Transactions
    description: Operations related to transactions
  - name: User signers
    description: Operations related to user signers
  - name: Users
    description: Operations related to users
  - name: Wallet Actions
    description: Operations related to wallet actions
  - name: Wallets
    description: Operations related to wallets
  - name: Webhooks
    description: >-
      Webhook events that Privy sends to your configured endpoint when specific
      actions occur in your app
  - name: Yield
    description: >-
      Operations for depositing and withdrawing funds from ERC-4626 yield vaults
      (Morpho, Aave)
paths:
  /v1/custodial_wallets:
    post:
      tags:
        - Wallets
      summary: Create custodial wallet
      description: Create a new wallet custodied by a third-party provider.
      operationId: createCustodialWallet
      parameters:
        - schema:
            type: string
            description: ID of your Privy app.
          required: true
          name: privy-app-id
          in: header
        - schema:
            type: string
            description: >-
              Idempotency keys ensure API requests are executed only once within
              a 24-hour window.
          required: false
          name: privy-idempotency-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustodialWalletCreateInput'
      responses:
        '200':
          description: Newly created custodial wallet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustodialWallet'
      security:
        - appSecretAuth: []
components:
  schemas:
    CustodialWalletCreateInput:
      type: object
      properties:
        chain_type:
          $ref: '#/components/schemas/CustodialWalletChainType'
        provider_user_id:
          type: string
          minLength: 1
          description: >-
            The resource ID of the beneficiary of the custodial wallet, given by
            the licensing provider.
        provider:
          $ref: '#/components/schemas/CustodialWalletProvider'
        owner:
          $ref: '#/components/schemas/OwnerInput'
        additional_signers:
          $ref: '#/components/schemas/AdditionalSignerInput'
        policy_ids:
          $ref: '#/components/schemas/PolicyInput'
      required:
        - chain_type
        - provider_user_id
        - provider
      additionalProperties: false
      description: The input for creating a custodial wallet.
      title: CustodialWalletCreateInput
      example:
        chain_type: ethereum
        provider: bridge
        provider_user_id: '1234567890'
      x-stainless-model: wallets.custodial_wallet_create_input
    CustodialWallet:
      type: object
      properties:
        id:
          type: string
        address:
          type: string
        chain_type:
          $ref: '#/components/schemas/CustodialWalletChainType'
        custody:
          $ref: '#/components/schemas/WalletCustodian'
        policy_ids:
          type: array
          items:
            type: string
            minLength: 24
            maxLength: 24
        additional_signers:
          $ref: '#/components/schemas/WalletAdditionalSigner'
        owner_id:
          anyOf:
            - $ref: '#/components/schemas/KeyQuorumId'
            - type: 'null'
      required:
        - id
        - address
        - chain_type
        - custody
        - owner_id
      description: Information about a custodial wallet.
      title: CustodialWallet
      example:
        id: id2tptkqrxd39qo9j423etij
        address: '0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2'
        chain_type: ethereum
        custody:
          provider: bridge
          provider_user_id: '1234567890'
        policy_ids: []
        additional_signers: []
        owner_id: null
      x-stainless-model: wallets.custodial_wallet
    CustodialWalletChainType:
      type: string
      enum:
        - ethereum
        - solana
      description: The chain type of the custodial wallet.
      title: CustodialWalletChainType
      x-stainless-model: wallets.custodial_wallet_chain_type
    CustodialWalletProvider:
      type: string
      enum:
        - bridge
      description: The provider of the custodial wallet.
      title: CustodialWalletProvider
      x-stainless-model: wallets.custodial_wallet_provider
    OwnerInput:
      anyOf:
        - $ref: '#/components/schemas/OwnerInputUser'
        - $ref: '#/components/schemas/OwnerInputPublicKey'
        - type: 'null'
        - type: 'null'
      description: >-
        The owner of the resource, specified as a Privy user ID, a P-256 public
        key, or null to remove the current owner.
      title: OwnerInput
      x-stainless-model: shared.owner_input
    AdditionalSignerInput:
      type: array
      items:
        $ref: '#/components/schemas/AdditionalSignerItemInput'
      description: Additional signers for the wallet.
      title: AdditionalSignerInput
      x-stainless-model: wallets.additional_signer_input
    PolicyInput:
      type: array
      items:
        type: string
        minLength: 24
        maxLength: 24
        format: cuid2
      maxItems: 1
      description: An optional list of up to one policy ID to enforce on the wallet.
      title: PolicyInput
      x-stainless-model: wallets.policy_input
    WalletCustodian:
      type: object
      properties:
        provider:
          type: string
          description: The custodian responsible for the wallet.
        provider_user_id:
          type: string
          description: The resource ID of the beneficiary of the custodial wallet.
      required:
        - provider
        - provider_user_id
      description: Information about the custodian managing this wallet.
      title: WalletCustodian
      x-stainless-model: wallets.wallet_custodian
    WalletAdditionalSigner:
      type: array
      items:
        $ref: '#/components/schemas/WalletAdditionalSignerItem'
      description: Additional signers for the wallet.
      title: WalletAdditionalSigner
      x-stainless-model: wallets.wallet_additional_signer
    KeyQuorumId:
      type: string
      format: cuid2
      description: A unique identifier for a key quorum.
      title: KeyQuorumId
      x-stainless-model: shared.key_quorum_id
    OwnerInputUser:
      type: object
      properties:
        user_id:
          type: string
      required:
        - user_id
      additionalProperties: false
      description: Owner input specifying a Privy user ID.
      title: OwnerInputUser
      x-stainless-model: shared.owner_input_user
    OwnerInputPublicKey:
      type: object
      properties:
        public_key:
          $ref: '#/components/schemas/P256PublicKey'
      required:
        - public_key
      additionalProperties: false
      description: Owner input specifying a P-256 public key.
      title: OwnerInputPublicKey
      x-stainless-model: shared.owner_input_public_key
    AdditionalSignerItemInput:
      type: object
      properties:
        signer_id:
          $ref: '#/components/schemas/KeyQuorumId'
        override_policy_ids:
          $ref: '#/components/schemas/PolicyInput'
      required:
        - signer_id
      additionalProperties: false
      description: >-
        A single additional signer for a wallet, with an optional policy
        override.
      title: AdditionalSignerItemInput
      x-stainless-model: wallets.additional_signer_item_input
    WalletAdditionalSignerItem:
      type: object
      properties:
        signer_id:
          $ref: '#/components/schemas/KeyQuorumId'
        override_policy_ids:
          $ref: '#/components/schemas/PolicyInput'
      required:
        - signer_id
      additionalProperties: false
      description: >-
        A single additional signer on a wallet, with an optional policy
        override.
      title: WalletAdditionalSignerItem
      x-stainless-model: wallets.wallet_additional_signer_item
    P256PublicKey:
      type: string
      description: A P-256 (secp256r1) public key.
      title: P256PublicKey
      x-stainless-model: shared.p_256_public_key
  securitySchemes:
    appSecretAuth:
      type: http
      scheme: basic
      description: >-
        Basic Auth header with your app ID as the username and your app secret
        as the password.

````