> ## 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 balance for an address at specific timestamps or block heights. # Historical Satoshi Balance by Address ## OpenAPI ````yaml bitcoin/blockchain-indexer-api/openapi.json get /addresses/{address}/balance/historical openapi: 3.0.3 info: title: Bitcoin - Blockchain Indexer API description: >- This API provides core indexer endpoints with support for Bitcoin metaprotocols by delivering real-time, rollback-protected access to Bitcoin's UTXO data, enabling developers to build responsive and reliable blockchain applications without managing complex infrastructure. #### Key Features: - **Real-Time Data with Rollback Protection:** Ensures data accuracy by handling chain reorganizations gracefully, providing live data without sacrificing integrity. - **Comprehensive UTXO Indexing:** Specialized pipelines extract, match, and process on-chain information, including handling rollbacks, to provide accurate and up-to-date data. #### Key Benefits for Developers: By abstracting the complexities of blockchain data retrieval and processing, Maestro's Bitcoin Indexer API empowers developers to focus on building innovative applications with confidence in fast and reliable access to historical chain data. 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: /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: historical_satoshi_balance_by_address parameters: - name: address in: path description: Bitcoin address or hex encoded script pubkey required: true schema: type: string example: bc1qcx7ys0ahvtfqcc63sfn6axls0qrhkadnslpd94 - 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 ````