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

# Wallet - Balance Change

> Retrieve the balance change history of a wallet.

<Tabs>
  <Tab title="Usage Note">
    <p><strong>Balance-delta history for one Solana wallet.</strong></p>

    <ul>
      <li>Filter by <code>token\_address</code> when you want one token only, or omit it for broader wallet activity.</li>
      <li><code>token\_type</code> and <code>change\_type</code> narrow the result to the asset class and change direction you care about.</li>
      <li><code>time\_from</code> and <code>time\_to</code> let you constrain the review window.</li>
      <li>Pagination uses <code>offset</code> up to <code>10,000</code> and <code>limit</code> up to <code>100</code>.</li>
      <li><code>ui\_amount\_mode=scaled</code> applies Solana Token-2022 scaled UI amount when the token supports the scaled UI extension.</li>
    </ul>

    <p><strong>Reading the numbers.</strong> Balance-change rows explain how a wallet's token balance moved over time, which token changed, and by how much after decimal or scaled UI normalization.</p>
  </Tab>

  <Tab title="Accessibility">
    <ul>
      <li>Standard</li>
      <li>Lite</li>
      <li>Starter</li>
      <li>Premium</li>
      <li>Business</li>
      <li>Enterprise</li>
    </ul>
  </Tab>

  <Tab title="Chain Supported">
    <p><strong>Solana</strong></p>
  </Tab>
</Tabs>

<Accordion title="Compute Unit ⚙️" icon="fa-gauge-high">
  <ul>
    <li>This endpoint consumes <code>8 CU</code> per request.</li>
  </ul>
</Accordion>

<Accordion title="Use Cases 💡" icon="fa-lightbulb">
  <ul>
    <li>Review how a wallet accumulated, distributed, or rotated tokens over time.</li>
    <li>Power audit trails, treasury monitoring, and operator activity review.</li>
    <li>Isolate changes for one token before drilling into transfer-level events.</li>
  </ul>
</Accordion>

<Accordion title="How to Use 🛠️" icon="fa-book-open">
  <ul>
    <li>Set <code>x-chain=solana</code>.</li>
    <li>Pass the wallet address in <code>wallet</code>.</li>
    <li>Add <code>token\_address</code>, <code>token\_type</code>, or <code>change\_type</code> when you need a narrower slice.</li>
    <li>Use <code>time\_from</code> and <code>time\_to</code> for bounded investigations.</li>
    <li>Page through results with <code>offset</code> and <code>limit</code>.</li>
  </ul>
</Accordion>

<Accordion title="Best Practices ✅" icon="fa-check-circle">
  <ul>
    <li>Start broad, then add token and change filters once you see the wallet's activity pattern.</li>
    <li>Use this endpoint to find the interesting timestamps, then pair it with transfer endpoints for exact movement details.</li>
    <li>Keep <code>ui\_amount\_mode</code> aligned with other Solana Token-2022 analysis for consistent quantities.</li>
  </ul>
</Accordion>

<Accordion title="Limitations ⚠️" icon="fa-exclamation-triangle">
  <ul>
    <li>Solana only.</li>
    <li>Offset pagination tops out at <code>10,000</code>.</li>
  </ul>
</Accordion>

<br />


## OpenAPI

````yaml openapi/data/openapi_docs.json GET /wallet/v2/balance-change
openapi: 3.1.0
info:
  version: 1.1.0
  title: Birdeye Data API
  description: >-
    Birdeye Data API is a full-spectrum blockchain and DEX data platform for
    teams that need production-grade crypto market intelligence across tokens,
    pairs, wallets, traders, protocols, and chains.


    From real-time prices, OHLCV, liquidity, and transaction flow to holder
    analytics, token and pair overviews, wallet portfolio and PnL, smart money,
    discovery, security, and blockchain-level utilities, Birdeye gives you a
    unified data layer for building serious crypto products at scale.


    Use it to power exchange interfaces, trading terminals, bots, market-making
    systems, quant research, alpha screeners, portfolio apps, wallet
    intelligence tools, alerting systems, analytics dashboards, and back-office
    data pipelines. Whether your users are retail traders, pro desks, analysts,
    or infrastructure teams, Birdeye helps you ship faster with broad market
    coverage and API surfaces that support both lightweight integrations and
    data-heavy workflows.


    To start, create an account at [bds.birdeye.so](https://bds.birdeye.so),
    generate an API key from the `Security` tab, and send it in the `X-API-KEY`
    header on every request.
servers:
  - url: https://public-api.birdeye.so
security:
  - apiKeyAuth: []
tags:
  - name: Price & OHLCV
  - name: Stats
  - name: Token/Market List
  - name: Transactions
  - name: Wallet, Networth & PnL
  - name: Balance & Transfer
  - name: Holder
  - name: Alltime & History
  - name: Blockchain
  - name: Account
  - name: Token
  - name: Transaction
  - name: Creation & Trending
  - name: Meme
  - name: Security
  - name: Search & Utils
  - name: Smart Money
  - name: Global Fees Paid
  - name: DEX & Protocol
  - name: Wallet Identity
paths:
  /wallet/v2/balance-change:
    get:
      tags:
        - Balance & Transfer
      summary: Wallet - Balance Change
      description: Retrieve the balance change history of a wallet.
      operationId: get-wallet-v2-balance-change
      parameters:
        - $ref: '#/components/parameters/xSolanaChainParam'
        - $ref: '#/components/parameters/accountAddressParam'
        - $ref: '#/components/parameters/optionalTokenAddressParam'
        - $ref: '#/components/parameters/optionalTimeFromParam'
        - $ref: '#/components/parameters/optionalTimeToParam'
        - $ref: '#/components/parameters/walletBalanceTokenTypeParam'
        - $ref: '#/components/parameters/walletBalanceChangeTypeParam'
        - $ref: '#/components/parameters/onlyOffset10kParam'
        - $ref: '#/components/parameters/limit100Default20Param'
        - $ref: '#/components/parameters/uiAmountModeSplitParam'
      responses:
        '200':
          $ref: '#/components/responses/WalletBalanceChange'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    xSolanaChainParam:
      name: x-chain
      description: Solana network only.
      in: header
      required: false
      schema:
        type: string
        enum:
          - solana
        default: solana
    accountAddressParam:
      name: address
      description: The address of the account.
      in: query
      required: true
      schema:
        type: string
      examples:
        solana:
          value: eJpBLoF3bgXpzjxqJRAvMchjEo4EqdAmiQh3ASmEtZT
    optionalTokenAddressParam:
      name: token_address
      description: The address of the token contract.
      in: query
      schema:
        type: string
      examples:
        wsol:
          value: So11111111111111111111111111111111111111112
        solana:
          value: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
        ethereum:
          value: '0x95ad61b0a150d79219dcf64e1e6cc01f0b64c4ce'
        solana_scaled_ui:
          value: Xsc9qvGR1efVDFGLrVsmkzv3qi45LTBjeUKSPmx9qEh
    optionalTimeFromParam:
      name: time_from
      description: Specify the start time using unix timestamps in seconds
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 10000000000
      example: 1726700000
    optionalTimeToParam:
      name: time_to
      description: Specify the end time using unix timestamps in seconds
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 10000000000
      example: 1726704000
    walletBalanceTokenTypeParam:
      name: type
      in: query
      schema:
        type: string
        enum:
          - SOL
          - SPL
    walletBalanceChangeTypeParam:
      name: change_type
      in: query
      schema:
        type: string
        enum:
          - increase
          - decrease
    onlyOffset10kParam:
      name: offset
      description: Make sure offset <= 10000
      in: query
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
        maximum: 10000
    limit100Default20Param:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
    uiAmountModeSplitParam:
      name: ui_amount_mode
      description: >-
        Indicate whether to use the scaled amount for scaled ui amount tokens.
        Only support solana
      in: query
      required: false
      schema:
        type: string
        enum:
          - raw
          - scaled
        default: scaled
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Bad request
    '401':
      description: Unauthorized. API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Unauthorized
    '403':
      description: Forbidden. Request is blacklisted or not whitelisted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Access Denied
    '429':
      description: Too Many Requests. Rate limit reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Too many requests
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Internal Server Error
    WalletBalanceChange:
      description: JSON object containing a list of balance changes of an address
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WalletBalanceChangeResponseSchema'
          examples:
            Solana:
              value:
                success: true
                data:
                  items:
                    - time: '2025-08-01T08:55:58Z'
                      block_number: 357129280
                      block_unix_time: 1754038558
                      address: 51dEMNojjd2hZKrMeDWBRMPmhDS5QH1eCQWCdtR7CYKp
                      token_account: ATgjegWTEidtsDniCfVJp5Py86fi5X8nzRyzndfimr59
                      tx_hash: >-
                        mBxrLzapLZtcdPsKSr6EkUUXgFJDyXJs7bJcwQ58xh7JXhN7nsz9ELNspxsnG6TxVaJdzsbrkvhjgrX8QArrp4h
                      pre_balance: '257629693'
                      post_balance: '293106471'
                      amount: '35476777'
                      token_info:
                        address: 4a79c1TRehFCpHxQ7niHAiBAvHRJRWey3UkWuMDREKL7
                        decimals: 9
                        symbol: ''
                        name: ''
                        logo_uri: ''
                        is_scaled_ui_token: true
                        multiplier: 1.5
                      type: 2
                      type_text: SPL
                      change_type: 1
                      change_type_text: INCR
  schemas:
    WalletBalanceChangeResponseSchema:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          description: Whether the request succeeded.
        data:
          type: object
          properties:
            items:
              type: array
              description: Balance-change events for the requested wallet.
              items:
                type: object
                additionalProperties: true
                properties:
                  time:
                    type: string
                    description: Human-readable event time.
                  block_number:
                    type:
                      - integer
                      - string
                    description: Block or slot number of the event.
                  block_unix_time:
                    type: integer
                    description: Block timestamp in Unix seconds.
                  address:
                    type: string
                    description: Wallet address whose balance changed.
                  token_account:
                    type: string
                    description: Token account or balance slot address.
                  tx_hash:
                    type: string
                    description: Transaction signature or hash.
                  pre_balance:
                    type:
                      - number
                      - string
                    description: Balance before the change.
                  post_balance:
                    type:
                      - number
                      - string
                    description: Balance after the change.
                  amount:
                    type:
                      - number
                      - string
                    description: Signed balance delta for the event.
                  token_info:
                    type: object
                    additionalProperties: true
                    description: Metadata for the token whose balance changed.
                  type:
                    type: string
                    description: Machine-readable event type.
                  type_text:
                    type: string
                    description: Human-readable event type.
                  change_type:
                    type: string
                    description: Machine-readable change-direction classification.
                  change_type_text:
                    type: string
                    description: Human-readable change-direction label.
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````