Create a crypto deposit account

A crypto deposit account gives a wallet persistent deposit addresses. By default, deposit addresses belong to dedicated source wallets owned by the depositing user. Destination address reuse requires an explicit strategy. The REST request body is a flat object discriminated by type:

'inline_route' | 'deposit_config'

required

Which create payload to send. inline_route takes source and destination. deposit_config reuses an existing deposit configuration via deposit_config_id.

'dedicated' | 'prefer_destination' | 'require_destination'

Optional for both inline_route and deposit_config. Omission always selects dedicated, including for existing routes.

dedicated: Reuse or create eligible dedicated source wallets, never the destination wallet.
prefer_destination: Use the eligible destination for its matching source chain family; use dedicated wallets otherwise.
require_destination: Require the destination to serve its own chain family when that family is requested, and fail without fallback if it cannot. Other requested families still use dedicated source wallets.

object

Required when type is inline_route. Assets the deposit address accepts. Chains must be EVM or Solana.

Hide properties

'all' | 'include' | 'exclude'

required

include accepts only the listed assets. exclude accepts all except the listed assets. all accepts every supported source.

object[]

Asset specs for include and exclude. Omit when mode is all.

Hide properties

string

Omit to match every supported chain for that asset.

object

Required when type is inline_route. Asset delivered to the destination wallet. Identifies exactly one asset on exactly one chain.

Hide properties

string

required

string

required

Must be in the same chain family as the destination wallet’s chain_type. An EVM chain such as tempo matches an ethereum wallet.

string

Required when type is deposit_config. ID of an existing deposit configuration to attach.

Deposit address behavior

The destination must be a Privy wallet owned 1-of-1 by a single user, with no authorization keys and no nested quorums. A user token must belong to that user. Source chain families are EVM and Solana. require_destination uses the destination only for its own family when that family is requested; other families still use dedicated source wallets. Exported wallets cannot act as deposit sources, including when reusing a destination address. An exported destination can still receive converted funds from dedicated source wallets. When reusing the destination wallet, both prefer_destination and require_destination remove all existing automation attachments, including matching and disabled attachments, then attach the requested automation. The shared automation configurations and attachments on other wallets are unchanged. dedicated does not modify the destination wallet’s attachments. Repeated calls for the same route and strategy reuse eligible source wallets.

Switching to dedicated, including by omitting the option, can change the returned deposit address without detaching previous routes. Explicit destination reuse can change which route the destination address serves by replacing all of its automation attachments. Use the latest returned deposit_address when displaying deposit instructions.

Examples

The body uses the optional deposit_address_strategy field for either request type, with the same strategy values and dedicated default described above. Include it in the signed body when provided. Do not add its default after signing a request that omits it.The field for an existing configuration is deposit_config_id.To create a crypto deposit account for a wallet, make a POST request to:

https://api.privy.io/v1/wallets/{wallet_id}/deposit_accounts/crypto

Below is a sample cURL command for this request:

curl --request POST https://api.privy.io/v1/wallets/{wallet_id}/deposit_accounts/crypto \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>" \
  -H "privy-authorization-signature: <dest-owner-signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inline_route",
    "deposit_address_strategy": "prefer_destination",
    "source": {
      "mode": "include",
      "values": [{"asset": "usdc", "chain": "base"}]
    },
    "destination": {
      "asset": "pathusd",
      "chain": "tempo"
    }
  }'

{
  "type": "deposit_config",
  "deposit_config_id": "<deposit-config-id>",
  "deposit_address_strategy": "prefer_destination"
}

Response

A successful response includes the following fields:

object[]

One entry per source route created for the destination wallet.

Hide properties

string

Address to send funds to. The selected strategy determines whether this belongs to a dedicated source wallet or the destination wallet.

string

ID of the source wallet behind this deposit address.

object

Assets this address accepts, using aliases when known.

Hide properties

'all' | 'include' | 'exclude'

Filter applied to this deposit address.

object[]

Accepted assets.

Hide properties

string

object

Asset and chain delivered to the destination wallet, using aliases when known.

Hide properties

string

{
  "deposit_accounts": [
    {
      "wallet_id": "insert-source-wallet-id",
      "deposit_address": "0x1234...abcd",
      "source": {
        "mode": "include",
        "values": [{"asset": "usdc", "chain": "base"}]
      },
      "destination": {"asset": "pathusd", "chain": "tempo"}
    }
  ]
}

Error handling

Create rejects on invalid configuration or failed requests. Common error cases include:

the user is not authenticated
the dest-owner request expires before it is sent
swaps or app-pays gas sponsorship are not enabled for the source chain
the route is unsupported
require_destination is set and the destination cannot serve its own chain family when that family is requested

Your app should wrap calls in try/catch and show clear UI feedback.

Next steps

Deposit modal

useDepositFunds for the prebuilt deposit UI

Setup

Enable swaps and app-pays gas sponsorship

Quotes

Indicative route quotes before creating an address

Orders

Poll sweep status after a deposit is sent

Deposits

Fiat deposits

Crypto deposits

Deposit modal

Create a deposit account

Deposit address behavior

Examples

Response

Error handling

Next steps

Deposit modal

Setup

Quotes

Orders

​Deposit address behavior

​Examples

​Response

​Error handling

​Next steps

Deposit modal

Setup

Quotes

Orders

Deposit address behavior

Examples

Response

Error handling

Next steps