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

# Get reward earnings

> Get a wallet's base-token earnings in one yield, grouped into UTC day, week or month buckets.

Each bucket holds the earnings for that period only, not a running total, so add the buckets up for a cumulative figure. Choose the window with `period` (`1d`, `7d`, `30d`, `90d`, `1y`, `all`; default `30d`) or with `from` and `to` (ISO 8601). Each of `from` and `to` is optional on its own, and either one overrides `period`. `from` is floored to UTC midnight, so a `from` with a time component includes that whole UTC day. `to` defaults to now, is extended to the end of its UTC day, and is then clamped to the last aggregated hour. A `to` without `from` starts at the wallet's first earnings bucket. `interval` sets the bucket size: `day` (default), `week` or `month`. `period=all`, or a `to` without `from`, defaults `interval` to `week`. A range of more than 366 buckets returns `400`.

Earnings are aggregated hourly, so the newest bucket ends at the last aggregated hour. They are recorded only for wallets that have already used Yield.xyz on that network, from that point on, and earlier earnings are not backfilled. A yield without reward support returns `404`. To read earnings for one of your allocator vaults, pass its `feeConfigurationId`; an id that is not one of your project's fee configurations returns `400`.

For preset windows (the last 24 hours, 7, 30 and 365 days from UTC midnight, and all time), use the [reward earnings summary](/api-reference/YieldsController_getYieldRewardsSummary). For the yield's rate over time rather than a wallet's earnings, use [reward rate history](/api-reference/YieldsController_getYieldRewardRateHistory).


## OpenAPI

````yaml openapi.json GET /v1/yields/{yieldId}/rewards
openapi: 3.0.0
info:
  title: 'Yield API: Earn'
  description: API Documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api.yield.xyz
    description: Production
security: []
tags:
  - name: Discovery
    description: >-
      Browse and discover yield opportunities, networks, and providers, plus
      yield-level risk, reward rate, and TVL data
  - name: Portfolio
    description: User-specific balances and KYC status
  - name: Actions
    description: Generate transactions to enter, exit, and manage yields
externalDocs:
  description: For more information
  url: https://docs.yield.xyz
paths:
  /v1/yields/{yieldId}/rewards:
    get:
      tags:
        - Portfolio
      summary: Get bucketed reward earnings
      description: >-
        Returns non-cumulative base-token earnings for a wallet, grouped into
        UTC day, week, or month buckets. period uses the same windows as
        reward-rate and TVL history. from or to overrides period. from is
        floored to the UTC day. A to without from starts at the first earnings
        bucket and defaults interval to week. to defaults to now, moves to the
        end of that UTC day, and is clamped to the last aggregated hour.
      operationId: YieldsController_getYieldRewardEarnings_v1
      parameters:
        - name: yieldId
          required: true
          in: path
          description: The unique identifier of the yield
          schema:
            type: string
            example: ethereum-usdc-morpho-vault
        - name: address
          required: true
          in: query
          description: Wallet address to fetch earnings for
          schema:
            type: string
            example: '0x742d35cc6634c0532925a3b844bc454e4438f44e'
        - name: feeConfigurationId
          required: false
          in: query
          description: >-
            Fee configuration ID used to resolve the partner allocator vault. An
            id that is not one of the project fee configurations is rejected.
          schema:
            example: 66f299cd-aaaa-bbbb-cccc-d1f26e3a02db
            type: string
        - name: from
          required: false
          in: query
          description: >-
            Start of the time range (ISO 8601). Overrides period. Floored to the
            UTC day.
          schema:
            type: string
            example: '2026-10-07T00:00:00.000Z'
        - name: to
          required: false
          in: query
          description: >-
            End of the time range (ISO 8601). Overrides period. Defaults to now,
            then the end of that UTC day, clamped to the last aggregated hour.
            When to is set without from, the range starts at the first earnings
            bucket.
          schema:
            type: string
            example: '2026-10-14T10:45:00.000Z'
        - name: period
          required: false
          in: query
          description: >-
            Predefined time window. Ignored when from or to is provided.
            Default: 30d. period=all defaults interval to week.
          schema:
            enum:
              - 1d
              - 7d
              - 30d
              - 90d
              - 1y
              - all
            type: string
        - name: interval
          required: false
          in: query
          description: >-
            Bucket size (day, week, or month). Default: day. period=all and a to
            without from default to week when omitted.
          schema:
            enum:
              - day
              - week
              - month
            type: string
      responses:
        '200':
          description: Bucketed non-cumulative earnings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YieldRewardsResponseDto'
        '400':
          description: >-
            Invalid address, fee configuration, or date range, or more than 366
            buckets
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid API key
                  error:
                    type: string
                    example: Unauthorized
                  statusCode:
                    type: number
                    example: 401
        '404':
          description: Yield not found, or rewards are not supported for this yield
        '429':
          description: Rate limit exceeded
          headers:
            x-ratelimit-limit:
              description: Request limit per window
              schema:
                type: string
            x-ratelimit-remaining:
              description: Remaining requests (will be 0)
              schema:
                type: string
            x-ratelimit-reset:
              description: Unix timestamp when window resets
              schema:
                type: string
            retry-after:
              description: Seconds to wait before retrying
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Rate limit exceeded
                  error:
                    type: string
                    example: Too Many Requests
                  statusCode:
                    type: number
                    example: 429
                  retryAfter:
                    type: number
                    example: 30
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal server error
                  error:
                    type: string
                    example: Internal Server Error
                  statusCode:
                    type: number
                    example: 500
      security:
        - ApiKey: []
components:
  schemas:
    YieldRewardsResponseDto:
      type: object
      properties:
        yieldId:
          type: string
          example: ethereum-usdc-morpho-vault
        address:
          type: string
          example: '0x742d35cc6634c0532925a3b844bc454e4438f44e'
        token:
          $ref: '#/components/schemas/YieldRewardTokenDto'
        interval:
          type: string
          enum:
            - day
            - week
            - month
          example: day
        from:
          type: string
          example: '2026-10-07T00:00:00.000Z'
        to:
          type: string
          example: '2026-10-14T10:45:00.000Z'
        items:
          type: array
          items:
            $ref: '#/components/schemas/YieldRewardBucketDto'
      required:
        - yieldId
        - address
        - token
        - interval
        - from
        - to
        - items
    YieldRewardTokenDto:
      type: object
      properties:
        symbol:
          type: string
          description: Token symbol
          example: USDC
        decimals:
          type: number
          description: Token decimal places
          example: 6
        network:
          type: string
          description: Token network
          enum:
            - ethereum
            - ethereum-goerli
            - ethereum-holesky
            - ethereum-sepolia
            - ethereum-hoodi
            - arbitrum
            - base
            - base-sepolia
            - gnosis
            - optimism
            - polygon
            - polygon-amoy
            - starknet
            - zksync
            - linea
            - unichain
            - plume
            - monad-testnet
            - monad
            - robinhood
            - robinhood-testnet
            - arc-testnet
            - arc
            - avalanche-c
            - avalanche-c-atomic
            - avalanche-p
            - binance
            - celo
            - fantom
            - harmony
            - moonriver
            - okc
            - viction
            - core
            - sonic
            - plasma
            - katana
            - hyperevm
            - tempo
            - pharos
            - xlayer
            - agoric
            - akash
            - axelar
            - band-protocol
            - bitsong
            - canto
            - chihuahua
            - comdex
            - coreum
            - cosmos
            - crescent
            - cronos
            - cudos
            - desmos
            - dydx
            - evmos
            - fetch-ai
            - gravity-bridge
            - injective
            - irisnet
            - juno
            - kava
            - ki-network
            - mars-protocol
            - nym
            - okex-chain
            - onomy
            - osmosis
            - persistence
            - quicksilver
            - regen
            - secret
            - sentinel
            - sommelier
            - stafi
            - stargaze
            - stride
            - teritori
            - tgrade
            - umee
            - sei
            - mantra
            - celestia
            - saga
            - zetachain
            - dymension
            - humansai
            - neutron
            - polkadot
            - kusama
            - westend
            - bittensor
            - aptos
            - binancebeacon
            - cardano
            - near
            - solana
            - solana-devnet
            - stellar
            - stellar-testnet
            - sui
            - tezos
            - tron
            - ton
            - ton-testnet
            - hyperliquid
          example: ethereum
        address:
          type: string
          description: Token address
          example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
      required:
        - symbol
        - decimals
        - network
    YieldRewardBucketDto:
      type: object
      properties:
        timestamp:
          type: string
          description: UTC start of this bucket
          example: '2026-10-07T00:00:00.000Z'
        amount:
          type: string
          description: Non-cumulative earnings in this bucket, as a decimal string
          example: '0.212345'
        amountRaw:
          type: string
          description: Non-cumulative earnings in this bucket, in base units
          example: '212345'
      required:
        - timestamp
        - amount
        - amountRaw
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.