Create a crypto deposit account

A crypto deposit account gives a wallet persistent deposit addresses. When receiving deposits on the same chain type as the wallet, the deposit address is the wallet itself. When receiving deposits on a different chain type as the wallet, the deposit address is a newly provisioned wallet assigned to the same owner. The 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.

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 match the destination wallet’s chain_type.

string

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

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

useHeadlessCryptoDeposit is experimental. Import it from @privy-io/react-auth/internal. The interface may change without a major SDK version bump.

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

const {createCryptoDepositAccount, getQuote} = useHeadlessCryptoDeposit();

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

The hook param for an existing configuration is depositConfigId.

Response

A successful response includes the following fields:

object[]

One entry per source route created for the destination wallet.

Hide properties

string

Address to sends funds to. If the source assets are on the same chain type as the wallet, this should be same as the wallet address.

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

Get a quote

React and React Native apps can call getQuote on useHeadlessCryptoDeposit. Quotes do not require a wallet ID or authorization signature. This calls POST /v1/deposit_accounts/crypto/quote.

const quote = await getQuote({
  source: {chain: 'base', asset: 'usdc'},
  destination: {chain: 'tempo', asset: 'pathusd'},
  inputAmount: '1.5',
  slippageBps: 50
});

getQuote accepts an object with the following fields:

object

required

Asset the quote prices as input. Unlike create, both chain and asset are required.

Hide properties

string

required

A quote is a specific route, so chain cannot be omitted.

string

required

object

required

Asset delivered to the destination wallet.

Hide properties

string

required

string

required

string

Amount as a decimal string in the source token’s standard unit (for example, "1.5" for 1.5 USDC). Not the smallest on-chain unit. Omit to quote approximately $50 of the source asset.

number

Slippage tolerance in basis points.

getQuote returns a Promise with the following fields:

string

Quoted input as a decimal string in the source token’s standard unit.

string

Estimated output as a decimal string in the destination token’s standard unit.

string

ISO 8601 timestamp when the quote was created.

Error handling

On React and React Native, createCryptoDepositAccount 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

getQuote rejects when the route is unsupported or source and destination are not both mainnet or both testnet. Your app should wrap calls in try/catch and show clear UI feedback.

Complete example

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

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

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

      setDepositAddress(deposit_accounts[0]?.deposit_address ?? null);
      setEstimatedOut(quote.estimated_output_amount);
    } 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>
          {estimatedOut ? ` for about ${estimatedOut} pathUSD` : ''}
        </p>
      )}
    </div>
  );
};

Next steps

Deposit modal

useDepositFunds for the prebuilt deposit UI

Setup

Enable swaps and app-pays gas sponsorship

Deposits

Fiat deposits

Crypto deposits

Deposit modal

Card onramps

Create a deposit account

Response

Get a quote

Error handling

Complete example

Next steps

Deposit modal

Setup

​Response

​Get a quote

​Error handling

​Complete example

​Next steps

Deposit modal

Setup

Response

Get a quote

Error handling

Complete example

Next steps