> ## Documentation Index > Fetch the complete documentation index at: https://docs.superform.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Get User Balance ## OpenAPI ````yaml https://persephone.superform.xyz/openapi.json get /v1/balances/{address} openapi: 3.1.0 info: title: Superform API description: API for interacting with the Superform platform version: 33.2.0 contact: name: Superform Team url: https://superform.xyz servers: - url: https://persephone.superform.xyz security: - SF-API-KEY: [] tags: - name: RestAPIService paths: /v1/balances/{address}: get: tags: - RestAPIService summary: Get User Balance operationId: RestAPIService_GetUserBalances parameters: - name: address description: User wallet address in: path required: true schema: type: string - name: force in: query required: false schema: type: boolean - name: use_rpc in: query required: false schema: type: boolean - name: balances_provider description: >- Optional balances provider override (one of: zerion, dune, debank, zapper, octav) in: query required: false schema: type: string responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/restGetUserBalancesResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/rpcStatus' components: schemas: restGetUserBalancesResponse: type: object properties: balances: type: array items: $ref: '#/components/schemas/commonBalance' total_portfolio_value_usd: type: number format: double total_vault_share_value_usd: type: number format: double avg_vault_share_apy: type: number format: double portfolio_performance: $ref: '#/components/schemas/commonPortfolioPerformance' hypercore: $ref: '#/components/schemas/commonHyperCoreBalance' rpcStatus: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: $ref: '#/components/schemas/protobufAny' commonBalance: type: object properties: user_address: type: string amount: type: string chain_id: type: string format: uint64 decimals: type: integer format: int32 icon: type: string is_stable: type: boolean is_btc: type: boolean is_eth: type: boolean name: type: string price: type: string symbol: type: string last_updated: type: string format: date-time token_address: type: string token_type: type: string title: USD, BTC, ETH, or blank value_usd: type: string value_btc: type: string value_eth: type: string vault_id: type: string vault: $ref: '#/components/schemas/commonSuperVault' assets: type: array items: $ref: '#/components/schemas/commonAssetMeta' performance: $ref: '#/components/schemas/commonBalancePerformance' action: type: string title: >- Action and Status are only populated in staging (mrt_balances_api_v3): action: 'transaction', 'withdrawal-request', 'withdrawal-request-cancellation' status: 'available', 'pending', 'fulfilled' status: type: string strategy_id: type: string title: Strategy ID is only populated in staging (mrt_balances_api_v6) underlying_amount: type: string description: >- Underlying-asset amount for vault-backed balances. Same units as the underlying asset (Assets[0].decimals), not vault-share decimals. Empty for non-vault balances or when share pricing is unavailable. See SUP-19361. token_sub_type: type: string example: token enum: - token - stock description: >- Asset classification for ERC-20 balances. Allowed values: token, stock. Empty for non-ERC-20 balances or unknown assets. title: Balance represents a user's token balance commonPortfolioPerformance: type: object properties: portfolio_value_usd: type: number format: double total_pnl: type: number format: double total_unrealized_pnl: type: number format: double growth: type: number format: double unrealized_breakdown: $ref: '#/components/schemas/commonPnLBreakdown' total_realized_pnl: type: number format: double realized_breakdown: $ref: '#/components/schemas/commonPnLBreakdown' commonHyperCoreBalance: type: object properties: perp_account_value_usd: type: number format: double description: >- perp_account_value_usd is HyperCore marginSummary.accountValue: posted margin plus unrealized PnL. perp_margin_used_usd: type: number format: double perp_withdrawable_usd: type: number format: double spot_usdc_value_usd: type: number format: double description: >- spot_usdc_value_usd is HyperCore spot USDC valued 1:1. It is the funding token, so it is broken out separately from the rest of spot. total_value_usd: type: number format: double description: >- total_value_usd is the amount this account contributes to total_portfolio_value_usd. That is its definition, and clients rely on it to know not to add this object to either portfolio total. It is normally perp_account_value_usd plus spot_value_usd. It is NOT when the read was incomplete: a spot-degraded observation knows the perp side and nothing about the spot side, so publishing it would value the user's spot holdings at zero. The totals then fall back to the last complete valuation, and this field reports that fallback - which is what was actually counted - while the other fields go on describing the read. spot_unavailable is the signal that the two differ. spot_balances: type: array items: $ref: '#/components/schemas/commonHyperCoreSpotBalance' stale: type: boolean description: >- stale is true when this is a last-known-good cached observation rather than the newest upstream observation. This can follow request-budget exhaustion, an upstream read failure, or replacement of an incomplete spot read with the last complete valuation. Use last_updated for age; stale does not identify the fallback reason. spot_unavailable: type: boolean description: >- spot_unavailable is true when the perp read succeeded but the spot read did not, so spot_usdc_value_usd is unknown rather than zero. last_updated: type: string format: date-time spot_value_usd: type: number format: double description: |- spot_value_usd is every priced HyperCore spot token including USDC. Unpriced rows are excluded rather than counted as zero. description: >- HyperCoreBalance carries a user's Hyperliquid HyperCore holdings, which are off-EVM and therefore invisible to every balance provider and RPC read. Without it a funded perps user's portfolio total is short by the amount they deposited, which reads to them as lost money rather than moved money. Scope note. total_value_usd is folded into total_portfolio_value_usd and portfolio_performance.portfolio_value_usd, and HyperCore PnL is folded into total_pnl_usd and into the unrealized and realized totals: there is ONE set of portfolio figures covering vaults and HyperCore together, not a separate perps set to add on. total_pnl_usd is therefore unrealized plus realized, for a perps user exactly as for a vault one. Unrealized comes from open positions' unrealizedPnl in clearinghouseState; realized is the remainder, which is also where funding payments land - the cost-basis feed excludes them, so they reach PnL through accountValue, and funding is realized. What stays vault-only: growth, which means yield plus rewards and is neither of those for a perp; and the per-source breakdowns (underlying, yield, rewards), because perp PnL decomposes into none of them. /v1/user/pnl/historical carries HyperCore in its aggregates too, with the per-snapshot hypercore_* fields exposed so a client can render a vault-only series. There is no history to backfill - Hyperliquid publishes none and cost basis accumulates forward from the first read - so a series steps when HyperCore first appears rather than being reconstructed backwards. Do not add hypercore.total_value_usd to either portfolio total; it is already in both. protobufAny: type: object properties: '@type': type: string additionalProperties: {} commonSuperVault: type: object properties: id: type: string title: chain_id + "_" + address address: type: string chain_id: type: string format: uint64 name: type: string symbol: type: string decimals: type: integer format: int32 friendly_name: type: string category: type: string title: yield, staking, rwa, etc type: type: string example: '4626' enum: - '4626' - fully_async_7540 - async_deposit_7540 - async_redeem_7540 description: >- Canonical vault standard. Allowed values: 4626, fully_async_7540, async_deposit_7540, async_redeem_7540. description: type: string short_description: type: string description: Optional short vault description. Maximum 200 characters. visibility: type: string example: listed description: 'Visibility of the vault. One of: listed, unlisted, hidden, featured.' availability: type: string example: available description: >- Availability of the vault. One of: available, unavailable, paused, withdraw_only, deposit_only. risk_rating: type: string risk_data: $ref: '#/components/schemas/commonVaultRiskData' status_message: type: string external_url: type: string has_rewards: type: boolean description: Kept for backwards compatibility with current frontend consumers. is_on_mobile: type: boolean has_timelock: type: boolean timelock_duration: type: string format: uint64 timelock_unit: type: string is_supervault: type: boolean is_on_earn_page: type: boolean is_supervault_v2: type: boolean asset_ids: type: array items: type: string title: many-to-many association provider_ids: type: array items: type: string title: many-to-many association yield_source_ids: type: array items: type: string title: identifiers for underlying yield sources metadata: $ref: '#/components/schemas/commonVaultMetadata' stats_basic: $ref: '#/components/schemas/commonVaultStatsBasic' deployment_date: type: string format: date-time title: date deployed onchain created_at: type: string format: date-time title: date listed on superform providers: type: array items: $ref: '#/components/schemas/commonSuperVaultProvider' assets: type: array items: $ref: '#/components/schemas/commonSuperVaultAsset' rewards: type: array items: $ref: '#/components/schemas/commonSuperVaultReward' chain: $ref: '#/components/schemas/commonSuperVaultChain' commonAssetMeta: type: object properties: asset_id: type: string is_btc: type: boolean is_eth: type: boolean is_stable: type: boolean name: type: string symbol: type: string price: type: number format: double description: Omitted when no fresh/safe latest price is available. decimals: type: integer format: int64 icon: type: string chain_id: type: string format: uint64 address: type: string commonBalancePerformance: type: object properties: cost_method: type: string average_cost: type: number format: double total_pnl: type: number format: double growth: type: number format: double total_unrealized_pnl: type: number format: double unrealized_breakdown: $ref: '#/components/schemas/commonPnLBreakdown' total_realized_pnl: type: number format: double realized_breakdown: $ref: '#/components/schemas/commonPnLBreakdown' commonPnLBreakdown: type: object properties: underlying: type: number format: double yield: type: number format: double rewards: type: number format: double commonHyperCoreSpotBalance: type: object properties: coin: type: string token_index: type: integer format: int32 description: |- int32 deliberately: protojson renders int64 as a JSON string, and a token index is a small enum-like value clients compare numerically. amount: type: string hold: type: string value_usd: type: number format: double description: >- value_usd is priced from the token's canonical USDC spot pair. It is 0 when priced is false, which means the price is unknown rather than zero - a token with no resting liquidity has no mid or mark to read. priced: type: boolean description: >- HyperCoreSpotBalance is one HyperCore spot token row, priced from its canonical USDC spot pair where one exists. Tokens without a USDC pair or without liquidity are reported unpriced rather than with an implied price. commonVaultRiskData: type: object properties: pool_rating: type: string pool_rating_color: type: string pool_rating_description: type: string pool_url: type: string pool_design: $ref: '#/components/schemas/VaultRiskDataPoolDesign' chain: $ref: '#/components/schemas/VaultRiskDataRiskCategory' assets: $ref: '#/components/schemas/VaultRiskDataRiskCategory' protocols: $ref: '#/components/schemas/VaultRiskDataRiskCategory' commonVaultMetadata: type: object properties: audits: type: array items: $ref: '#/components/schemas/commonAudit' kyc: type: array items: $ref: '#/components/schemas/VaultMetadataKYC' faq: type: array items: $ref: '#/components/schemas/commonFAQ' other: type: array items: $ref: '#/components/schemas/VaultMetadataOther' commonVaultStatsBasic: type: object properties: apy_snapshot_now: type: number format: double apy_snapshot_day: type: number format: double apy_snapshot_week: type: number format: double apy_snapshot_month: type: number format: double apy_snapshot_year: type: number format: double apy_snapshot_all_time: type: number format: double apy_change_day: type: number format: double apy_change_week: type: number format: double apy_change_month: type: number format: double apy_change_year: type: number format: double apy_change_all_time: type: number format: double tvl_total: type: number format: double tvl_superform: type: number format: double tvl_total_change_day: type: number format: double tvl_total_change_week: type: number format: double tvl_total_change_month: type: number format: double tvl_total_change_year: type: number format: double tvl_total_change_all_time: type: number format: double tvl_superform_change_day: type: number format: double tvl_superform_change_week: type: number format: double tvl_superform_change_month: type: number format: double tvl_superform_change_year: type: number format: double tvl_superform_change_all_time: type: number format: double sharpe_snapshot_day: type: number format: double sharpe_snapshot_week: type: number format: double sharpe_snapshot_month: type: number format: double sharpe_snapshot_year: type: number format: double sharpe_snapshot_all_time: type: number format: double return_day: type: number format: double return_week: type: number format: double return_month: type: number format: double return_year: type: number format: double return_all_time: type: number format: double pps: type: number format: double pps_usd: type: number format: double reward_rate: type: number format: double net_inflow_total_day: type: number format: double description: >- Signed net inflow in USD over the trailing window (positive = inflow, negative = outflow), derived from share-supply deltas. net_inflow_total_week: type: number format: double net_inflow_total_month: type: number format: double net_inflow_total_day_assets: type: number format: double description: >- Same signal denominated in whole units of the vault's underlying asset (e.g. 10.5 = 10.5 USDC for a USDC vault). Signed. net_inflow_total_week_assets: type: number format: double net_inflow_total_month_assets: type: number format: double commonSuperVaultProvider: type: object properties: id: type: string name: type: string logo: type: string type: type: string description: type: string is_hidden: type: boolean commonSuperVaultAsset: type: object properties: id: type: string title: chain_id + "_" + address address: type: string chain_id: type: string format: uint64 decimals: type: integer format: int32 icon: type: string is_btc: type: boolean is_eth: type: boolean is_stable: type: boolean name: type: string price_usd: type: number format: double description: Omitted when no fresh/safe latest price is available. price_usd_24h_change: type: number format: double symbol: type: string commonSuperVaultReward: type: object properties: type: type: string logo: type: string reward_rate: type: number format: double rate_type: type: string address: type: string symbol: type: string reward_multiplier: type: number format: double chain_id: type: string format: uint64 remarks: type: string remarks_url: type: string is_configurable: type: boolean total_supply: type: string format: uint64 reward_source: type: string reward_up_base_rate: type: number format: double commonSuperVaultChain: type: object properties: id: type: string format: uint64 name: type: string icon: type: string currency_symbol: type: string is_l1: type: boolean VaultRiskDataPoolDesign: type: object properties: rating: type: string rating_color: type: string VaultRiskDataRiskCategory: type: object properties: rating: type: string rating_color: type: string underlying: type: array items: $ref: '#/components/schemas/VaultRiskDataUnderlying' commonAudit: type: object properties: date: type: string format: date-time url: type: string auditor: type: string VaultMetadataKYC: type: object properties: issuer: type: string issuer_link: type: string provider: type: string commonFAQ: type: object properties: question: type: string answer: type: string title: '--- metadata types ---' VaultMetadataOther: type: object properties: info: type: string description: type: string VaultRiskDataUnderlying: type: object properties: name: type: string rating: type: string rating_color: type: string url: type: string securitySchemes: SF-API-KEY: type: apiKey description: >- API key required for authentication. Use the value {{v2_api_key}} in Postman. name: SF-API-KEY in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.