Create a crypto deposit account

A crypto deposit account gives a destination wallet reusable deposit addresses. Each address accepts the assets your app chooses, and Privy converts deposits to one target asset. Privy returns one deposit address for each source chain family in the request, EVM or Solana. Before creating a deposit account, enable app-pays gas sponsorship on each source chain. The destination must be a Privy wallet owned by a single user.

Use createCryptoDepositAccount from the useHeadlessCryptoDeposit hook. The hook signs the request with the authenticated user’s signer.

useHeadlessCryptoDeposit is experimental and requires @privy-io/react-auth 3.46.0 or later. The interface may change without a major SDK version bump.

import {useHeadlessCryptoDeposit} from '@privy-io/react-auth';

const {createCryptoDepositAccount} = useHeadlessCryptoDeposit();

// Accept USDC on Base and deliver PathUSD on Tempo
const {deposit_accounts} = await createCryptoDepositAccount({
  walletId: '<destination-wallet-id>',
  type: 'inline_route',
  source: {
    mode: 'include',
    values: [{asset: 'usdc', chain: 'base'}]
  },
  destination: {asset: 'pathusd', chain: 'tempo'}
});

To use the destination wallet’s own address as the deposit address, set depositAddressStrategy:

const {deposit_accounts} = await createCryptoDepositAccount({
  walletId: '<destination-wallet-id>',
  type: 'inline_route',
  depositAddressStrategy: 'prefer_destination',
  source: {
    mode: 'include',
    values: [{asset: 'usdc', chain: 'base'}]
  },
  destination: {asset: 'pathusd', chain: 'tempo'}
});

To reuse an existing deposit configuration, pass its ID:

const {deposit_accounts} = await createCryptoDepositAccount({
  walletId: '<destination-wallet-id>',
  type: 'deposit_config',
  depositConfigId: '<deposit-config-id>'
});

ParameterscreateCryptoDepositAccount accepts an object with the following fields:

string

required

ID of the destination wallet. The authenticated user must own this wallet.

'inline_route' | 'deposit_config'

required

inline_route defines the route in the request with source and destination. deposit_config reuses an existing deposit configuration with depositConfigId.

object

Required when type is inline_route. Assets the deposit addresses accept. Chains must be EVM or Solana.

Show properties

'all' | 'include' | 'exclude'

required

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

object[]

Assets for include and exclude. Omit when mode is all.

Show properties

string

Asset alias or token contract address, such as usdc or 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

string

Chain alias or CAIP-2 identifier, such as base or eip155:8453. Omit to match every supported chain for that asset.

object

Required when type is inline_route. The one asset, on one chain, delivered to the destination wallet.

Show properties

string

required

Asset alias or token contract address, such as usdc or 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

string

required

Chain alias or CAIP-2 identifier, such as base or eip155:8453. Must be in the destination wallet’s chain family. For example, tempo matches an Ethereum wallet.

string

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

'dedicated' | 'prefer_destination' | 'require_destination'

Where deposit addresses live. Defaults to dedicated, which always uses separate source wallets. See where deposit addresses live.

ReturnscreateCryptoDepositAccount returns a Promise for an object with a deposit_accounts array. See response.Complete example

import {useState} from 'react';
import {useHeadlessCryptoDeposit} from '@privy-io/react-auth';

export const CryptoDepositPanel = ({walletId}: {walletId: string}) => {
  const {createCryptoDepositAccount} = useHeadlessCryptoDeposit();
  const [depositAddress, setDepositAddress] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(false);

  const onCreate = async () => {
    setIsLoading(true);
    try {
      const {deposit_accounts} = await createCryptoDepositAccount({
        walletId,
        type: 'inline_route',
        source: {
          mode: 'include',
          values: [{asset: 'usdc', chain: 'base'}]
        },
        destination: {asset: 'pathusd', chain: 'tempo'}
      });

      setDepositAddress(deposit_accounts[0]?.deposit_address ?? null);
    } catch (error) {
      console.error(error);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div>
      <button type="button" onClick={onCreate} disabled={isLoading}>
        {isLoading ? 'Creating...' : 'Get deposit address'}
      </button>
      {depositAddress && (
        <p>
          Send USDC on Base to <code>{depositAddress}</code>
        </p>
      )}
    </div>
  );
};

Response

Every SDK returns the API response unchanged, with snake_case fields:

object[]

One entry per source route created for the destination wallet.

Hide properties

string

Address to send funds to. This is the source wallet’s address.

string

ID of the source wallet. When the destination wallet is its own source, this is the destination wallet’s ID.

object

Assets this address accepts, using aliases when known.

object

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

{
  "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"}
    }
  ]
}

Show each deposit_address to users as the place to send the listed assets.

Deposit address behavior

Destination requirements. The destination must be a Privy wallet owned by a single user, with no authorization keys or nested key quorums. When a client SDK creates the account, the authenticated user must be that owner. Source wallet reuse. Repeated calls for the same route reuse the same source wallet while it remains eligible. A source wallet stays eligible while it serves only this route and has not been exported. Otherwise, Privy creates a new source wallet. Exported wallets. An exported wallet cannot be a source wallet. Exporting a source wallet for asset recovery stops conversions to it. An exported destination wallet can still receive converted funds from separate source wallets. Destination reuse. With prefer_destination or require_destination, Privy attaches the deposit route to the destination wallet. Other automations attached to the destination wallet are detached. If this route is already attached, Privy keeps it and re-enables it. The default dedicated strategy never changes the destination wallet’s automations.

Changing strategies can change the returned deposit address. Switching to dedicated, including by omitting the option, returns a separate source wallet’s address. Previous routes stay attached, so deposits sent to earlier addresses are still converted. Always show users the latest returned deposit_address.

Error handling

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

App-pays gas sponsorship is not enabled on a requested source chain. See setup.
The route is unsupported, or the destination chain is not in the destination wallet’s chain family.
The destination wallet is not owned by a single user, or the request is not authorized by that user.
require_destination is set and the destination wallet was exported.
The signed request expires before Privy receives it.

Some apps require the app secret for all wallet actions. For these apps, client SDK requests return a 401. Create the deposit account from a server with NodeJS or the REST API instead. Your app should wrap calls in try/catch and show clear UI feedback.

Next steps

Quote a route

Preview the delivered amount before a deposit

Track orders

Optionally check conversion status after a deposit

Deposit modal

Show a prebuilt deposit UI in React or React Native

Set up crypto deposits

Enable app-pays gas sponsorship on source chains

Deposits

Fiat deposits

Crypto deposits

Deposit modal

Create a crypto deposit account

Response

Deposit address behavior

Error handling

Next steps

Quote a route

Track orders

Deposit modal

Set up crypto deposits

​Response

​Deposit address behavior

​Error handling

​Next steps

Quote a route

Track orders

Deposit modal

Set up crypto deposits

Response

Deposit address behavior

Error handling

Next steps