Euler Finance APYs API

openapi: 3.2.0
info:
  title: Euler APYs API
  version: 3.0.0
  description: 'Operations tagged APYs across 2 of this provider''s published API definitions: euler-openapi.json, euler-v3-data-api.json. Each path carries the servers of the definition it was published in.'
servers:
- url: /
  description: Current environment
security: []
tags:
- name: APYs
  description: Base and intrinsic APY surfaces. In v3, APY families are split into dedicated endpoints instead of being embedded inconsistently across larger payloads.
paths:
  /v3/evk/vaults/{chainId}/{address}/apy:
    get:
      tags:
      - APYs
      summary: Vault APY (current + historical)
      description: 'Returns current and historical vault APY. The effective end is `to` or the

        current time. When `from` is omitted, the effective window is 7 days for

        `1h` and 30 days for `1d`. Ranges count both endpoint buckets and support

        at most 744 hourly buckets or 732 daily buckets.


        Needs the `apys` chain capability; a chain without it answers 404

        `CHAIN_CAPABILITY_DISABLED`.'
      x-status: implemented
      x-chain-capability: apys
      x-cache-ttl: 60
      parameters:
      - $ref: '#/components/parameters/ChainIdPath'
      - $ref: '#/components/parameters/AddressPath'
      - $ref: '#/components/parameters/HistoryFromParam'
      - $ref: '#/components/parameters/HistoryToParam'
      - name: resolution
        in: query
        required: false
        schema:
          type: string
          enum:
          - 1h
          - 1d
          default: 1d
        description: Defaults to `1d`. If omitted, uses last 30 days for `1d` and last 7 days for `1h`.
      - $ref: '#/components/parameters/SortParam'
      responses:
        '200':
          description: Vault APY
          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/VaultApy'
                  meta:
                    $ref: '#/components/schemas/VaultApyMeta'
        '400':
          $ref: '#/components/responses/Error400'
        '404':
          $ref: '#/components/responses/Error404ChainCapability'
      operationId: getVaultsByChainIdByAddressApy
    servers:
    - url: /
      description: Current environment
  /v3/apys/intrinsic:
    get:
      tags:
      - APYs
      summary: Intrinsic APYs
      description: Returns one row per chain and asset. The newest provider observation is selected; equal timestamps use provider and uniquifier ascending as deterministic tie-breakers. An asset whose newest non-zero observation is older than 7 days is left out. A provider set up per token (a yield-source entry, or a DefiLlama pool mapping) is served only while the asset has an enabled entry for it, and a DefiLlama pool APY only while the mapping names that pool; other providers, such as Pendle, are not set up per token. Needs the `apys` chain capability. A `chainId` naming a chain without it answers 404 `CHAIN_CAPABILITY_DISABLED`; without `chainId`, served chains without it are left out and listed in `meta.excludedChains`.
      x-status: implemented
      x-chain-capability: apys
      x-cache-ttl: 300
      parameters:
      - $ref: '#/components/parameters/ChainIdParam'
      - name: assets
        in: query
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Intrinsic APYs
          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/IntrinsicApy'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '400':
          $ref: '#/components/responses/Error400'
        '404':
          $ref: '#/components/responses/Error404ChainCapability'
      operationId: getApysIntrinsic
    servers:
    - url: /
      description: Current environment
  /v3/apys/intrinsic/history:
    get:
      tags:
      - APYs
      summary: Intrinsic APY history
      description: Needs the `apys` chain capability; a chain without it answers 404 `CHAIN_CAPABILITY_DISABLED`.
      x-status: implemented
      x-chain-capability: apys
      x-cache-ttl: 300
      parameters:
      - $ref: '#/components/parameters/ChainIdParam'
      - name: asset
        in: query
        required: true
        schema:
          type: string
        description: Asset address to query.
      - name: resolution
        in: query
        required: true
        schema:
          type: string
          enum:
          - 1h
          - 1d
        description: Bucket size for aggregation.
      - $ref: '#/components/parameters/StartTimestampParam'
      - $ref: '#/components/parameters/EndTimestampParam'
      responses:
        '200':
          description: Intrinsic APY 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/IntrinsicApyHistoryPoint'
                  meta:
                    $ref: '#/components/schemas/IntrinsicApyHistoryMeta'
        '404':
          $ref: '#/components/responses/Error404ChainCapability'
      operationId: getApysIntrinsicHistory
    servers:
    - url: /
      description: Current environment
components:
  schemas:
    LabelHoldSummary:
      description: What a draft read shows on a held row.
      type: object
      required:
      - id
      - kind
      - reason
      - since
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
          - quarantine
          - entity-hold
        reason:
          type: string
        since:
          type: string
          format: date-time
    ExcludedChains:
      type: array
      description: 'On a read across chains that names no `chainId`: the served chains it left out because they do not run the capability the operation needs, rather than reading them as empty. Absent when no chain was left out.'
      items:
        type: object
        required:
        - chainId
        - capability
        properties:
          chainId:
            type: integer
          capability:
            type: string
            enum:
            - indexing
            - activity
            - prices
            - historicalPrices
            - assessments
            - labels
            - logos
            - stats
            - risk
            - rewards
            - apys
    IntrinsicApyHistoryPoint:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        apy:
          type: number
          description: Intrinsic APY as a percent number.
        provider:
          type: string
        uniquifier:
          type: string
          description: Provider-specific identity when one provider exposes multiple APY streams.
        apyDuration:
          type: number
          description: Duration in seconds used to compute the APY.
    VaultApyMeta:
      type: object
      properties:
        coverage:
          $ref: '#/components/schemas/HistoryCoverage'
        chainId:
          type: string
        vault:
          type: string
        resolution:
          type: string
          enum:
          - 1h
          - 1d
        startTimestamp:
          type: string
          format: date-time
        endTimestamp:
          type: string
          format: date-time
        timestamp:
          type: string
          format: date-time
    HistoryInterval:
      type: object
      required:
      - from
      - to
      description: Inclusive UTC bucket-start bounds. A single absent bucket has equal from/to values.
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
    HistoryCoverage:
      type: object
      required:
      - scope
      - status
      - requestedBuckets
      - evaluatedBuckets
      - returnedBuckets
      - futureBuckets
      - firstAvailable
      - lastAvailable
      - provisionalBucket
      - missingIntervals
      - metrics
      description: Availability within the requested range, not proof of historical membership, vault inception, source retention, recoverability, or price accuracy. Leading and trailing absent buckets are included. Future buckets are excluded from evaluation; the current bucket is provisional. Missing fields and read failures remain unavailable without asserting their root cause.
      properties:
        scope:
          type: string
          enum:
          - requested-range
        status:
          type: string
          enum:
          - complete
          - partial
          - missing
          - not_applicable
          description: Complete requires all evaluated buckets and all reported metrics. Missing means no returned buckets. Not applicable means the range is entirely in the future.
        requestedBuckets:
          type: integer
          minimum: 1
        evaluatedBuckets:
          type: integer
          minimum: 0
        returnedBuckets:
          type: integer
          minimum: 0
        futureBuckets:
          type: integer
          minimum: 0
        firstAvailable:
          type: string
          format: date-time
          nullable: true
          description: First returned bucket within the evaluated range, not the earliest retained source date.
        lastAvailable:
          type: string
          format: date-time
          nullable: true
        provisionalBucket:
          type: string
          format: date-time
          nullable: true
        missingIntervals:
          type: array
          description: Buckets absent from the response regardless of metric coverage.
          items:
            $ref: '#/components/schemas/HistoryInterval'
        metrics:
          type: object
          description: Coverage keyed by public metric name. Available and missing bucket counts sum to evaluatedBuckets; partialBuckets is a subset of availableBuckets.
          additionalProperties:
            $ref: '#/components/schemas/HistoryMetricCoverage'
    ResolvedProductLabels:
      type: object
      readOnly: true
      description: Read-time entity fallbacks for display. Derived, never stored.
      required:
      - entityName
      - url
      - logo
      properties:
        entityName:
          type: string
          nullable: true
        url:
          type: string
          nullable: true
          description: Product url, falling back to the owning entity url.
        logo:
          type: string
          nullable: true
          description: Product logo, falling back to the owning entity logo.
    VaultApyPoint:
      type: object
      properties:
        supplyApy:
          type: number
          nullable: true
          description: Percent number with 6 decimal places.
        borrowApy:
          type: number
          nullable: true
          description: Percent number with 6 decimal places.
        timestamp:
          type: string
          format: date-time
    IntrinsicApyHistoryMeta:
      type: object
      properties:
        chainId:
          type: string
        asset:
          type: string
        symbol:
          type: string
        resolution:
          type: string
          enum:
          - 1h
          - 1d
        startTimestamp:
          type: string
          format: date-time
        endTimestamp:
          type: string
          format: date-time
        timestamp:
          type: string
          format: date-time
    ProductPlatformListing:
      description: The platform-owned discovery decision on a product, as a product row shows it.
      type: object
      required:
      - notExplorableLend
      - notExplorableBorrow
      - reason
      properties:
        notExplorableLend:
          type: boolean
        notExplorableBorrow:
          type: boolean
        reason:
          type: string
          nullable: true
    VaultApy:
      type: object
      properties:
        coverage:
          $ref: '#/components/schemas/HistoryCoverage'
        current:
          $ref: '#/components/schemas/VaultApyPoint'
        history:
          type: array
          items:
            $ref: '#/components/schemas/VaultApyPoint'
    IntrinsicApy:
      type: object
      properties:
        chainId:
          type: integer
        address:
          type: string
        symbol:
          type: string
        apy:
          type: number
          description: Percent number with 6 decimal places.
        provider:
          type: string
        source:
          type: string
        claimUrl:
          type: string
          format: uri
          description: Where the yield is claimed. Always an https URL; absent when the source gave none or a URL that is not https.
        timestamp:
          type: string
          format: date-time
    PaginationMeta:
      type: object
      required:
      - timestamp
      properties:
        total:
          type: integer
          description: Exact total count when the endpoint provides one.
        hasMore:
          type: boolean
          description: Indicates whether another page exists beyond the current page.
        offset:
          type: integer
        limit:
          type: integer
          description: Echoed page size after endpoint-side clamping.
        outcome:
          type: string
          enum:
          - disabled
          - removed
          description: On a toolbox config DELETE, what happened to the row.
        products:
          type: array
          description: 'On a curation vault `POST`, `PUT`, or `PATCH`: the products the write touched (the one the vault left and the one it joined) as they are after the write, `governanceMode` included, so the caller applies them instead of re-reading.'
          items:
            $ref: '#/components/schemas/ProductLabels'
        timestamp:
          type: string
          format: date-time
        chainId:
          type: string
          description: Comma-separated chain IDs for multi-chain responses.
        degradedProviders:
          type: array
          items:
            type: string
          description: Live providers whose data is incomplete in this response.
        excludedChains:
          $ref: '#/components/schemas/ExcludedChains'
    ListingFlag:
      type: boolean
      nullable: true
      description: Curator listing flag. `null` leaves the decision to platform overrides and deprecation, `true` hides the vault(s) from discovery, `false` keeps a deprecated vault listed.
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - requestId
          properties:
            code:
              type: string
              description: 'Domain error code. Examples:

                - BAD_REQUEST

                - INVALID_ADDRESS

                - INVALID_CHAIN_ID

                - CHAIN_NOT_SUPPORTED

                - CHAIN_CAPABILITY_DISABLED

                - NOT_FOUND

                - VAULT_NOT_FOUND

                - TOKEN_NOT_FOUND

                - ACCOUNT_NOT_FOUND

                - VALIDATION_ERROR

                - CONFLICT

                - PRECONDITION_FAILED

                - PAYLOAD_TOO_LARGE

                - RATE_LIMIT_EXCEEDED

                - UNSUPPORTED_MEDIA_TYPE

                - UPSTREAM_TIMEOUT

                - UNAUTHORIZED

                - FORBIDDEN

                - SERVICE_UNAVAILABLE

                - SERVICE_DISABLED

                - INTERNAL_ERROR

                '
            message:
              type: string
            requestId:
              type: string
            details:
              type: object
              additionalProperties: true
              description: Context of the error. Where present, `details.reason` is a stable kebab-case value to key on, and `details.cause` narrows a reason that has several causes. The labels routes list theirs in the Labels tag.
    HistoryMetricCoverage:
      type: object
      required:
      - status
      - availableBuckets
      - partialBuckets
      - missingBuckets
      - missingIntervals
      - partialIntervals
      properties:
        status:
          type: string
          enum:
          - complete
          - partial
          - missing
          - not_applicable
        availableBuckets:
          type: integer
          minimum: 0
          description: Distinct elapsed requested buckets with a finite value, including partial aggregate values and observed zero.
        partialBuckets:
          type: integer
          minimum: 0
          description: Available buckets whose aggregate covers only part of the requested chain scope.
        missingBuckets:
          type: integer
          minimum: 0
        missingIntervals:
          type: array
          items:
            $ref: '#/components/schemas/HistoryInterval'
        partialIntervals:
          type: array
          items:
            $ref: '#/components/schemas/HistoryInterval'
    ProductLabels:
      type: object
      required:
      - id
      - chainId
      - entityId
      - coBrandEntityIds
      - name
      - isDeprecated
      - notExplorable
      - governanceMode
      - resolved
      - anyExplorableLend
      - anyExplorableBorrow
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
        chainId:
          type: integer
          minimum: 1
        entityId:
          type: string
        coBrandEntityIds:
          type: array
          description: Additional entities whose logos should be displayed. Product management remains exclusively with entityId.
          items:
            type: string
        name:
          type: string
        logo:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        url:
          type: string
          nullable: true
          maxLength: 2048
          pattern: ^[Hh][Tt][Tt][Pp][Ss]://
          description: Absolute https URL.
        portfolioNotice:
          type: string
          nullable: true
        isDeprecated:
          type: boolean
        deprecationReason:
          type: string
          nullable: true
        notExplorable:
          allOf:
          - $ref: '#/components/schemas/ListingFlag'
          description: Product-wide curator listing flag applied to both sides of every member vault unless a vault-level flag overrides it.
        governanceMode:
          type: string
          enum:
          - governed
          - ungoverned
          - unknown
          readOnly: true
          description: Derived by the server from the on-chain governor of member vaults; clients cannot set it. Products are created as `unknown`. Every vault assignment recomputes the mode over the resulting member set and rejects sets that mix governed and ungoverned vaults. Layer 2 adopts `governed` or `ungoverned` for an `unknown` product once its membership verifies against chain state. Entity members cannot update or delete an `ungoverned` product or its vaults after the initial assignment.
        resolved:
          $ref: '#/components/schemas/ResolvedProductLabels'
        anyExplorableLend:
          type: boolean
          readOnly: true
          description: True when at least one member vault is lend-discoverable per the materialized visibility verdicts. Live chain state (e.g. borrowability) is deliberately excluded.
        anyExplorableBorrow:
          type: boolean
          readOnly: true
          description: True when at least one member vault is borrow-discoverable per the materialized visibility verdicts. Live chain state (e.g. borrowability) is deliberately excluded.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        hold:
          type: object
          nullable: true
          description: The hold covering this row on a draft read; absent on published reads.
          allOf:
          - $ref: '#/components/schemas/LabelHoldSummary'
        platformListing:
          type: object
          nullable: true
          description: Euler's listing override on this product, shown to platform sessions on draft reads (null when there is none); absent on published reads and to curators.
          allOf:
          - $ref: '#/components/schemas/ProductPlatformListing'
    IntrinsicApyHistoryPoint_2:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        apy:
          type: number
          description: Intrinsic APY as a percent number.
        provider:
          type: string
        apyDuration:
          type: number
          description: Duration in seconds used to compute the APY.
    VaultApyMeta_2:
      type: object
      properties:
        chainId:
          type: string
        vault:
          type: string
        resolution:
          type: string
          enum:
          - 1h
          - 1d
        startTimestamp:
          type: string
          format: date-time
        endTimestamp:
          type: string
          format: date-time
        timestamp:
          type: string
          format: date-time
    VaultApyPoint_2:
      type: object
      properties:
        supplyApy:
          type: number
          nullable: true
          description: Percent number with 6 decimal places.
        borrowApy:
          type: number
          description: Percent number with 6 decimal places.
        timestamp:
          type: string
          format: date-time
    VaultApy_2:
      type: object
      properties:
        current:
          $ref: '#/components/schemas/VaultApyPoint_2'
        history:
          type: array
          items:
            $ref: '#/components/schemas/VaultApyPoint_2'
    PaginationMeta_2:
      type: object
      required:
      - timestamp
      properties:
        total:
          type: integer
          description: Exact total count when the endpoint provides one.
        hasMore:
          type: boolean
          description: Indicates whether another page exists beyond the current page.
        offset:
          type: integer
        limit:
          type: integer
          description: Echoed page size after endpoint-side clamping.
        timestamp:
          type: string
          format: date-time
        chainId:
          type: string
          description: Comma-separated chain IDs for multi-chain responses.
    IntrinsicApy_2:
      type: object
      properties:
        chainId:
          type: integer
        address:
          type: string
        symbol:
          type: string
        apy:
          type: number
          description: Percent number with 6 decimal places.
        provider:
          type: string
        source:
          type: string
        timestamp:
          type: string
          format: date-time
  parameters:
    OffsetParam:
      name: offset
      in: query
      required: false
      description: Page offset, capped at 10000 to bound query cost.
      schema:
        type: integer
        minimum: 0
        maximum: 10000
        default: 0
    EndTimestampParam:
      name: endTimestamp
      in: query
      required: false
      schema:
        type: integer
      description: End of time range (unix seconds).
    StartTimestampParam:
      name: startTimestamp
      in: query
      required: false
      schema:
        type: integer
      description: Start of time range (unix seconds).
    ChainIdParam:
      name: chainId
      in: query
      required: false
      schema:
        type: string
      description: Comma-separated list of positive chain IDs (single value allowed). Duplicate IDs are removed in first-occurrence order; at most 20 distinct IDs and 512 input characters are accepted.
      example: 1,10,8453
    LimitParam:
      name: limit
      in: query
      required: false
      description: Requested page size. Values above the endpoint cap are clamped; the default shared cap is 100.
      schema:
        type: integer
        minimum: 1
        default: 20
        maximum: 100
    ChainIdPath:
      name: chainId
      in: path
      required: true
      schema:
        type: integer
    HistoryFromParam:
      name: from
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 2147483647
      description: Unix timestamp in seconds, no later than 2038-01-19T03:14:07Z.
    AddressPath:
      name: address
      in: path
      required: true
      schema:
        type: string
    SortParam:
      name: sort
      in: query
      required: false
      schema:
        type: string
      description: Sort field, prefix with '-' for descending.
    HistoryToParam:
      name: to
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 2147483647
      description: Unix timestamp in seconds, no later than 2038-01-19T03:14:07Z.
    ChainIdParam_2:
      name: chainId
      in: query
      required: false
      schema:
        type: string
      description: Comma-separated list of chain IDs (single value allowed).
      example: 1,10,8453
    LimitParam_2:
      name: limit
      in: query
      required: false
      description: Requested page size. Values above the endpoint cap are clamped; the default shared cap is 100.
      schema:
        type: integer
        default: 20
        maximum: 100
    FieldsParam:
      name: fields
      in: query
      required: false
      schema:
        type: string
      description: Comma-separated list of fields to include.
    OffsetParam_2:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        default: 0
  headers:
    X-Request-Id:
      description: Request identifier for tracing.
      schema:
        type: string
    Cache-Control:
      description: Cache policy for this response.
      schema:
        type: string
  responses:
    Error404ChainCapability:
      description: 'Not found, or `CHAIN_CAPABILITY_DISABLED`: a requested chain does not run the capability the operation needs (see `capabilities` on `/v3/chains`), named in `x-chain-capability` or, where it depends on the request, in the parameter. `details.chainIds` lists those chains and `details.capability` names the capability.'
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: CHAIN_CAPABILITY_DISABLED
              message: Chain(s) 137 do not run prices
              requestId: req_example
              details:
                chainIds:
                - 137
                capability: prices
    Error400:
      description: Bad request
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication (optional; higher rate limits).
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Alternative to X-API-Key using Authorization: Bearer <key>'
    AdminSecret:
      type: apiKey
      in: header
      name: X-Admin-Secret
      description: Admin secret (server-to-server) for API key management.
    PlatformSession:
      type: apiKey
      in: cookie
      name: euler_platform_session
      description: Signed, httpOnly platform-operator browser session cookie.
    PlatformCsrf:
      type: apiKey
      in: header
      name: X-CSRF-Token
      description: Double-submit CSRF token required for unsafe cookie-authenticated methods.
x-refined-from:
- euler-openapi.json
- euler-v3-data-api.json