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

# Wallet Reward Positions

> Lists a wallet's earn positions one by one, including closed ones, each with its identifier, units, unit price, value, principal and earnings. Pass `asOf` to read the positions as they were at a past time.

This endpoint reads the recorded history only. For the live per-product summary with today's and this week's earnings, use [Wallet Rewards](/en/api-reference/rewards/wallet-rewards).

### Query Parameters

| Key | Required | Type | Description |
| --- | --- | --- | --- |
| addressId | false | string (UUID) | Only positions held by this child address. Omit for every position in the wallet. |
| asOf | false | string (ISO 8601 date and time) | Read the positions as they were at this time. Cannot be in the future. Omit for the current positions. |
| page | false | number | Page number. |
| limit | false | number | Items per page. |

### Position Fields

| Field | Description |
| --- | --- |
| id | The position. Use it on the position and earnings endpoints. |
| scope | `master_wallet` for a position held by the master wallet, `address` for one held by a child address (`addressId` is then set). |
| positionStatus | `active` or `closed`. A closed position stays readable. |
| asOf | The time the figures describe. |
| units, unitDecimals | The amount of the product held, and its decimals. |
| unitPrice | Value of one base unit of the product in base units of the asset at `asOf`. |
| value | What the position was worth at `asOf`, in the asset, after fees. |
| deposited | Principal still in the position at `asOf`. |
| earnings | `value` minus `deposited`. |
| status | `complete` when every deposit and withdrawal of the position is on record; `incomplete_cost_basis` when the position was opened before history recording began, so `deposited` and `earnings` are measured from the start of the record; `unavailable` when no price was recorded for that time. |



## OpenAPI

````yaml get /v1/wallets/{walletId}/rewards/positions
openapi: 3.0.3
info:
  title: Blockradar Documentation
  description: >-
    The OpenAPI specification of the Blockradar API that enables fintechs and
    developers to seamlessly integrate stablecoin deposits and payments into
    their products.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.blockradar.co
security:
  - apiKey: []
tags:
  - name: Rewards
    description: >-
      Non-custodial yield (Earn) on stablecoins via DeFi (Aave) strategies.
      Deposit, withdraw, preview fees, and read positions and earnings at the
      business, wallet, and sub-address level. Amounts are returned net of the
      platform fee, which applies only to interest earned.
  - name: Wallet
    description: >-
      Wallet Management System


      Comprehensive wallet management API for multi-blockchain operations. This
      system handles wallet creation, configuration, balance monitoring, and
      integration with various blockchain networks.


      Core Functionality:


      - Multi-blockchain wallet creation and management

      - Balance monitoring and asset tracking

      - Auto-settlement rule configuration

      - Gateway wallet integration

      - Address generation and management

      - Transaction monitoring and processing
  - name: Addresses
    description: >-
      Address Management System


      Comprehensive blockchain address management API for operations. This
      system handles address creation, validation, monitoring, and management
      across multiple blockchain networks.


      Core Functionality:


      - Multi-blockchain address generation

      - Address validation and verification

      - Balance monitoring and tracking

      - Transaction history management

      - Address labeling and organization

      - Integration with wallet systems

      - Real-time address monitoring
  - name: Asset
  - name: Transactions
  - name: Withdraw
    description: >-
      The Withdraw feature allows you to programmatically withdraw stablecoins
      from your master wallet with ease
  - name: Withdraw Fiat
  - name: Signing
    description: >-
      Signing service for plain text messages, raw transactions, and EIP-712
      typed data. Message signing, transaction signing, and sign-and-broadcast
      are available on EVM, Tron, Solana, and Stellar. Typed data signing
      (EIP-712, including EIP-2612 Permit and EIP-3009
      TransferWithAuthorization) is EVM-only.
  - name: Swap
    description: >-
      The Swap feature enables users to exchange one stabelcoin asset for
      another across different blockchains. This feature provides a seamless way
      to convert between different stablecoins while maintaining security and
      compliance standards.
  - name: Liquidity Pool
  - name: Virtual Accounts
    description: >-
      Virtual Accounts API provides endpoints for managing virtual bank accounts
      linked to master wallets or child addresses. This API enables businesses
      to:


      - Create virtual accounts for customers to receive payments

      - Retrieve virtual account details

      - Activate/deactivate virtual accounts


      **Virtual Account Types:**


      Virtual accounts support different types with varying behaviors:


      1. **AUTO_FUNDING** (Default):

          - Automatically mints stablecoin when fiat payments are received

          - Transfers the stablecoin to the linked wallet/address immediately

          - Best for real-time payment processing


      **How It Works - Auto-Funding Flow (AUTO_FUNDING type only):**


      When a customer sends fiat currency to a virtual account with type
      AUTO_FUNDING:


      1. **Payment Receipt**: The payment is received in the virtual account

      2. **Automatic Minting**: The system automatically mints the stablecoin
      equivalent

      3. **Blockchain Transfer**: The minted stablecoin is transferred to the
      virtual account's linked wallet or address


      **Note**: The auto-funding flow only applies to virtual accounts with type
      `AUTO_FUNDING`.

      Other types have different processing behaviors.


      ## Prerequisites


      Before creating virtual accounts, ensure:


      - **Compliance requirements must be completed** (see [Compliance
      Requirements](http://localhost:3000/essentials/virtual-accounts#compliance-requirements)
      section below)

      - **Virtual accounts feature must be enabled** for your business (reach
      out to [support@blockradar.co](https://mailto:support@blockradar.co) or
      use live chat on the dashboard to enable the feature after compliance
      approval)

      - **Environment-aware routing** - testnet requests use only testnet routes
      and wallets, while mainnet requests use only mainnet routes and wallets

      - **Master Wallet must support stablecoin asset** - Your account plan must
      include stablecoin access (upgrade from Dashboard → Settings →
      Subscription if needed)


      **Supported Currency:**


      - Fiat: NGN (Nigerian Naira)

      - Stablecoin: cNGN - minted automatically on blockchain (for AUTO_FUNDING
      type)
  - name: Auto Settlements
    description: >-
      Creates a new auto settlement rule for a wallet. Auto settlement
      automatically transfers/swap assets based on configured rules when certain
      conditions are met.


      Rules can be configured for:


      - Source blockchain and assets

      - Destination blockchain and asset

      - Amount ranges (min/max)

      - Slippage tolerance

      - Gateway vs non-gateway wallets


      Gateway rules are required for testnet wallets and must have matching
      source/destination assets.
  - name: Smart Contract
    description: >-
      This API provides endpoints for interacting with smart contracts on the
      blockchain. It allows for reading contract data, executing contract
      functions, and estimating network fees.
  - name: Gateway
    description: >-
      The Gateway feature enables you to programmatically deposit USDC into a
      unified, chain-abstracted balance and instantly mint USDC on any supported
      blockchain, streamlining crosschain transfers and eliminating manual
      bridging steps and rebalancing complexities.
  - name: Payment Links
    description: >-
      The Payment Pages API provides a quick and secure way to collect payment
      for servcies.
  - name: Beneficiaries
    description: >-
      This API allows you to create beneficiaries with automatic settlements to
      your external wallets on a periodic basis.


      Example frequencies: INSTANT, DAILY, WEEKLY, MONTHLY, YEARLY
  - name: AML
    description: >-
      The AML (Anti Money Laundering) API provides a quick way for you to check
      if an address is blacklisted or sanctioned
  - name: Asset Recovery
    description: >-
      Enables the recovery (salvage) of both native blockchain assets and tokens
      from a specified sender address to a recipient address. This feature
      supports emergency fund recovery and asset consolidation operations.
  - name: Miscellaneous
    description: >-
      The Miscellaneous API are supporting APIs that can be used to provide more
      details to other APIs.
  - name: Asset1
  - name: Blockchain
  - name: Webhooks
    description: >-
      Webhooks allow you to set up a notification system that can be used to
      receive updates on certain requests made to the Blockradar API.

      To see full list and instructions
      [https://docs.blockradar.co/essentials/webhooks](https://docs.blockradar.co/essentials/webhooks)


      ##
  - name: Deposit
  - name: Withdraw1
  - name: Swap1
  - name: Gateway1
paths:
  /v1/wallets/{walletId}/rewards/positions:
    get:
      tags:
        - Rewards
      summary: Wallet Reward Positions
      description: >-
        Lists a wallet's earn positions one by one, including closed ones, each
        with its identifier, units, unit price, value, principal and earnings.
        Pass `asOf` to read the positions as they were at a past time.


        This endpoint reads the recorded history only. For the live per-product
        summary with today's and this week's earnings, use [Wallet
        Rewards](/en/api-reference/rewards/wallet-rewards).


        ### Query Parameters


        | Key | Required | Type | Description |

        | --- | --- | --- | --- |

        | addressId | false | string (UUID) | Only positions held by this child
        address. Omit for every position in the wallet. |

        | asOf | false | string (ISO 8601 date and time) | Read the positions as
        they were at this time. Cannot be in the future. Omit for the current
        positions. |

        | page | false | number | Page number. |

        | limit | false | number | Items per page. |


        ### Position Fields


        | Field | Description |

        | --- | --- |

        | id | The position. Use it on the position and earnings endpoints. |

        | scope | `master_wallet` for a position held by the master wallet,
        `address` for one held by a child address (`addressId` is then set). |

        | positionStatus | `active` or `closed`. A closed position stays
        readable. |

        | asOf | The time the figures describe. |

        | units, unitDecimals | The amount of the product held, and its
        decimals. |

        | unitPrice | Value of one base unit of the product in base units of the
        asset at `asOf`. |

        | value | What the position was worth at `asOf`, in the asset, after
        fees. |

        | deposited | Principal still in the position at `asOf`. |

        | earnings | `value` minus `deposited`. |

        | status | `complete` when every deposit and withdrawal of the position
        is on record; `incomplete_cost_basis` when the position was opened
        before history recording began, so `deposited` and `earnings` are
        measured from the start of the record; `unavailable` when no price was
        recorded for that time. |
      operationId: getWalletRewardPositions
      parameters:
        - name: walletId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Wallet identifier.
        - name: addressId
          in: query
          schema:
            type: string
            example: ''
        - name: asOf
          in: query
          schema:
            type: string
            format: date-time
            example: '2026-11-18T12:00:00Z'
        - name: page
          in: query
          schema:
            type: number
            example: 1
        - name: limit
          in: query
          schema:
            type: number
            example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              example:
                message: Reward positions retrieved successfully
                statusCode: 200
                data:
                  - id: 6b1a3d0e-5c0f-4d0a-9d2e-2f4f6c1f7a10
                    productId: 3aa81215-585a-4db2-9707-339a01ad794d
                    productKey: ground-tempo-prime
                    provider: ground
                    type: regulated
                    addressId: null
                    scope: master_wallet
                    positionStatus: active
                    asOf: '2026-11-18T12:00:00.000Z'
                    units: '9341001175079031360'
                    unitDecimals: 18
                    unitPrice: '0.000000000001071040000000'
                    value: '10.004585'
                    deposited: '10.000000'
                    earnings: '0.004585'
                    status: complete
                    asset:
                      id: 3e8b5b88-8bd3-4106-9100-82a48d7133b7
                      symbol: USDC.e
                      decimals: 6
                      address: '0x20C000000000000000000000b9537d11c60E8b50'
                    createdAt: '2026-11-18T08:30:00.000Z'
                meta:
                  totalItems: 1
                  itemCount: 1
                  itemsPerPage: 10
                  totalPages: 1
                  currentPage: 1
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header

````

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