Euler Finance Vaults API

openapi: 3.1.0
info:
  title: Euler Data API (V3) Accounts Vaults API
  version: 3.0.0
  description: "API specification for Euler Data v3. This spec defines the current\nresource-oriented contract for the platform, with emphasis on consistent\nschemas, predictable REST semantics, caching, observability, and a uniform\ndeveloper experience.\n\nMigration notes\n- Euler Data v3 is not a path-for-path clone of v1/v2. Some endpoints map\n  directly, some require multiple v3 calls, and some legacy aggregates were\n  intentionally removed.\n- The live [migration guide](/v3/docs/migration) explains how legacy v1/v2\n  endpoints and payloads map into the v3 resource model.\n- Important semantic changes:\n  - Vault base APY and rewards APY are exposed separately in v3.\n  - Account positions are flattened into account-vault rows instead of the\n    legacy nested sub-account shape.\n  - All supported API paths live under `/v3`; legacy paths return `410`.\n  - Summary endpoints prefer smaller, focused resources over large\n    BFF-style payloads.\n\nBase path: /v3\n\nConventions\n- JSON field naming: camelCase\n- Addresses: accept lowercase or checksum; responses are EIP-55 checksummed\n- Public APY values (`*Apy`, `apy*`): percent numbers with 6 decimal places (e.g., 5.123456 = 5.123456%)\n- Contract interest-rate fields (`borrowAPY`, `supplyAPY` in `interestRates`): decimal strings in contract fraction units\n- Ratios (utilization, LTV, etc.): numbers with 6 decimal places\n- Response timestamps: ISO-8601 strings (UTC). Some legacy fields still expose unix\n  seconds for compatibility and include `*Iso` companions.\n- Query time ranges: unix seconds (from/to)\n\nUnit policy\n- v3 separates market metadata from contract verdicts by both name and type.\n- Market-normalized USD prices and USD values are JSON numbers. These are values\n  derived from off-chain pricing, cached price snapshots, or API-level market math.\n  This includes `/v3/prices`, token price routes, vault/earn/protocol USD totals,\n  portfolio market values, portfolio USD liquidation/risk fields such as\n  `liabilityValueUsd`, `totalCollateralValueUsd`, `borrowLiquidationPriceUsd`,\n  and `collateralLiquidationPricesUsd`, and vault holder `assetsUsd`.\n- Contract-derived oracle and raw account-liquidity verdict values are exact strings.\n  These preserve the integer value used by contracts, normalized to 18 decimals\n  for API exposure. Oracle prices are quoted in the vault unit of account, which\n  can be USD, ETH, or another asset. This includes `/v3/oracles/prices`, raw\n  account-liquidity `liabilityValue` and `totalCollateralValue` objects,\n  `liabilityValueBorrowing`, `liabilityValueLiquidation`, and collateral verdict\n  values.\n- On-chain token quantities are bigint strings in their native unit scale. This\n  includes amounts, balances, shares, assets, borrows, reward amounts, liquidation\n  repay/yield amounts, and block numbers.\n- Caps are also bigint strings, but EVK caps are exposed as resolved underlying\n  asset-unit amounts rather than packed contract config words.\n- LTV config values use canonical basis-point strings. Legacy decimal aliases\n  may remain on config-history payloads for compatibility when explicitly named.\n\nRate limiting\n- Optional API keys for higher limits\n- Default limits are configurable; current defaults: free tier 100 req/min (IP-based)\n  and authenticated 1000 req/min (per API key), 60s window.\n- By default, proxy headers are not trusted for IP identity unless explicitly enabled.\n- Redis failures default to fail-closed (503) for strict enforcement; fail-open is opt-in.\n- RateLimit-* (IETF draft-6) and legacy X-RateLimit-* headers are returned.\n\nCORS\n- Public API responses use wildcard CORS, including preflight responses for unsafe methods.\n- Unsafe methods with request bodies must use a JSON media type.\n\nCaching\n- Cache-Control headers are returned for cacheable endpoints.\n- Defaults (may be adjusted in config):\n  - Prices: 300s\n  - APYs: 600s\n  - Rewards: 900s\n  - General responses: 60s (short 30s, long 300s)\n\nErrors\n- All errors use a standard envelope: { error: { code, message, requestId, details? } }\n- Domain error codes are documented in this spec.\n- JSON request bodies must use `Content-Type: application/json` or another `application/*+json` media type.\n- Request bodies larger than 1 MiB are rejected before route parsing with `413 PAYLOAD_TOO_LARGE`.\n"
servers:
- url: /
  description: Current environment
security: []
tags:
- name: Vaults
  description: Canonical vault resources, vault history, holders, borrowers, and open-interest views. In v3, vault detail is decomposed into focused endpoints instead of one large legacy response.
paths:
  /v3/evk/vaults:
    get:
      tags:
      - Vaults
      summary: List vaults
      description: "Returns a list of vaults.\nNotes:\n  - `fields` and `sort` are accepted but currently ignored.\n  - `minTvl`/`maxTvl` apply to `totalSupplyUsd` where `totalSupplyUsd = (cash + totalBorrows) * price`.\n"
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - $ref: '#/components/parameters/ChainIdParam'
      - $ref: '#/components/parameters/FieldsParam'
      - $ref: '#/components/parameters/SortParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      - name: asset
        in: query
        required: false
        schema:
          type: string
      - name: minTvl
        in: query
        required: false
        schema:
          type: number
      - name: maxTvl
        in: query
        required: false
        schema:
          type: number
      - name: visibility
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated visibility filter (`visible,warning,hidden,pending_review`).
      responses:
        '200':
          description: Vault list
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vault'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
      operationId: getVaults
  /v3/evk/vaults/batch:
    post:
      tags:
      - Vaults
      summary: Batch vault details
      description: "Returns canonical EVK vault detail entities for an explicit address set.\nUse this to avoid high client-side fanout when you already know the vault\naddresses you want to render.\n\nNotes:\n  - Request order is preserved for found vaults.\n  - `meta.notFound` returns requested addresses that were not resolved.\n  - `include=[\"collaterals\"]` expands collateral detail for every returned vault.\n  - The request cap is 1000 vault addresses and 256 KiB of JSON body.\n"
      x-status: implemented
      x-cache-ttl: 60
      operationId: postEvkVaultBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvkVaultBatchRequest'
      responses:
        '200':
          description: Batched EVK vault details
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvkVaultBatchResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '404':
          $ref: '#/components/responses/Error404'
        '413':
          $ref: '#/components/responses/Error413'
        '415':
          $ref: '#/components/responses/Error415'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
  /v3/resolve/vaults:
    get:
      tags:
      - Vaults
      summary: Resolve a vault address to its family
      description: Resolve a single `(chainId, address)` pair to `vaultType`, `factory`, and the canonical resource path when one exists.
      x-status: implemented
      x-cache-ttl: 60
      operationId: getVaultResolve
      parameters:
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
      - name: address
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Resolved vault family
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/VaultResolveEntry'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '404':
          description: Vault not found
    post:
      tags:
      - Vaults
      summary: Resolve multiple vault addresses to their families
      description: Bulk resolver for SDK/meta-routing use cases. Supports up to 500 addresses per request.
      x-status: implemented
      x-cache-ttl: 60
      operationId: postVaultResolve
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chainId
              - addresses
              properties:
                chainId:
                  type: integer
                addresses:
                  type: array
                  minItems: 1
                  maxItems: 500
                  items:
                    type: string
      responses:
        '200':
          description: Resolved vault families
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/VaultResolveEntry'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '413':
          $ref: '#/components/responses/Error413'
        '415':
          $ref: '#/components/responses/Error415'
  /v3/evk/vaults/health/utilization:
    get:
      tags:
      - Vaults
      summary: Vault utilization health
      description: 'Lists vaults ordered by utilization severity (descending).

        - `chainId` is required.

        - If `threshold` is omitted, returns all vaults.

        - Threshold filter is inclusive (`utilization >= threshold`).

        - `onlyOverThreshold` is accepted for compatibility and currently does not alter filtering.

        '
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
      - name: threshold
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
      - name: onlyOverThreshold
        in: query
        required: false
        schema:
          type: boolean
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Vault utilization health list
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubAccount'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '400':
          $ref: '#/components/responses/Error400'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
      operationId: getVaultsHealthUtilization
  /v3/evk/vaults/health/caps:
    get:
      tags:
      - Vaults
      summary: Vault cap usage health
      description: 'Lists vaults ordered by cap-usage severity (descending).

        Cap usage is computed as `max(supplyCapUsage, borrowCapUsage)`, and the

        response includes both supply-cap and borrow-cap fields.

        - `chainId` is required.

        - If `threshold` is omitted, returns all vaults.

        - Threshold filter is inclusive (`capUsage >= threshold`).

        - `onlyOverThreshold` is accepted for compatibility and currently does not alter filtering.

        '
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
      - name: threshold
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 1
      - name: onlyOverThreshold
        in: query
        required: false
        schema:
          type: boolean
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Vault cap health list
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/VaultCapHealthItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '400':
          $ref: '#/components/responses/Error400'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
      operationId: getVaultsHealthCaps
  /v3/evk/vaults/{chainId}/{address}:
    get:
      tags:
      - Vaults
      summary: Vault details
      description: 'Returns vault detail. Optional `include` expands related resources in a single response.

        Supported values: `collaterals`, `apy`, `totals`, `prices`.

        The single-vault detail response uses `totalBorrowed` as the canonical borrow-total field.

        '
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      - $ref: '#/components/parameters/IncludeParam'
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          description: Vault details
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/VaultDetailResponseWithIncludes'
      operationId: getVaultsByChainIdByAddress
  /v3/evk/vaults/{chainId}/{address}/labels:
    get:
      tags:
      - Vaults
      summary: Public curator labels for a vault
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      responses:
        '200':
          description: Curator-submitted labels for this vault
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PublicVaultLabel'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '400':
          $ref: '#/components/responses/Error400'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
      operationId: getVaultsByChainIdByAddressLabels
  /v3/evk/vaults/{chainId}/{address}/visibility:
    get:
      tags:
      - Vaults
      summary: Deterministic visibility status for a vault
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      responses:
        '200':
          description: Current visibility status and check results
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/VaultVisibility'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '400':
          $ref: '#/components/responses/Error400'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
      operationId: getVaultsByChainIdByAddressVisibility
  /v3/evk/vaults/{chainId}/{address}/positions:
    get:
      tags:
      - Vaults
      summary: Positions in a vault
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      - name: addressPrefix
        in: query
        required: false
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{8}$
        description: Optional 4-byte account prefix filter (`0x` + 8 hex chars).
      - name: blockNumber
        in: query
        required: false
        schema:
          type: string
        description: Not supported for this endpoint. If provided, returns 400.
      responses:
        '200':
          description: Vault positions
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/VaultPosition'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
      operationId: getVaultsByChainIdByAddressPositions
  /v3/evk/vaults/{chainId}/{address}/config-history:
    get:
      tags:
      - Vaults
      summary: Vault configuration history
      description: 'Returns a unified timeline of all configuration changes for this vault,

        including caps, LTV, IRM, governor, fee receiver, hook config, and other settings.

        For specific config types, use the dedicated endpoints (cap-history, ltv-history, irm-history).

        '
      x-status: implemented
      x-cache-ttl: 300
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      - name: from
        in: query
        required: true
        schema:
          type: integer
      - name: to
        in: query
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      - name: type
        in: query
        required: false
        schema:
          type: string
          enum:
          - caps
          - ltv
          - irm
          - governor
          - feeReceiver
          - hookConfig
          - interestFee
          - configFlags
        description: Filter by configuration change type
      responses:
        '200':
          description: Vault config history
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConfigHistoryItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
      operationId: getVaultsByChainIdByAddressConfigHistory
  /v3/evk/vaults/{chainId}/{address}/collaterals:
    get:
      tags:
      - Vaults
      summary: Current accepted collaterals with LTV configurations
      description: 'Returns the list of vaults accepted as collateral for this vault,

        along with their current LTV configurations. Use this to understand

        what assets can be used as collateral when borrowing from this vault.

        '
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      responses:
        '200':
          description: Accepted collaterals with LTV configs
          headers:
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollateralConfig'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '404':
          $ref: '#/components/responses/Error404'
      operationId: getVaultsByChainIdByAddressCollaterals
  /v3/evk/vaults/{chainId}/{address}/ltv-history:
    get:
      tags:
      - Vaults
      summary: Vault LTV history
      x-status: implemented
      x-cache-ttl: 300
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      - name: collateral
        in: query
        required: false
        schema:
          type: string
        description: Filter by collateral vault address
      - $ref: '#/components/parameters/FromParam'
      - $ref: '#/components/parameters/ToParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Vault LTV history
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LtvHistoryItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
      operationId: getVaultsByChainIdByAddressLtvHistory
  /v3/evk/vaults/{chainId}/{address}/cap-history:
    get:
      tags:
      - Vaults
      summary: Vault cap history (supply/borrow)
      description: Returns historical changes to supply and borrow caps for this vault.
      x-status: implemented
      x-cache-ttl: 300
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      - name: from
        in: query
        required: true
        schema:
          type: integer
      - name: to
        in: query
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Vault cap history
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CapHistoryItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
      operationId: getVaultsByChainIdByAddressCapHistory
  /v3/evk/vaults/{chainId}/{address}/irm-history:
    get:
      tags:
      - Vaults
      summary: Vault interest rate model history
      description: Returns historical changes to the interest rate model for this vault.
      x-status: implemented
      x-cache-ttl: 300
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      - $ref: '#/components/parameters/FromParam'
      - $ref: '#/components/parameters/ToParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Vault IRM history
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IrmHistoryItem'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
      operationId: getVaultsByChainIdByAddressIrmHistory
  /v3/evk/vaults/{chainId}/{address}/events:
    get:
      tags:
      - Vaults
      summary: Unified core vault event timeline
      description: 'Unified stream of deposit, withdraw, borrow, repay, and transfer events for one vault.

        Requires a bounded time window (`from` + `to`), max 30 days.

        '
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      - $ref: '#/components/parameters/FromParam'
      - $ref: '#/components/parameters/ToParam'
      - name: type
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated event type filter. Unknown values return 400.
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Vault events
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        chainId:
                          type: integer
                        type:
                          type: string
                        timestamp:
                          type: string
                          format: date-time
                        blockNumber:
                          type: string
                        txHash:
                          type: string
                        payload:
                          type: object
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '400':
          $ref: '#/components/responses/Error400'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
      operationId: getVaultsByChainIdByAddressEvents
  /v3/evk/vaults/{chainId}/{address}/totals:
    get:
      tags:
      - Vaults
      summary: Vault totals with historical series
      description: Returns totalAssets, totalBorrows, utilization, APY from dynamic snapshots. Historical values are raw amounts - compose with /v3/prices for USD conversion.
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      - name: resolution
        in: query
        required: false
        schema:
          type: string
          enum:
          - 1h
          - 1d
          default: 1d
      - $ref: '#/components/parameters/FromParam'
      - $ref: '#/components/parameters/ToParam'
      - name: forceFresh
        in: query
        required: false
        schema:
          type: boolean
        description: 'When true, trigger bounded synchronous vault dynamic refresh before reading totals.

          On timeout/failure, response safely falls back to stored snapshots and indicates cached mode in freshness metadata.

          '
      responses:
        '200':
          description: Vault totals with current + historical data
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/VaultTotals'
                  meta:
                    $ref: '#/components/schemas/VaultTotalsMeta'
                  freshness:
                    $ref: '#/components/schemas/VaultTotalsFreshness'
      operationId: getVaultsByChainIdByAddressTotals
  /v3/evk/vaults/{chainId}/{address}/holders:
    get:
      tags:
      - Vaults
      summary: Vault share holders
      description: Returns all holders with non-zero share balances via transfer aggregation (raw holder set). This endpoint does not unwrap Euler Earn depositors and therefore aligns with legacy behavior when `resolveEulerEarn=false`. Supports 4-byte `addressPrefix` filter for wallet-scoped scans. Balance values are integer strings in raw mode; when resolve flags are enabled, balances may be proportional decimal strings.
      x-status: implemented
      x-cache-ttl: 60
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      - name: addressPrefix
        in: query
        required: false
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{8}$
        description: Optional 4-byte account prefix filter (`0x` + 8 hex chars).
      - name: resolveEulerEarn
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: When true, expands Euler Earn vault-holder addresses into underlying depositors (v1 parity mode).
      - name: resolveSubAccounts
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: When true, aggregates sub-account holders into their owner addresses.
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Vault share holders
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        holder:
                          type: string
                        balance:
                          type: string
                          description: Numeric string; in

# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/euler/refs/heads/main/openapi/euler-vaults-api-openapi.yml