> ## 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 comprehensive activity history for a Bitcoin address including transactions, inscriptions, and Runes.

# Satoshi Activity by Address



## OpenAPI

````yaml bitcoin/blockchain-indexer-api/openapi.json get /addresses/{address}/activity
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}/activity:
    get:
      tags:
        - Addresses
      summary: Satoshi Activity by Address
      description: >-
        Returns all transactions for a given address or script pubkey, allowing
        insight into when the balance increased, decreased, or remained the
        same. This endpoint supports customization to narrow results by time,
        transaction type, or ordering, enabling tailored historical views.
      operationId: satoshi_activity_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 transactions included on or after a specific height
          required: false
          schema:
            type: integer
            format: int64
            nullable: true
            minimum: 0
        - name: to
          in: query
          description: Return only transactions included on or before a specific height
          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: activity_kind
          in: query
          description: >-
            Only return transactions of a specific activity kind. Supported
            values: "increase" for transactions where satoshi balance increases,
            "decrease" for decrease, and "self_transfer" for transactions where
            satoshi balance remained the same.
          required: false
          schema:
            allOf:
              - $ref: '#/components/schemas/ActivityKindByAddress'
            nullable: true
        - name: exclude_self_transfers
          in: query
          description: >-
            Do not return self-transfer transactions - transactions in which
            satoshi balance did not increase or decrease.
          required: false
          schema:
            type: boolean
            nullable: true
      responses:
        '200':
          description: Requested data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedActivityByAddress'
              example:
                data:
                  - amount: '4456732'
                    confirmations: 48
                    height: 892671
                    kind: increase
                    tx_hash: >-
                      9f2d17f672ebb9962940aba94daef140cc876f32edba5e9325c18ca17534120e
                  - amount: '4456732'
                    confirmations: 43
                    height: 892676
                    kind: decrease
                    tx_hash: >-
                      2c34dbe0d8dcbf4faba291e50cda1d9b6f70cccdbb2fcd23a9341d2791845998
                last_updated:
                  block_hash: >-
                    00000000000000000000c7f19aca70cdeab9d7f04a79d1c8283b66dce78796e8
                  block_height: 892719
                next_cursor: null
        '400':
          description: Malformed query parameters
        '404':
          description: Requested entity not found on-chain
        '500':
          description: Internal server error
components:
  schemas:
    ActivityKindByAddress:
      type: string
      enum:
        - self_transfer
        - increase
        - decrease
    PaginatedActivityByAddress:
      type: object
      required:
        - data
        - last_updated
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ActivityByAddress'
        last_updated:
          $ref: '#/components/schemas/ChainTip'
        next_cursor:
          type: string
          nullable: true
    ActivityByAddress:
      type: object
      required:
        - height
        - confirmations
        - tx_hash
        - sat_activity
      properties:
        confirmations:
          type: integer
          format: int64
          description: Number of confirmation blocks.
          minimum: 0
        height:
          type: integer
          format: int64
          description: Height of block containing the satoshi activity.
          minimum: 0
        sat_activity:
          $ref: '#/components/schemas/SatActivity'
        tx_hash:
          type: string
          description: Hash of transaction containing the satoshi activity.
    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
    SatActivity:
      type: object
      required:
        - kind
        - amount
      properties:
        amount:
          type: string
          description: Amount of satoshis involved in the activity.
        kind:
          $ref: '#/components/schemas/ActivityKindByAddress'
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: api-key
      description: Project API Key

````