Skip to main content

​
Check a wallet’s position

Once Privy confirms a deposit, your app can query the wallet’s holdings using the get position endpoint. The assets_in_vault field shows the current redeemable value, including accrued yield.

​
Usage

To check a wallet’s position via REST API, make a GET request to:
https://auth.privy.io/api/v1/wallets/{wallet_id}/ethereum_yield_vault?vault_id={vault_id}

​
Parameters

​
vault_id
string
required
The unique identifier for the vault.

​
Returns

​
asset
object
The vault’s underlying asset, with address and symbol fields.
​
total_deposited
string
Total amount deposited into the vault, in the token’s smallest unit.
​
total_withdrawn
string
Total amount withdrawn from the vault, in the token’s smallest unit.
​
assets_in_vault
string
Current redeemable value of the wallet’s vault shares, including accrued yield.
​
shares_in_vault
string
Number of vault shares held by the wallet.

​
Example

curl https://auth.privy.io/api/v1/wallets/{wallet_id}/ethereum_yield_vault?vault_id={vault_id} \
  -H "privy-app-id: <your-app-id>" \
  -H "Authorization: Basic <credentials>"
Example response
{
  "asset": {
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "symbol": "USDC"
  },
  "total_deposited": "1000000",
  "total_withdrawn": "0",
  "assets_in_vault": "1050000",
  "shares_in_vault": "1000000000000000000"
}

​
Display balances

FieldWhat it representsHow to use it
assets_in_vaultCurrent redeemable value including yieldShow this as the user’s current balance
total_depositedSum of all depositsUse as the user’s cost basis
total_withdrawnSum of all withdrawalsSubtract from total_deposited for net contributions
shares_in_vaultRaw vault shares heldRarely shown to users — use assets_in_vault instead

​
Calculate earned yield

To display how much yield a wallet has earned: 
earned_yield = assets_in_vault - (total_deposited - total_withdrawn)
For example, if a wallet deposited 1,000 USDC, withdrew 200 USDC, and assets_in_vault is 850 USDC: 
earned_yield = 850 - (1000 - 200) = 850 - 800 = 50 USDC
All amounts are in the token’s smallest unit. For USDC (6 decimals), divide by 10^6 before displaying to users. For example, 1050000 equals 1.05 USDC.

​
Get vault details

Use the get vault details endpoint to retrieve vault-level information like current APY, TVL, and available liquidity.
Make a GET request to:
https://auth.privy.io/api/v1/ethereum_yield_vault/{vault_id}

​
Parameters

​
vault_id
string
required
The unique identifier for the vault.

​
Returns

​
id
string
The vault’s unique identifier.
​
name
string
Display name of the vault.
​
provider
string
The protocol powering the vault (e.g. "morpho").
​
vault_address
string
The onchain address of the vault contract.
​
asset_address
string
The address of the vault’s underlying token.
​
caip2
string
Chain identifier in CAIP-2 format.
​
user_apy
number
Current APY in basis points (e.g. 500 = 5%).
​
tvl_usd
number
Total value locked in the vault in USD.
​
available_liquidity_usd
number
Liquidity available for withdrawal in USD.

​
Example

curl https://auth.privy.io/api/v1/ethereum_yield_vault/{vault_id} \
  -H "privy-app-id: <your-app-id>" \
  -H "Authorization: Basic <credentials>"
Example response
{
  "id": "<your-vault-id>",
  "name": "Gauntlet USDC Prime",
  "provider": "morpho",
  "vault_address": "0x04422053aDDbc9bB2759b248B574e3FCA76Bc145",
  "asset_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "caip2": "eip155:1",
  "user_apy": 500,
  "tvl_usd": 1000000,
  "available_liquidity_usd": 500000
}

​
Track activity with webhooks

Privy emits webhooks when vault operations complete onchain. Subscribe to earn events from the Configuration > Webhooks page in the Privy Dashboard to keep your app synchronized without polling.
EventFired when
yield.deposit.confirmedPrivy confirms a vault deposit onchain
yield.withdraw.confirmedPrivy confirms a vault withdrawal onchain
yield.claim.confirmedPrivy confirms a reward claim onchain
For full webhook setup instructions and payload schemas, see the webhooks overview.

​
Next steps

Setup

Deploy a fee wrapper and configure a vault.

Deposit funds

Deposit assets from a wallet into a yield vault.

Withdraw and claim

Withdraw deposited assets with accrued yield and claim reward incentives.