✍️User Positions

User Positions

Aggregated view of a user's investments grouped by vault/strategy. Combines deposit history, withdrawal history, and on-chain state to compute total invested, current value, and earnings per strategy.

List User Positions

GET /defi-vaults/v1/defi/user/:userAddress/positions

Returns one entry per vault the user has deposited into, with aggregated totals.

Headers

Header	Required	Description
X-JOIN-KEY	Yes	Your API key

Path Parameters

Parameter	Description
userAddress	User wallet address (checksummed or lowercase)

Response

{
  "userAddress": "0x1234...",
  "totalRecords": 2,
  "positions": [
    {
      "vaultAddress": "0x43481b8d38CAc19b102B59499D90AEb9BE698630",
      "vaultName": "Demo Vault USD",
      "userAddress": "0x1234...",
      "chainId": 43114,
      "apy": "4.80",
      "assetSymbol": "USDC",
      "assetDecimals": 6,
      "totalDepositedAssets": "7000000",
      "totalWithdrawnAssets": "0",
      "currentShares": "7000000000000000000",
      "sharePrice": "1000000",
      "currentValue": "7000000",
      "earnedAssets": "0",
      "depositCount": 5,
      "startDate": "2026-03-21T15:17:08.000Z",
      "lastDepositDate": "2026-03-22T00:54:56.000Z",
      "statusBreakdown": {
        "pending": 0,
        "claimable": 0,
        "completed": 5
      }
    }
  ]
}

Position Fields

Field	Type	Description
vaultAddress	string	Vault contract address
vaultName	string	Vault display name
userAddress	string	User wallet address
chainId	number	Chain where the vault is deployed
apy	string	Current annualized yield (%)
assetSymbol	string	Underlying asset symbol (e.g. "USDC")
assetDecimals	number	Underlying asset decimals (e.g. 6 for USDC)
totalDepositedAssets	string	Sum of all deposit amounts (smallest unit)
totalWithdrawnAssets	string	Sum of all withdrawal amounts (smallest unit)
currentShares	string	Shares currently in the user's wallet (smallest unit)
sharePrice	string	Price of 1 share in asset units (smallest unit)
currentValue	string	Current value of shares in asset terms (smallest unit)
earnedAssets	string	Net earnings: currentValue + totalWithdrawn - totalDeposited (smallest unit, can be negative)
depositCount	number	Total number of deposits made
startDate	string	ISO 8601 timestamp of the first deposit
lastDepositDate	string	ISO 8601 timestamp of the most recent deposit
statusBreakdown	object	Count of deposits by status

How earnedAssets is Computed

earnedAssets = currentValue + totalWithdrawnAssets - totalDepositedAssets

• currentValue = on-chain balanceOf(user) * sharePrice / 10^shareDecimals

• totalWithdrawnAssets = sum of all Withdraw event amounts for this user on this vault

• totalDepositedAssets = sum of all DepositRequest event amounts

earnedAssets can be negative when a deposit is still pending (it counts as deposited but has no current value yet because the curator hasn't settled it).

Notes

• Positions are sorted by most recent deposit first.

• Only vaults where the user has made at least one deposit are returned.

• All amounts are in the smallest unit of the underlying asset (e.g. 6 decimals for USDC: "1000000" = 1 USDC).

Errors

Status	Error	Description
400	Missing or invalid userAddress	Address not valid
401	Unauthorized: Missing client ID	No API key provided
404	No vaults configured for this client	Client has no vaults

---

Get Position Detail

GET /defi-vaults/v1/defi/user/:userAddress/positions/:vaultAddress

Returns the aggregated position for a specific vault plus a paginated list of individual deposits.

Headers

Header	Required	Description
X-JOIN-KEY	Yes	Your API key

Path Parameters

Parameter	Description
userAddress	User wallet address
vaultAddress	Vault contract address

Query Parameters

Parameter	Required	Default	Description
limit	No	50	Max deposits to return (max 100)
offset	No	0	Number of deposits to skip

Response

{
  "userAddress": "0x1234...",
  "position": {
    "vaultAddress": "0x43481b8d38CAc19b102B59499D90AEb9BE698630",
    "vaultName": "Demo Vault USD",
    "userAddress": "0x1234...",
    "chainId": 43114,
    "apy": "4.80",
    "assetSymbol": "USDC",
    "assetDecimals": 6,
    "totalDepositedAssets": "7000000",
    "totalWithdrawnAssets": "0",
    "currentShares": "7000000000000000000",
    "sharePrice": "1000000",
    "currentValue": "7000000",
    "earnedAssets": "0",
    "depositCount": 5,
    "startDate": "2026-03-21T15:17:08.000Z",
    "lastDepositDate": "2026-03-22T00:54:56.000Z",
    "statusBreakdown": {
      "pending": 0,
      "claimable": 0,
      "completed": 5
    }
  },
  "totalRecords": 5,
  "hasMore": false,
  "deposits": [
    {
      "depositId": "0x80c15bf9...",
      "vaultAddress": "0x43481b8d38CAc19b102B59499D90AEb9BE698630",
      "vaultName": "Demo Vault USD",
      "userAddress": "0x1234...",
      "chainId": 43114,
      "status": "completed",
      "statusDescription": "Shares have been claimed and are in the wallet",
      "amounts": {
        "depositedAssets": "1000000",
        "pendingDeposit": "0",
        "claimableShares": "0",
        "currentShares": "7000000000000000000"
      },
      "vault": {
        "apy": "4.80",
        "assetSymbol": "USDC",
        "assetDecimals": 6,
        "sharePrice": "1000000"
      },
      "epochId": 5,
      "timestamp": "2026-03-22T00:54:56.000Z",
      "transactionHash": "0x80c15bf9..."
    }
  ]
}

Response Fields

Field	Type	Description
userAddress	string	Queried user address
position	UserPositionEntry	Aggregated position (same fields as in the list endpoint)
totalRecords	number	Total number of individual deposits in this vault
hasMore	boolean	Whether more deposits exist beyond the current page
deposits	UserDepositEntry[]	Individual deposits sorted by timestamp (newest first)

Errors

Status	Error	Description
400	Missing or invalid userAddress	Address not valid
400	Missing or invalid vaultAddress	Address not valid
401	Unauthorized: Missing client ID	No API key provided
404	No vaults configured for this client	Client has no vaults
404	No deposits found for this user on this vault	User has no deposits on this vault