> ## Documentation Index > Fetch the complete documentation index at: https://docs.gomaestro.org/llms.txt > Use this file to discover all available pages before exploring further. > Get historical Bitcoin satoshi balance data for an address at specific block heights or timestamps with USD valuation. # Historical Satoshi Balance by Address ## OpenAPI ````yaml bitcoin/wallet-api/openapi.json get /wallet/addresses/{address}/balance/historical openapi: 3.0.3 info: title: Bitcoin - Wallet API description: >- Maestro's Bitcoin Wallet API delivers detailed transaction activity data at the address level, spanning native Bitcoin (satoshis) and metaprotocol layers like inscriptions and runes. This API enables deep visibility into balance changes, token movements, and asset-specific behaviors. Useful for powering explorers, wallets, or dashboards with granular insight into address-level history and asset interactions. #### Key Features: - **Satoshi Activity Tracking:** Track and analyze satoshi-level balance changes—including increases, decreases, and self-transfers—with timestamped precision. Historical balances are itemized by either block height or timestamp, enabling accurate auditing, time-based analysis, and USD-denominated valuation over time. - **Inscription Insight:** Monitor Ordinals transactions, filtered by inscription ID, activity type (send/receive), or self-transfer logic to reduce noise from spam or internal moves. - **Rune Transaction Logging:** Track rune minting, transfers, etchings, and balance changes for a given address, including support for filtering by specific rune. - **Unified Metaprotocol View:** Fetch combined activity across satoshis, inscriptions, and runes in a single request to power holistic user or address histories. - **Mempool Awareness:** Provides insight into the latest activity from the mempool by _default_. The system monitors for block reorganizations and automatically rolls back unconfirmed or invalidated trades, ensuring the data reflects the confirmed state of the chain. #### Key Benefits for Developers: Developers gain the ability to surface address-level insights without having to manually parse raw blockchain data. The Wallet API simplifies historical activity analysis, enables protocol-specific filtering, and lets developers build UX-enhancing features like transaction history views, asset trackers, and real-time alerts for wallet activity without managing indexing infrastructure. license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.txt version: v0.2.0 servers: - url: https://xbt-mainnet.gomaestro-api.org/v0 description: Bitcoin Mainnet - url: https://xbt-testnet.gomaestro-api.org/v0 description: Bitcoin Testnet security: - api-key: [] paths: /wallet/addresses/{address}/balance/historical: get: tags: - Addresses summary: Historical Satoshi Balance by Address description: >- Returns the historical satoshi balances, itemized by block and including USD price. operationId: wallet_historical_satoshi_balance_by_address parameters: - name: address in: path description: Bitcoin address or hex encoded script pubkey required: true schema: type: string example: bc1phyrmjs2jm5c98tldke2ykp0h66lsx3wy0ey8ug2fjj5mxsn8ftqsa24un8 - name: order in: query description: >- The order in which the results are sorted. Supported values: asc, desc required: false schema: allOf: - type: string default: asc enum: - asc - desc nullable: true - name: count in: query description: The max number of results per page required: false schema: allOf: - type: integer default: 100 minimum: 0 nullable: true - name: from in: query description: >- Return only blocks included on or after a specific height or timestamps. If this parameter is not provided, the starting point will be the first block where the address has seen its balance increase or decrease. required: false schema: type: integer format: int64 nullable: true minimum: 0 - name: to in: query description: >- Return only blocks included on or before a specific height or timestamp required: false schema: type: integer format: int64 nullable: true minimum: 0 - name: cursor in: query description: >- Pagination cursor string, use the cursor included in a page of results to fetch the next page required: false schema: type: string nullable: true - name: height_params in: query description: >- Whether the from and to integer query params should be read as timestamps or as block heights. True (the default) means from and to params should be read as block heights. required: false schema: type: boolean nullable: true responses: '200': description: Requested data content: application/json: schema: $ref: '#/components/schemas/PaginatedHistoricalSatBalanceByAddress' example: data: - confirmations: 932 height: 899903 sat_balance: '155191' timestamp: '2025-06-05 12:34:23' unix_timestamp: 1749126863 usd_balance: '163.59' - confirmations: 931 height: 899904 sat_balance: '155191' timestamp: '2025-06-05 12:34:52' unix_timestamp: 1749126892 usd_balance: '163.59' - confirmations: 930 height: 899905 sat_balance: '155191' timestamp: '2025-06-05 12:35:24' unix_timestamp: 1749126924 usd_balance: '163.56' last_updated: block_hash: >- 000000000000000000014ba9b2d30d9c737423c753c5b6a27989815ed50afe04 block_height: 900834 next_cursor: null '400': description: Malformed query parameters '404': description: Requested entity not found on-chain '500': description: Internal server error components: schemas: PaginatedHistoricalSatBalanceByAddress: type: object required: - data - last_updated properties: data: type: array items: $ref: '#/components/schemas/HistoricalSatBalanceByAddress' last_updated: $ref: '#/components/schemas/ChainTip' next_cursor: type: string nullable: true HistoricalSatBalanceByAddress: type: object required: - height - confirmations - unix_timestamp - timestamp - sat_balance - usd_balance properties: confirmations: type: integer format: int64 description: Number of confirmation blocks. minimum: 0 height: type: integer format: int64 description: Block height. minimum: 0 sat_balance: type: string description: Satoshi balance of the address at the end of this block. timestamp: type: string description: The timestamp of the block, as claimed by the miner, in UTC format. unix_timestamp: type: integer format: int32 description: The timestamp of the block, as claimed by the miner, in UNIX format. minimum: 0 usd_balance: type: string description: >- USD balance if sat balance was exchanged. The exchange rate is that between USD and BTC at the time the block was mined. ChainTip: type: object required: - block_hash - block_height properties: block_hash: type: string description: The hash of the block example: 0000000000000000000a7f3b7b6b6e1d9a18db65a3b4a3f4f3bcb2e1f1b2d3e7 block_height: type: integer format: int64 description: The height of the block in the blockchain example: 707000 minimum: 0 securitySchemes: api-key: type: apiKey in: header name: api-key description: Project API Key ````