> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octav.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual Users Portfolio

> Fetch portfolios for one or more virtual users. Works identically to GET /portfolio but uses virtual user addresses. Requires a Pro subscription.

**Cost:** 1 credit per virtual user address

**Get your API key:** [Dev Portal](https://data.octav.fi)



## OpenAPI

````yaml /openapi.json get /virtual-users/portfolio
openapi: 3.0.0
info:
  title: Octav API
  description: >-
    Comprehensive blockchain data API for portfolio management, transactions,
    and DeFi analytics
  version: 1.0.0
  contact:
    name: Octav Support
    url: https://octav.fi
    email: info@octav.fi
servers:
  - url: https://api.octav.fi/v1
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Portfolio
    description: Portfolio and holdings endpoints
  - name: Virtual Users
    description: Virtual user management and portfolio endpoints (Pro only)
  - name: Nav
    description: Net Asset Value endpoints
  - name: Wallet
    description: Wallet information endpoints
  - name: Transactions
    description: Transaction history endpoints
  - name: Approvals
    description: Token approval endpoints
  - name: Tokens
    description: Token data endpoints
  - name: Airdrops
    description: Airdrop eligibility endpoints
  - name: Sync
    description: Data synchronization endpoints
  - name: Status
    description: Status check endpoints
  - name: Credits
    description: Credit balance endpoints
  - name: Chains
    description: Blockchain network and protocol endpoints
  - name: Contract Protocol
    description: Resolve a contract address to its DeFi protocol
  - name: Beacon Validators
    description: >-
      Ethereum beacon chain validator endpoints — details, rewards, withdrawals,
      and deposits (mainnet only)
paths:
  /virtual-users/portfolio:
    get:
      tags:
        - Virtual Users
      summary: Virtual Users Portfolio
      description: >-
        Fetch portfolios for one or more virtual users. Works identically to GET
        /portfolio but uses virtual user addresses. Requires a Pro subscription.


        **Cost:** 1 credit per virtual user address


        **Get your API key:** [Dev Portal](https://data.octav.fi)
      operationId: getVirtualUsersPortfolio
      parameters:
        - name: addresses
          in: query
          required: true
          description: >-
            Comma-separated virtual user addresses (from the list endpoint).
            Format: virtual:<id>. Max 10.
          schema:
            type: string
          example: virtual:a1b2c3d4-e5f6-7890-abcd-ef1234567890
        - name: aggregated
          in: query
          required: false
          description: Return a single reduced portfolio across all virtual users
          schema:
            type: boolean
            default: false
        - name: waitForSync
          in: query
          required: false
          description: Wait for fresh data if cache is stale
          schema:
            type: boolean
            default: false
        - name: includeImages
          in: query
          required: false
          description: Include image URLs for chains, assets, and protocols
          schema:
            type: boolean
            default: false
        - name: includeExplorerUrls
          in: query
          required: false
          description: Include blockchain explorer URLs for assets and transactions
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response — same schema as GET /portfolio
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    address:
                      type: string
                      description: The virtual user address (virtual:<id>)
                    networth:
                      type: string
                      description: Total portfolio net worth in USD
                    cashBalance:
                      type: string
                      description: Available cash balance
                    dailyIncome:
                      type: string
                      description: Income generated today
                    dailyExpense:
                      type: string
                      description: Expenses incurred today
                    fees:
                      type: string
                      description: Total fees in native asset
                    feesFiat:
                      type: string
                      description: Total fees in USD
                    lastUpdated:
                      type: string
                      description: Last sync timestamp (milliseconds since epoch)
                    assetByProtocols:
                      type: object
                      description: Assets organized by protocol
                    chains:
                      type: object
                      description: Assets organized by blockchain
        '403':
          description: >-
            Forbidden — one or more virtual user addresses do not belong to this
            account
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````