Headless crypto deposits

Privy provides a useHeadlessCryptoDeposit hook that creates crypto deposit accounts and fetches indicative quotes. The hook does not render the Privy modal. The app owns the UI. This hook is React-only and is not available in React Native or Expo.

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

createCryptoDepositAccount requires an authenticated user and a dest-owner authorization signature. The hook signs that request with the user’s signer.

Prerequisites

Enable swaps and app-pays gas sponsorship as described in setup.

Access the hook

Import and initialize useHeadlessCryptoDeposit:

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

const {createCryptoDepositAccount, getQuote} = useHeadlessCryptoDeposit();

Create a deposit account

Call createCryptoDepositAccount with the destination wallet and an inline route (or an existing deposit configuration).

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

Your app can display each deposit_address. The same address is reusable for later deposits on that route. For Node.js and REST, see Create a deposit account.

Parameters

createCryptoDepositAccount accepts an object with the following fields:

string

required

Destination wallet to attach the deposit account to.

'inline_route' | 'deposit_config'

required

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

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.

Return value

createCryptoDepositAccount returns a Promise for {deposit_accounts}. Each entry matches the create response.

Get a quote

Call getQuote with a concrete source and destination pair. Quotes do not require a wallet ID or authorization signature.

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

This calls POST /v1/deposit_accounts/crypto/quote.

Parameters

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.

Return value

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

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>
  );
};

Create a deposit account

Node.js and REST for the same create endpoint

Setup

Enable swaps and app-pays gas sponsorship

Onramp modal

Privy-hosted funding UI with useAddFunds

Deposits

Fiat deposits

Crypto deposits

Onramp modal

Card onramps

Headless crypto deposits

Prerequisites

Access the hook

Create a deposit account

Parameters

Return value

Get a quote

Parameters

Return value

Error handling

Complete example

Create a deposit account

Setup

Onramp modal

​Prerequisites

​Access the hook

​Create a deposit account

​Parameters

​Return value

​Get a quote

​Parameters

​Return value

​Error handling

​Complete example

​Related

Create a deposit account

Setup

Onramp modal

Prerequisites

Access the hook

Create a deposit account

Parameters

Return value

Get a quote

Parameters

Return value

Error handling

Complete example

Related