Deposit funds - Privy Docs

Deposit assets from a wallet into a vault using the deposit endpoint. Privy handles the ERC-20 approval and deposit in a single call. The wallet depositing funds and the admin wallet will receive shares corresponding to the fee share split.

View the full API reference for the deposit endpoint.

If your app has gas sponsorship configured, usage of the /earn/ethereum/deposit endpoint will be gas-sponsored by default. There is no need to specify additional parameters for sponsorship.

Deposit flow

Privy approves the vault to spend the specified amount of the wallet’s ERC-20 tokens.
The vault converts the deposited assets into vault shares at the current share price.
Shares are split between the depositing wallet and your app’s admin wallet based on the fee percentage configured during setup.
The deposit is created as a wallet action with status pending. Privy prepares, signs, and broadcasts the transaction asynchronously. The status moves to succeeded once confirmed onchain.

The share_amount in the response is null while the action is pending. Once the action succeeds, it reflects the number of shares minted to the depositing wallet. To see the admin wallet’s fee shares, query the admin wallet’s position.

The wallet must hold enough of the deposit token to cover the full amount. If the balance is insufficient, the deposit fails. Your app should check the wallet’s token balance before initiating a deposit.

Usage

Node SDK
REST API

Use the deposit convenience method on the earn ethereum service to deposit assets into a vault.

const response = await privy.wallets().earn().ethereum().deposit('insert-wallet-id', {
  vault_id: '<your-vault-id>',
  amount: '1.5',
  authorization_context: {
    authorization_private_keys: ['<authorization-private-key>'],
  },
});

The method returns an EarnDepositActionResponse with the pending wallet action. Poll the status with get wallet action, or listen for the wallet_action.earn_deposit.succeeded webhook.

To deposit funds via REST API, make a POST request to:

https://api.privy.io/api/v1/wallets/{wallet_id}/earn/ethereum/deposit

Parameters

vault_id

string

required

The unique identifier for the vault. Copy this from the Privy Dashboard after deploying a fee wrapper.

amount

string

Human-readable decimal amount to deposit (e.g. "1.5" for 1.5 USDC). Exactly one of amount or raw_amount must be provided.

raw_amount

string

Amount to deposit in the token’s smallest unit (e.g. "1500000" for 1.5 USDC with 6 decimals). Exactly one of amount or raw_amount must be provided.

Wallets with owner_id present must provide an authorization signature as a request header for deposit operations.

Returns

string

The wallet action ID. Use this to poll status with get wallet action.

wallet_id

string

The ID of the wallet that deposited funds.

type

string

The action type. Always "earn_deposit" for this endpoint.

status

'pending' | 'succeeded' | 'rejected' | 'failed'

The current status of the deposit action.

caip2

string

CAIP-2 chain identifier for the deposit (e.g. "eip155:8453").

vault_id

string

The ID of the vault receiving the deposit.

vault_address

string

The ERC-4626 vault contract address.

asset_address

string

The address of the underlying asset token.

raw_amount

string

Amount deposited in the token’s smallest unit.

amount

string | undefined

Human-readable decimal amount (e.g. "1.5"). Only present when the token is known in the asset registry.

asset

string | undefined

Asset identifier (e.g. "usdc"). Only present when the token is known in the asset registry.

decimals

number | undefined

Number of decimals for the underlying asset. Only present when the token is known in the asset registry.

Vault shares received in base units. null until the action succeeds.

created_at

string

ISO 8601 timestamp of when the action was created.

steps

array | undefined

The execution steps. Only returned if ?include=steps is provided on a GET request.

Example

curl -X POST https://api.privy.io/api/v1/wallets/{wallet_id}/earn/ethereum/deposit \
  -H "privy-app-id: <your-app-id>" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "vault_id": "<your-vault-id>",
    "amount": "1.5"
  }'

Example response

{
  "id": "<action-id>",
  "wallet_id": "<your-wallet-id>",
  "type": "earn_deposit",
  "status": "pending",
  "caip2": "eip155:8453",
  "vault_id": "<your-vault-id>",
  "vault_address": "0x5224d0c05698eD4a97C771B62095929F293f1D60",
  "asset_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "raw_amount": "1500000",
  "amount": "1.5",
  "asset": "usdc",
  "decimals": 6,
  "share_amount": null,
  "created_at": "2025-04-01T12:00:00.000Z"
}

Poll the status with get wallet action, or listen for the wallet_action.earn_deposit.succeeded webhook to know when Privy confirms the deposit onchain.

A rejected status means the action failed before any transaction was signed or broadcast — for example, due to insufficient balance or a policy violation. Your app can safely retry the request. A failed status means a transaction was broadcast but reverted onchain. Inspect the action’s steps for details.

Next steps

Withdraw assets

Withdraw deposited assets with accrued yield.

​Deposit flow

​Usage

​Parameters

​Returns

​Example

​Next steps

Withdraw assets

Deposit flow

Usage

Parameters

Returns

Example

Next steps