schema.yml

openapi: 3.0.3
info:
  title: Stampchain - OpenAPI 3.0
  description: Stampchain API UI
  version: 2.3.0
  license:
    name: GNU Affero General Public License v3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
  contact:
    name: Stampchain Support
    url: https://stampchain.io
    email: api@stampchain.io
tags:
  - name: System
    description: System-level endpoints for health and version checks
  - name: Documentation
    description: API documentation endpoints
  - name: Balance
    description: STAMPS, SRC-101, and SRC-20 balance-related endpoints
  - name: Blocks
    description: Block-related endpoints
  - name: Collections
    description: Collection management endpoints
  - name: Cursed Stamps
    description: Endpoints for managing cursed stamps
  - name: SRC-20
    description: SRC-20 token related endpoints
  - name: SRC-101
    description: SRC-101 token related endpoints
  - name: Stamps
    description: Stamp management endpoints
  - name: Dispensers
    description: Dispenser management endpoints
  - name: Minting
    description: Token and stamp minting endpoints
  - name: UTXO
    description: UTXO management endpoints
  - name: API Keys
    description: API key signup and usage endpoints
externalDocs:
  description: Find out more about Stampchain
  url: "http://stampchain.io"
servers:
  - url: "https://stampchain.io"
    description: Production server (uses live data)
  - url: "https://dev.stampchain.io"
    description: Production server (uses live data)

security:
  - ApiKeyAuth: []

paths:
  /api/v2/health:
    get:
      operationId: getHealthStatus
      tags:
        - System
      summary: Health check endpoint
      description: |
        Checks if the API service is running and responding correctly.
        Validates the status of core services including the API, indexer, and mempool connectivity.
        Also provides block synchronization status between the indexer and network.
        Includes current versions of system components (Bitcoin Core, Counterparty, Stamps Indexer) when available.
      responses:
        "200":
          description: Detailed health status of the system and its services
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: ["OK", "ERROR"]
                    description: Overall system health status
                  services:
                    type: object
                    properties:
                      api:
                        type: boolean
                        description: API service connectivity
                      indexer:
                        type: boolean
                        description: Indexer service connectivity
                      mempool:
                        type: boolean
                        description: Mempool API connectivity
                      database:
                        type: boolean
                        description: Database connectivity
                      xcp:
                        type: boolean
                        description: Counterparty node connectivity
                      blockSync:
                        type: object
                        description: Block synchronization information
                        properties:
                          indexed:
                            type: integer
                            description: Last indexed block height
                          network:
                            type: integer
                            description: Current network block height
                          isSynced:
                            type: boolean
                            description: Whether the indexer is in sync with the network (allowing 1 block lag)
                      stats:
                        type: object
                        description: System-wide statistics
                        properties:
                          src20Deployments:
                            type: integer
                            description: Total number of SRC-20 tokens deployed
                          totalStamps:
                            type: integer
                            description: Total number of stamps in the system
                      nodeVersions:
                        type: array
                        description: Current versions of system components (bitcoin_core, counterparty, stamps_indexer)
                        items:
                          type: object
                          required:
                            - component_name
                            - version_string
                            - detected_at
                          properties:
                            component_name:
                              type: string
                              description: Component identifier (e.g. bitcoin_core, counterparty:local, stamps_indexer)
                            version_string:
                              type: string
                              description: Full version string (e.g. 28.0.0, 11.0.3, 1.8.26+canary.258)
                            version_major:
                              type: integer
                              nullable: true
                              description: Parsed major version number
                            version_minor:
                              type: integer
                              nullable: true
                              description: Parsed minor version number
                            version_revision:
                              type: integer
                              nullable: true
                              description: Parsed revision/patch version number
                            version_suffix:
                              type: string
                              nullable: true
                              description: Version suffix (e.g. canary.258, rc1)
                            extra_info:
                              type: object
                              nullable: true
                              description: Component-specific metadata (varies per component)
                            detected_at:
                              type: string
                              format: date-time
                              description: When this version was first detected
              example:
                status: "OK"
                services:
                  api: true
                  indexer: true
                  mempool: true
                  database: true
                  blockSync:
                    indexed: 800000
                    network: 800001
                    isSynced: true
                  stats:
                    src20Deployments: 100000
                    totalStamps: 1000000
                  nodeVersions:
                    - component_name: "bitcoin_core"
                      version_string: "28.0.0"
                      version_major: 28
                      version_minor: 0
                      version_revision: 0
                      version_suffix: null
                      extra_info:
                        subversion: "/Satoshi:28.0.0/"
                        protocolversion: 70016
                        connections: 125
                      detected_at: "2026-02-27T00:00:00.000Z"
                    - component_name: "stamps_indexer"
                      version_string: "1.8.26+canary.258"
                      version_major: 1
                      version_minor: 8
                      version_revision: 26
                      version_suffix: "canary.258"
                      extra_info: null
                      detected_at: "2026-02-27T00:00:00.000Z"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/docs:
    get:
      operationId: getApiDocs
      tags:
        - Documentation
      summary: API documentation
      description: Returns the OpenAPI documentation. Can be filtered by path or tag.
      parameters:
        - in: query
          name: path
          schema:
            type: string
          description: Optional path to filter documentation for a specific endpoint
          example: "/api/v2/olga/mint"
        - in: query
          name: tag
          schema:
            type: string
          description: Optional tag to filter documentation by category
          example: "Minting"
      responses:
        "200":
          description: Successful response with API documentation
          content:
            application/json:
              schema:
                oneOf:
                  - description: Full API documentation (no filters)
                    type: object
                    required:
                      - openapi
                      - info
                      - paths
                    properties:
                      openapi:
                        type: string
                        description: OpenAPI version
                        example: "3.0.3"
                      info:
                        type: object
                        description: API information
                        required:
                          - title
                          - version
                        properties:
                          title:
                            type: string
                          description:
                            type: string
                          version:
                            type: string
                      paths:
                        type: object
                        description: Formatted endpoint documentation
                      tags:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            description:
                              type: string
                      servers:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                            description:
                              type: string
                  - description: Filtered documentation response
                    type: object
                    required:
                      - documentation
                    properties:
                      documentation:
                        type: array
                        items:
                          type: object
                          required:
                            - path
                            - method
                          properties:
                            path:
                              type: string
                              description: Endpoint path
                            method:
                              type: string
                              description: HTTP method
                              enum: [GET, POST, PUT, DELETE, PATCH]
                            summary:
                              type: string
                              description: Brief description of the endpoint
                            description:
                              type: string
                              description: Detailed endpoint description
                            tags:
                              type: array
                              items:
                                type: string
                              description: Associated tags
                            parameters:
                              type: array
                              description: Endpoint parameters
                              items:
                                type: object
                            requestBody:
                              type: object
                              nullable: true
                              description: Request body schema if applicable
                            responses:
                              type: array
                              description: Possible responses
                              items:
                                type: object
                                properties:
                                  code:
                                    type: string
                                    description: HTTP status code
                                  description:
                                    type: string
                                    description: Response description
                                  content:
                                    type: object
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/version:
    get:
      operationId: getApiVersion
      tags:
        - System
      summary: Get API version
      description: Returns the current version of the API being used.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/error:
    get:
      operationId: testErrorResponse
      tags:
        - System
      summary: Test error endpoint
      description: Test endpoint that always returns an error response. Used for testing error handling and responses.
      responses:
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseBody"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/versions:
    get:
      operationId: getApiVersions
      tags:
        - System
      summary: Get available API versions
      description: |
        Returns information about all available API versions, their status, and migration information.

        Use the API-Version header to request a specific API version:
        - API-Version: 2.2 (stable, legacy)
        - API-Version: 2.3 (current, with enhanced market data)

        Default version is 2.3 when no header is specified.
      parameters:
        - in: header
          name: API-Version
          schema:
            type: string
            example: "2.3"
          description: Specify the API version to use
      responses:
        "200":
          description: Available API versions and their status
          content:
            application/json:
              schema:
                type: object
                properties:
                  current:
                    type: string
                    description: Current/latest API version
                    example: "2.3"
                  requestedVersion:
                    type: string
                    description: Version used for this request
                    example: "2.3"
                  versions:
                    type: array
                    items:
                      type: object
                      properties:
                        version:
                          type: string
                          example: "2.3"
                        status:
                          type: string
                          enum: [current, supported, deprecated]
                        releaseDate:
                          type: string
                          format: date
                        endOfLife:
                          type: string
                          format: date
                          nullable: true
                        links:
                          type: object
                          properties:
                            documentation:
                              type: string
                              format: uri
                            changelog:
                              type: string
                              format: uri
                            migration:
                              type: string
                              format: uri
                              nullable: true
                  headers:
                    type: object
                    description: Supported version headers
                  links:
                    type: object
                    properties:
                      changelog:
                        type: string
                        format: uri
                      documentation:
                        type: string
                        format: uri
                  deprecationNotice:
                    type: object
                    nullable: true
                    description: Present if using deprecated version
                    properties:
                      message:
                        type: string
                      migrationGuide:
                        type: string
                        format: uri
                      currentVersion:
                        type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/versions/changelog:
    get:
      operationId: getApiChangelog
      tags:
        - System
      summary: Get API version changelog
      description: |
        Returns detailed changelog for all API versions including:
        - New features and fields added
        - Improvements and optimizations
        - Bug fixes
        - Deprecated features
      responses:
        "200":
          description: API version changelog
          content:
            application/json:
              schema:
                type: object
                properties:
                  changelog:
                    type: array
                    items:
                      type: object
                      properties:
                        version:
                          type: string
                          example: "2.3.0"
                        releaseDate:
                          type: string
                          format: date
                        status:
                          type: string
                          enum: [current, supported, deprecated]
                        endOfLife:
                          type: string
                          format: date
                          nullable: true
                        changes:
                          type: object
                          properties:
                            added:
                              type: array
                              items:
                                type: string
                            improved:
                              type: array
                              items:
                                type: string
                            fixed:
                              type: array
                              items:
                                type: string
                            deprecated:
                              type: array
                              items:
                                type: string
                  currentVersion:
                    type: string
                    example: "2.3"
                  deprecationPolicy:
                    type: object
                    properties:
                      notice:
                        type: string
                        example: "6 months"
                      support:
                        type: string
                        example: "12 months after deprecation"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/balance/{address}:
    get:
      operationId: getAddressBalance
      tags:
        - Balance
      summary: Get combined stamp and SRC-20 balances
      description: |
        Convenience endpoint that combines stamp and SRC-20 balance data in a single request.
        For better performance and pagination control, consider using the dedicated endpoints:
        - /api/v2/stamps/balance/{address}
        - /api/v2/src20/balance/{address}
      parameters:
        - in: path
          name: address
          required: true
          example: "1GotRejB6XsGgMsM79TvcypeanDJRJbMtg"
          schema:
            type: string
          description: The Bitcoin address to query
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response with combined balances
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedBalanceResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/block/{block_index}:
    get:
      operationId: getBlockInfo
      tags:
        - Blocks
      summary: Get block info by block index or block hash
      description: Retrieves detailed information about a specific block, including transactions, stamps, and other block-related data.
      parameters:
        - in: path
          name: block_index
          required: true
          example: "844755"
          schema:
            type: string
          description: The block index or block hash
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockInfoResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/block/block_count/{number}:
    get:
      operationId: getLastBlocks
      tags:
        - Blocks
      summary: Get last x blocks
      description: Returns information about the most recent blocks, with the number of blocks specified in the request.
      parameters:
        - in: path
          name: number
          required: true

          example: 1
          schema:
            type: integer
          description: The number of last blocks to retrieve
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BlockRow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/collections:
    get:
      operationId: getCollections
      tags:
        - Collections
      summary: Get paginated collections
      description: Retrieves a paginated list of all stamp collections.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedCollectionResponseBody"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/collections/creator/{creator}:
    get:
      operationId: getCollectionsByCreator
      tags:
        - Collections
      summary: Get collections by creator
      description: Retrieves a paginated list of stamp collections for a specific creator.
      parameters:
        - in: path
          name: creator
          required: true

          example: "bc1qefhvcqwuz6g6qy6nck5dq2el2r37pky73tqxkc"
          schema:
            type: string
          description: "Creator address to filter collections by"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedCollectionResponseBody"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/collections/{id}:
    get:
      operationId: getCollectionById
      tags:
        - Collections
      summary: Get collection details by ID
      description: |
        Returns detailed information for a specific collection by its UUID identifier.
        Includes collection metadata, paginated stamps array, and aggregated market data
        from the collection_market_data table.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{32}$'
          description: Collection UUID (32 hex characters, with or without hyphens)
          example: "550e8400e29b41d4a716446655440000"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
        - in: query
          name: includeMarketData
          schema:
            type: boolean
            default: true
          description: Whether to include market data in the response
      responses:
        "200":
          description: Successful response with collection details
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection_id:
                    type: string
                    description: Collection UUID
                  collection_name:
                    type: string
                    description: Collection name
                  collection_description:
                    type: string
                    description: Collection description
                  creators:
                    type: array
                    items:
                      type: string
                    description: Array of creator addresses
                  stamp_count:
                    type: integer
                    description: Number of stamps in collection
                  total_editions:
                    type: number
                    description: Total editions across all stamps
                  stamps:
                    type: array
                    items:
                      $ref: "#/components/schemas/StampRow"
                    description: Paginated array of stamps in the collection
                  marketData:
                    $ref: "#/components/schemas/CollectionMarketData"
                    nullable: true
                    description: Aggregated market data from collection_market_data table
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalPages:
                        type: integer
                      total:
                        type: integer
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseBody"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/cursed:
    get:
      operationId: getCursedStamps
      tags:
        - Cursed Stamps
      summary: Get paginated cursed stamps
      description: Retrieves a paginated list of cursed stamps. Cursed stamps are stamps with negative stamp numbers that have been identified as invalid or problematic.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Sort"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedStampResponseBody"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/cursed/{id}:
    get:
      operationId: getCursedStampById
      tags:
        - Cursed Stamps
      summary: Get stamp by ID {tx_hash, stamp, cpid}
      description: |
        Retrieves a specific cursed stamp by its identifier. Cursed stamps simply have a negative stamp number.
        This endpoint is equivalent to /api/v2/stamps/{id} but specifically for cursed stamps.
      parameters:
        - in: path
          name: id
          required: true

          example: "-2"
          schema:
            type: string
          description: Stamp number, cpid, or stamp_hash
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StampResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/cursed/block/{block_index}:
    get:
      operationId: getCursedStampsByBlock
      tags:
        - Cursed Stamps
      summary: Get cursed stamps by block index
      description: Retrieves all cursed stamps that were created or identified in a specific block.
      parameters:
        - in: path
          name: block_index
          required: true

          example: 781141
          schema:
            type: integer
          description: The block index
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StampBlockResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20:
    get:
      operationId: getSrc20Transactions
      tags:
        - SRC-20
      summary: Get paginated valid SRC-20 transactions with market data filtering
      description: |
        Retrieves a paginated list of valid SRC-20 transactions with optional market data filtering.
        The new filters allow querying based on holder metrics, price ranges, volume, and data quality.
        API version 2.3 includes enhanced market data in responses.
      parameters:
        - in: header
          name: API-Version
          schema:
            type: string
            default: "2.3"
            example: "2.3"
          description: Specify the API version (2.2 for legacy format, 2.3 for enhanced market data)
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
        - name: sort
          in: query
          schema:
            type: string
            enum:
              [
                ASC,
                DESC,
                HOLDERS_DESC,
                HOLDERS_ASC,
                MARKET_CAP_DESC,
                MARKET_CAP_ASC,
                VALUE_DESC,
                VALUE_ASC,
                PRICE_DESC,
                PRICE_ASC,
                VOLUME_24H_DESC,
                VOLUME_24H_ASC,
                VOLUME_7D_DESC,
                VOLUME_7D_ASC,
                VOLUME_30D_DESC,
                VOLUME_30D_ASC,
                CHANGE_24H_DESC,
                CHANGE_24H_ASC,
                CHANGE_7D_DESC,
                CHANGE_7D_ASC,
                SUPPLY_DESC,
                SUPPLY_ASC,
                PROGRESS_DESC,
                PROGRESS_ASC,
                LIMIT_DESC,
                LIMIT_ASC,
                DECIMALS_DESC,
                DECIMALS_ASC,
                DEPLOY_DESC,
                DEPLOY_ASC,
                RECENT_DESC,
                RECENT_ASC,
                BLOCK_DESC,
                BLOCK_ASC,
                TICK_DESC,
                TICK_ASC,
                CREATOR_DESC,
                CREATOR_ASC,
              ]
            default: "DESC"
          description: |
            Comprehensive sort options for SRC-20 transactions:

            **⚠️ OPERATION-SPECIFIC RESTRICTIONS:**
            - **DEPLOY operations**: All sorting options available
            - **MINT/TRANSFER operations**: Limited to basic, activity, and alphabetical sorting only
            - **Market data and token metrics sorting**: Only available for DEPLOY operations

            **Basic Sorting (All Operations):**
            - ASC/DESC: Sort by block index (deploy date)
            - DEPLOY_DESC/DEPLOY_ASC: Sort by deploy date (block_index)
            - BLOCK_DESC/BLOCK_ASC: Sort by block index
            - TICK_DESC/TICK_ASC: Sort alphabetically by tick name
            - CREATOR_DESC/CREATOR_ASC: Sort by creator address

            **DEPLOY-Only Market Data Sorting:**
            - HOLDERS_DESC/HOLDERS_ASC: Sort by holder count
            - MARKET_CAP_DESC/MARKET_CAP_ASC: Sort by market cap (BTC)
            - VALUE_DESC/VALUE_ASC: Sort by floor price/market value
            - PRICE_DESC/PRICE_ASC: Alias for VALUE sorting
            - VOLUME_24H/7D/30D_DESC/ASC: Sort by trading volume
            - CHANGE_24H/7D_DESC/ASC: Sort by price change percentage

            **DEPLOY-Only Token Metrics Sorting:**
            - SUPPLY_DESC/SUPPLY_ASC: Sort by max supply (numeric)
            - PROGRESS_DESC/PROGRESS_ASC: Sort by mint progress percentage
            - LIMIT_DESC/LIMIT_ASC: Sort by mint limit per transaction
            - DECIMALS_DESC/DECIMALS_ASC: Sort by token decimals

            **MINT/TRANSFER-Only Sorting:**
            - AMOUNT_DESC/AMOUNT_ASC: Sort by transaction amount
            - RECENT_DESC/RECENT_ASC: Sort by recent activity (block_time)

            **Example Usage:**
            - `?op=DEPLOY&sortBy=SUPPLY_DESC` ✅ Valid
            - `?op=MINT&sortBy=SUPPLY_DESC` ❌ Invalid - returns error
            - `?op=MINT&sortBy=AMOUNT_DESC` ✅ Valid
        # Market Data Filters for SRC-20 (Task 42)
        - name: minHolderCount
          in: query
          description: Minimum number of holders for the SRC-20 token
          schema:
            type: integer
            minimum: 0
          example: 10
        - name: maxHolderCount
          in: query
          description: Maximum number of holders for the SRC-20 token
          schema:
            type: integer
            minimum: 0
          example: 1000
        - name: minFloorPriceBTC
          in: query
          description: Minimum floor price in BTC
          schema:
            type: number
            format: float
            minimum: 0
          example: 0.00001
        - name: maxFloorPriceBTC
          in: query
          description: Maximum floor price in BTC
          schema:
            type: number
            format: float
            minimum: 0
          example: 0.1
        - name: minVolume24h
          in: query
          description: Minimum 24-hour trading volume in BTC
          schema:
            type: number
            format: float
            minimum: 0
          example: 0.001
        - name: minPriceChange24h
          in: query
          description: Minimum 24-hour price change percentage
          schema:
            type: number
            format: float
          example: -10
        - name: minDataQualityScore
          in: query
          description: Minimum data quality score (0-10)
          schema:
            type: integer
            minimum: 0
            maximum: 10
          example: 7
        - name: primaryExchange
          in: query
          description: Filter by primary exchange source
          schema:
            type: string
          example: "openstamp"
        # v2.3 Enhanced Filtering Parameters
        - name: mintingStatus
          in: query
          description: |
            Filter tokens by minting status (v2.3+)
            - all: Return all tokens (default)
            - minting: Return only tokens still being minted (progress < 100%)
            - minted: Return only fully minted tokens (progress = 100%)
          schema:
            type: string
            enum:
              - all
              - minting
              - minted
            default: all
        - name: includeProgress
          in: query
          description: |
            Include detailed mint progress data in the response.
            Adds mint_progress object with progress percentage, current minted amount, and max supply.
          schema:
            type: boolean
            default: false
          example: true
        - name: includeMarketData
          in: query
          description: |
            Include comprehensive market data in the response.
            Adds market_data object with price, volume, holder count, and change metrics.
            Note: Automatically included for DEPLOY operations.
          schema:
            type: boolean
            default: false
          example: true
        - name: trendingWindow
          in: query
          description: Time window for trending calculations and volume metrics
          schema:
            type: string
            enum: ["24h", "7d", "30d"]
          example: "24h"
        - name: mintVelocityMin
          in: query
          description: Minimum minting velocity (tokens minted per hour) to filter by
          schema:
            type: number
            format: float
            minimum: 0
          example: 100.5
      responses:
        "200":
          description: Successful response with paginated SRC-20 transactions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSrc20ResponseBody"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/balance/{address}:
    get:
      operationId: getSrc20AddressBalance
      tags:
        - SRC-20
        - Balance
      summary: Get SRC-20 balances by BTC wallet address
      description: |
        Retrieves all SRC-20 token balances for a specific Bitcoin address.
        API version 2.3 includes enhanced market data in nested marketData objects.
        API version 2.2 maintains legacy flat structure for backward compatibility.
      parameters:
        - in: path
          name: address
          required: true

          description: The address of the wallet
          schema:
            type: string
          example: "1GotRejB6XsGgMsM79TvcypeanDJRJbMtg"
        - in: header
          name: API-Version
          schema:
            type: string
            default: "2.3"
            example: "2.3"
          description: Specify the API version (2.2 for legacy format, 2.3 for enhanced market data)
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response with SRC-20 balance data
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/PaginatedSrc20BalanceResponseBody"
                  - $ref: "#/components/schemas/PaginatedSrc20WithMarketDataResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/balance/{address}/{tick}:
    get:
      operationId: getSrc20AddressTickBalance
      tags:
        - SRC-20
        - Balance
      summary: Get SRC-20 balance by address and tick
      description: Retrieves the balance of a specific SRC-20 token (identified by tick) for a given Bitcoin address.
      parameters:
        - in: path
          name: address
          required: true

          example: "bc1qx6tg7nls0u949wy8eudwcaw0rcq0vl7ehh6p9l"
          schema:
            type: string
          description: The address of the wallet
        - in: path
          name: tick
          required: true

          example: "STAMP"
          schema:
            type: string
          description: The tick value
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Src20BalanceResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/balance/snapshot/{tick}:
    get:
      operationId: getSrc20TickSnapshot
      tags:
        - SRC-20
        - Balance
      summary: Get SRC-20 balance snapshot by tick on current block height
      description: |
        Retrieves a snapshot of all owners for the SRC-20 tick value based upon the current block height.
        This provides a complete overview of token distribution at the current point in time.
      parameters:
        - in: path
          name: tick
          required: true

          example: "KEVIN"
          schema:
            type: string
          description: The SRC20 tick value
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Src20SnapshotResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/block/{block_index}:
    get:
      operationId: getSrc20BlockTransactions
      tags:
        - SRC-20
      summary: Get paginated valid SRC-20 transactions from a specific block
      description: Retrieves all SRC-20 transactions that occurred in a specific block. Results can be filtered and paginated.
      parameters:
        - in: path
          name: block_index
          required: true

          example: 844757
          schema:
            type: integer
          description: The index of the block
        - in: query
          name: op
          required: false
          schema:
            type: string
          description: The operation type, if applicable.
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Sort"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSrc20ResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/block/{block_index}/{tick}:
    get:
      operationId: getSrc20BlockTickTransactions
      tags:
        - SRC-20
      summary: Fetches SRC20 transactions for a given block and tick
      description: Retrieves SRC20 transactions filtered by block index and tick value, with additional optional filtering and pagination parameters.
      parameters:
        - in: path
          name: block_index
          required: true

          example: 844757
          schema:
            type: integer
            format: int32
          description: The index of the block.
        - in: path
          name: tick
          required: true

          example: "STAMP"
          schema:
            type: string
          description: The tick value, possibly represented as an emoji.
        - in: query
          name: op
          required: false
          schema:
            type: string
            enum: [TRANSFER, MINT, DEPLOY]
          description: The operation type, if applicable.
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response with the list of valid SRC-20 transactions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSrc20ResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/tick:
    get:
      operationId: getSrc20TickOperations
      tags:
        - SRC-20
      summary: Get paginated valid SRC-20 transactions by operation type
      description: Retrieve paginated valid SRC-20 transactions by operation type (DEPLOY, MINT, TRANSFER)
      parameters:
        - in: query
          name: op
          schema:
            type: string
            default: "DEPLOY"
            enum: [TRANSFER, MINT, DEPLOY]
          description: The operation type [TRANSFER, MINT, DEPLOY(DEFAULT)]
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Sort"
      responses:
        "200":
          description: Successful response with paginated SRC-20 transactions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSrc20ResponseBody"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/tick/{tick}:
    get:
      operationId: getSrc20TickData
      tags:
        - SRC-20
      summary: Get paginated tick data
      description: Retrieve paginated tick data for a specific tick
      parameters:
        - in: path
          name: tick
          required: true

          example: "KEVIN"
          description: Tick value
          schema:
            type: string
        - in: query
          name: op
          schema:
            type: string
            default: "DEPLOY"
            enum: [TRANSFER, MINT, DEPLOY]
          description: The operation type [TRANSFER, MINT, DEPLOY]
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedTickResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/tick/{tick}/deploy:
    get:
      operationId: getSrc20TickDeployInfo
      tags:
        - SRC-20
      summary: Get deployment details for a specific tick
      description: Retrieve deployment details for a specific tick in the tick API.
      parameters:
        - in: path
          name: tick
          required: true

          example: "KEVIN"
          description: The tick value.
          schema:
            type: string
      responses:
        "200":
          description: Successful response with deployment details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TickResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/tx/{tx_hash}:
    get:
      operationId: getSrc20TransactionInfo
      tags:
        - SRC-20
      summary: Get information about a specific transaction
      description: Retrieves detailed information about a specific SRC-20 transaction by its transaction hash.
      parameters:
        - in: path
          name: tx_hash
          required: true

          example: "9d5451a3ae07a6fe92907cef3c649f52544b8b4e67a6cae848b14e1d8047b5a4"
          schema:
            type: string
          description: The hash of the transaction.
      responses:
        "200":
          description: Successful response with transaction information.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Src20ResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/market:
    get:
      operationId: getSrc20MarketData
      tags:
        - SRC-20
      summary: Get paginated SRC-20 market data
      description: |
        Returns paginated SRC-20 market data from the src20_market_data cache table.
        All data includes USD values calculated from BTC prices and current BTC/USD rate.
        Market data is refreshed periodically from exchange sources.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
        - in: query
          name: sort
          schema:
            type: string
            enum: [market_cap_usd, volume_24h_btc, price_change_24h_percent]
            default: market_cap_usd
          description: Field to sort by
        - in: query
          name: order
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort order (ascending or descending)
      responses:
        "200":
          description: Successful response with paginated market data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SRC20MarketDataRow"
                  total:
                    type: integer
                    description: Total number of tokens with market data
                  page:
                    type: integer
                    description: Current page number
                  limit:
                    type: integer
                    description: Items per page
                  totalPages:
                    type: integer
                    description: Total number of pages
                  last_block:
                    type: integer
                    description: Last indexed block height
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/market/{tick}:
    get:
      operationId: getSrc20MarketDataByTick
      tags:
        - SRC-20
      summary: Get market data for a specific SRC-20 token
      description: |
        Returns market data for a specific SRC-20 token from the src20_market_data cache table.
        Uses case-insensitive tick matching. Returns complete market data including USD values.
        USD values are calculated from BTC prices using current BTC/USD rate.
      parameters:
        - in: path
          name: tick
          required: true
          schema:
            type: string
          description: SRC-20 token tick symbol (case-insensitive)
          example: "KEVIN"
      responses:
        "200":
          description: Successful response with market data for the token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SRC20MarketDataRow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          description: Market data not found for the specified token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseBody"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101:
    get:
      operationId: getSrc101Transactions
      tags:
        - SRC-101
      summary: Get paginated valid SRC-101 transactions
      description: Retrieve paginated valid SRC-101 transactions with optional limit and page parameters
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response with paginated SRC-101 transactions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSrc101ResponseBody"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101/tx:
    get:
      operationId: getSrc101TransactionList
      tags:
        - SRC-101
      summary: Get paginated SRC-101 transactions
      description: Retrieve paginated SRC-101 transactions with optional filtering by block index, operation type, and validation status.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
        - in: query
          name: block_index
          schema:
            type: integer
          description: Filter transactions by block index
        - in: query
          name: op
          schema:
            type: string
            enum: [mint, transfer]
          description: Filter by operation type, either "mint" or "transfer"
        - in: query
          name: deploy_hash
          schema:
            type: string
          description: Filter by deployment transaction hash
        - in: query
          name: valid
          schema:
            type: integer
            enum: [0, 1]
          description: Filter by validation status (1 for valid, 0 for invalid)
      responses:
        "200":
          description: Successful response with paginated SRC-101 transactions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSrc101ResponseBody"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101/tx/{tx_hash}:
    get:
      operationId: getSrc101TransactionByHash
      tags:
        - SRC-101
      summary: Get SRC-101 transaction by hash
      description: Retrieve detailed information about a specific SRC-101 transaction using its transaction hash.
      parameters:
        - in: path
          name: tx_hash
          required: true

          example: "bc1ppwujuuj8ejh4qu5lpfftgmfg3yue7ml7ge8vgzyqzmpu5rc9ttmsrkaeh8"
          schema:
            type: string
          description: The hash of the transaction
      responses:
        "200":
          description: Successful response with transaction details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSrc101ResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101/{deploy_hash}/deploy:
    get:
      operationId: getSrc101DeployInfo
      tags:
        - SRC-101
      summary: Get SRC-101 deployment details
      description: Retrieve comprehensive deployment information for a specific SRC-101 token using its deployment transaction hash.
      parameters:
        - in: path
          name: deploy_hash
          required: true

          example: "77fb147b72a551cf1e2f0b37dccf9982a1c25623a7fe8b4d5efaac566cf63fed"
          schema:
            type: string
          description: The hash of the deploy transaction
      responses:
        "200":
          description: Successful response with deployment details
          content:
            application/json:
              schema:
                type: object
                properties:
                  last_block:
                    type: number
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Src101Detail"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101/{deploy_hash}:
    get:
      operationId: getSrc101Owner
      tags:
        - SRC-101
      summary: Get SRC-101 from owners table
      description: Return all src101 data that matches the rule by filtering
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
        - in: path
          name: deploy_hash
          required: true

          example: "77fb147b72a551cf1e2f0b37dccf9982a1c25623a7fe8b4d5efaac566cf63fed"
          schema:
            type: string
          description: The hash of the deploy transaction
        - in: query
          name: expire
          schema:
            type: integer
          description: 0 is false, 1 is true. false means there are no expired domain names
      responses:
        "200":
          description: Successful response with deployment details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSrc101ResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101/{deploy_hash}/total:
    get:
      operationId: getSrc101TotalSupply
      tags:
        - SRC-101
      summary: Get total supply for SRC-101 token
      description: Retrieve the total supply and related statistics for a specific SRC-101 token using its deployment hash.
      parameters:
        - in: path
          name: deploy_hash
          required: true

          example: "77fb147b72a551cf1e2f0b37dccf9982a1c25623a7fe8b4d5efaac566cf63fed"
          schema:
            type: string
          description: The hash of the deploy transaction
      responses:
        "200":
          description: Successful response with total supply information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TotalSrc101ResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101/{deploy_hash}/address/{address_btc}:
    get:
      operationId: getSrc101TokensByAddress
      tags:
        - SRC-101
      summary: Get tokenid of SRC-101 by address_btc
      description: Retrieve deployment details for a specific deploy_hash in the deploy_hash API.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
        - in: query
          name: prim
          required: true
          example: "false"
          schema:
            type: string
        - in: path
          name: deploy_hash
          required: true

          example: "77fb147b72a551cf1e2f0b37dccf9982a1c25623a7fe8b4d5efaac566cf63fed"
          description: The hash of the deploy transaction.
          schema:
            type: string
        - in: path
          name: address_btc
          required: true

          example: "bc1qhhv6rmxvq5mj2fc3zne2gpjqduy45urapje64m"
          schema:
            type: string
      responses:
        "200":
          description: Successful response with deployment details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenidSrc101ResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101/balance/{address}:
    get:
      operationId: getSrc101AddressBalance
      tags:
        - SRC-101
        - Balance
      summary: Get SRC-101 balances by address
      description: Retrieve all SRC-101 token balances for a specific Bitcoin address, including details about each token held.
      parameters:
        - in: path
          name: address
          required: true

          example: "bc1qhhv6rmxvq5mj2fc3zne2gpjqduy45urapje64m"
          schema:
            type: string
          description: The Bitcoin address to query
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response with address balances
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSrc101BalanceResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101/{deploy_hash}/{tokenid}:
    get:
      operationId: getSrc101TokenInfo
      tags:
        - SRC-101
      summary: Get SRC-101 token information
      description: Retrieve detailed information about a specific SRC-101 token using its deployment hash and token identifier.
      parameters:
        - in: path
          name: deploy_hash
          required: true

          example: "77fb147b72a551cf1e2f0b37dccf9982a1c25623a7fe8b4d5efaac566cf63fed"
          schema:
            type: string
          description: The deployment transaction hash
        - in: path
          name: tokenid
          required: true

          example: "aXJvbmI=="
          schema:
            type: string
          description: The unique token identifier
      responses:
        "200":
          description: Successful response with token information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Src101BalanceResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101/index/{deploy_hash}/{index}:
    get:
      operationId: getSrc101TokenByIndex
      tags:
        - SRC-101
      summary: Get SRC-101 token by index
      description: Retrieve token information using its deployment hash and numeric index. This endpoint provides an alternative way to access token data.
      parameters:
        - in: path
          name: deploy_hash
          required: true

          example: "77fb147b72a551cf1e2f0b37dccf9982a1c25623a7fe8b4d5efaac566cf63fed"
          schema:
            type: string
          description: The deployment transaction hash
        - in: path
          name: index
          required: true

          example: 1
          schema:
            type: number
          description: The numeric index of the token
      responses:
        "200":
          description: Successful response with token information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Src101BalanceResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src101/create:
    post:
      operationId: createSrc101
      tags:
        - SRC-101
      summary: Deploy, Mint, Transfer SRC-101, SetRecord, Renew
      description: |
        This returns a hex encoded serialized PSBT transaction ready for signing and broadcasting
        via wallet or library.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              discriminator:
                propertyName: op
                mapping:
                  deploy: "#/components/schemas/SRC101DeployData"
                  mint: "#/components/schemas/SRC101MintData"
                  transfer: "#/components/schemas/SRC101TransferData"
                  setrecord: "#/components/schemas/SRC101SetRecordData"
                  renew: "#/components/schemas/SRC101RenewData"
            examples:
              deploy:
                summary: Deploy example
                value:
                  sourceAddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  changeAddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  op: "deploy"
                  root: "btc"
                  name: "BitNameService"
                  lim: "10"
                  owner: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  rec: ["bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"]
                  tick: "btc"
                  pri: { 0: 45000, 1: -1, 2: -1, 3: 900000, 4: 225000 }
                  desc: "Bitname Service powered by BTC stamp."
                  mintstart: "0"
                  mintend: "18446744073709551615"
                  wla: "0317ac27154373716ab3bce4f170211446e7598c69ae3a90f058c831c56308323c"
                  imglp: "https://img.bitname.pro/img/"
                  imgf: "png"
                  idua: "999"
                  feeRate: 96
              mint:
                summary: Mint example
                value:
                  sourceAddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  changeAddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  recAddress: "bc1qkt6zxc6dl9xuf2wm8txna2g96yac3spukxvvtk"
                  op: "mint"
                  hash: "77fb147b72a551cf1e2f0b37dccf9982a1c25623a7fe8b4d5efaac566cf63fed"
                  toaddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  tokenid: ["YWJjZGVm"]
                  dua: "999"
                  prim: "true"
                  coef: "1000"
                  sig: ""
                  feeRate: 24
              transfer:
                summary: Transfer example
                value:
                  sourceAddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  changeAddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  tokenid: "YWJjZGVm"
                  op: "transfer"
                  "hash": "77fb147b72a551cf1e2f0b37dccf9982a1c25623a7fe8b4d5efaac566cf63fed"
                  toaddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  tick: "bns"
                  feeRate: 24
              setrecord:
                summary: Set record example
                value:
                  sourceAddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  changeAddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  op: "setrecord"
                  hash: "77fb147b72a551cf1e2f0b37dccf9982a1c25623a7fe8b4d5efaac566cf63fed"
                  tokenid: "YWJjZGVm"
                  type: "address"
                  data: { "btc": "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9" }
                  prim: "true"
                  feeRate: 24
              renew:
                summary: Renew example
                value:
                  sourceAddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  changeAddress: "bc1q7hfpkd39tqe7lske5uyhaj7y2adrjfuaufceu9"
                  recAddress: "bc1qkt6zxc6dl9xuf2wm8txna2g96yac3spukxvvtk"
                  op: "renew"
                  hash: "77fb147b72a551cf1e2f0b37dccf9982a1c25623a7fe8b4d5efaac566cf63fed"
                  tokenid: "YWJjZGVm"
                  dua: "999"
                  feeRate: 24
      responses:
        "200":
          description: Successful response with the hex value.
          content:
            application/json:
              schema:
                type: object
                properties:
                  hex:
                    type: string
                    description: The hex encoded serialized psbt trx
                  base64:
                    type: string
                    description: The base64 encoded serialized psbt trx
                  input_value:
                    type: integer
                    description: The input value in sats
                  total_dust_value:
                    type: integer
                    description: The total dust value in sats
                  est_miner_fee:
                    type: integer
                    description: The estimated miner fee in sats
                  est_tx_size:
                    type: integer
                    description: The estimated transaction size
                  inputsToSign:
                    type: array
                    items:
                      type: string
                      description: The inputs to sign
                  changeAddress:
                    type: string
                    description: The change address
                  fee:
                    type: integer
                    description: The estimated miner fee in sats
                  change:
                    type: integer
                    description: The change value
        "400":
          description: Bad request error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponseBody"

  /api/v2/stamps:
    get:
      operationId: getStamps
      tags:
        - Stamps
      summary: Get paginated stamps with advanced filtering
      description: |
        Retrieve a paginated list of stamps with advanced market data filtering capabilities.
        The new market data filters allow querying based on holder metrics, price ranges,
        volume, and data quality - features enabled by the market data cache system.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Sort"
        # Market Data Filters (Task 42)
        - name: minHolderCount
          in: query
          description: Minimum number of holders for the stamp
          schema:
            type: integer
            minimum: 0
          example: 10
        - name: maxHolderCount
          in: query
          description: Maximum number of holders for the stamp
          schema:
            type: integer
            minimum: 0
          example: 1000
        - name: minDistributionScore
          in: query
          description: Minimum holder distribution score (0-100, higher = more distributed)
          schema:
            type: integer
            minimum: 0
            maximum: 100
          example: 50
        - name: maxTopHolderPercentage
          in: query
          description: Maximum percentage held by top holder (0-100)
          schema:
            type: integer
            minimum: 0
            maximum: 100
          example: 25
        - name: minFloorPriceBTC
          in: query
          description: Minimum floor price in BTC
          schema:
            type: number
            format: float
            minimum: 0
          example: 0.001
        - name: maxFloorPriceBTC
          in: query
          description: Maximum floor price in BTC
          schema:
            type: number
            format: float
            minimum: 0
          example: 1.0
        - name: minVolume24h
          in: query
          description: Minimum 24-hour trading volume in BTC
          schema:
            type: number
            format: float
            minimum: 0
          example: 0.01
        - name: minPriceChange24h
          in: query
          description: Minimum 24-hour price change percentage (can be negative)
          schema:
            type: number
            format: float
          example: -10
        - name: minDataQualityScore
          in: query
          description: Minimum data quality score (0-10, higher = better quality)
          schema:
            type: integer
            minimum: 0
            maximum: 10
          example: 7
        - name: maxCacheAgeMinutes
          in: query
          description: Maximum age of cached market data in minutes
          schema:
            type: integer
            minimum: 0
          example: 60
        - name: priceSource
          in: query
          description: Filter by price data source (comma-separated for multiple)
          schema:
            type: string
          example: "counterparty,openstamp"
      responses:
        "200":
          description: Successful response with paginated stamps.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedStampResponseBody"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/{id}:
    get:
      operationId: getStampById
      tags:
        - Stamps
      summary: Get stamp by ID
      description: Retrieve a specific stamp using its ID (tx_hash, stamp number, or cpid).
      parameters:
        - in: path
          name: id
          required: true

          example: "5faa1aa3012c89b598372153371f835a88739e5539c9c709924ce189fb9c7863"
          description: ID (tx_hash, stamp, cpid) of the stamp
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StampResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/{id}/holders:
    get:
      operationId: getStampHolders
      tags:
        - Stamps
      summary: Get holders for a specific stamp
      description: Retrieve all current holders of a specific stamp.
      parameters:
        - in: path
          name: id
          required: true

          example: "792121"
          schema:
            type: string
          description: Stamp number, cpid, or stamp_hash
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            address:
                              type: string
                            quantity:
                              type: number
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/{id}/dispensers:
    get:
      operationId: getStampDispensersById
      tags:
        - Stamps
        - Dispensers
      summary: Get all dispensers for a specific stamp
      description: Retrieve all dispensers (open and closed) for a specific stamp.
      parameters:
        - in: path
          name: id
          required: true

          example: "792121"
          schema:
            type: string
          description: Stamp number, cpid, or stamp_hash
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/DispenserRow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/dispensers/{address}:
    get:
      operationId: getAddressDispensers
      tags:
        - Stamps
        - Dispensers
      summary: Get all dispensers opened by a wallet address
      description: Retrieve all dispensers (open and closed) opened by a wallet address, each enriched with its stamp metadata.
      parameters:
        - in: path
          name: address
          required: true
          example: "bc1q20d2cdvy2x83h3ssrz5lgryy4c9wqxsgc749ej"
          schema:
            type: string
          description: Bitcoin wallet address
        - in: query
          name: status
          required: false
          schema:
            type: string
            enum:
              - open
              - closed
          description: Filter by dispenser status (omit for all)
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/DispenserRow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/{id}/sends:
    get:
      operationId: getStampSends
      tags:
        - Stamps
      summary: Get send history for a specific stamp
      description: Retrieve the complete transfer history for a specific stamp.
      parameters:
        - in: path
          name: id
          required: true

          example: "792121"
          schema:
            type: string
          description: Stamp number, cpid, or stamp_hash
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            tx_hash:
                              type: string
                            block_index:
                              type: number
                            source:
                              type: string
                            destination:
                              type: string
                            quantity:
                              type: number
                            block_time:
                              type: string
                              format: date-time
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/{id}/dispenses:
    get:
      operationId: getStampDispenses
      tags:
        - Stamps
        - Dispensers
      summary: Get dispense history for a specific stamp
      description: Retrieve the complete dispense history for a specific stamp.
      parameters:
        - in: path
          name: id
          required: true

          example: "792121"
          schema:
            type: string
          description: Stamp number, cpid, or stamp_hash
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/DispenseRow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/balance/{address}:
    get:
      operationId: getStampBalance
      tags:
        - Stamps
        - Balance
      summary: Get stamp balances by address with optional enhanced features
      description: |
        Retrieve all stamp balances for a specific Bitcoin address.
        Use the 'enhanced=true' parameter to enable advanced features including:
        - Market data integration with individual stamp values
        - Advanced sorting options (value, quantity, stamp number, recent activity)
        - Bulk market data optimization for better performance
      parameters:
        - in: path
          name: address
          required: true

          example: "1GotRejB6XsGgMsM79TvcypeanDJRJbMtg"
          description: The address to retrieve stamp balances for
          schema:
            type: string
        - in: query
          name: enhanced
          schema:
            type: boolean
            default: true
          description: Enable enhanced features with market data and advanced sorting
        - in: query
          name: sortBy
          schema:
            type: string
            default: "DESC"
            enum:
              - ASC
              - DESC
              - value_desc
              - value_asc
              - quantity_desc
              - quantity_asc
              - stamp_desc
              - stamp_asc
              - recent_desc
              - recent_asc
          description: Sort order for stamps (requires enhanced=true for advanced options)
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response with stamp balance data
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/PaginatedStampBalanceResponseBody"
                  - $ref: "#/components/schemas/EnhancedStampBalanceResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/block/{block_index}:
    get:
      operationId: getStampsByBlock
      tags:
        - Stamps
      summary: Get stamps by block index
      description: Retrieve all stamps that were created in a specific block.
      parameters:
        - in: path
          name: block_index
          required: true

          example: "779652"
          schema:
            type: string
          description: The index of the block
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StampBlockResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/ident/{ident}:
    get:
      operationId: getStampsByIdent
      tags:
        - Stamps
      summary: Get stamps by ident
      description: Retrieve stamps based on their identifier type (SRC-721, STAMP).
      parameters:
        - in: path
          name: ident
          required: true

          example: "STAMP"
          description: The ident value (SRC-721, STAMP)
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response with the paginated stamps
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedIdResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/recent-sales:
    get:
      operationId: getRecentStampSales
      tags:
        - Stamps
      summary: Get recent stamp sales with enhanced details
      description: |
        Retrieve recent stamp sales (dispenses) with enhanced transaction details and configurable time range.
        This endpoint provides comprehensive information about stamp sales including transaction metadata,
        block information, and optional full transaction details.
      parameters:
        - name: dayRange
          in: query
          description: Number of days to look back for sales (default 7, max 30)
          schema:
            type: integer
            minimum: 1
            maximum: 30
            default: 7
          example: 7
        - name: fullDetails
          in: query
          description: Include full transaction details in response
          schema:
            type: boolean
            default: false
          example: false
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Page"
      responses:
        "200":
          description: Successful response with recent stamp sales
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecentStampSalesResponseBody"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/stamps/search:
    get:
      operationId: searchStamps
      tags:
        - Stamps
      summary: Search stamps by query string
      description: |
        Search for stamps by CPID, stamp number, transaction hash, creator address, or ticker.
        The input is automatically classified and routed to the appropriate query type.
        Returns a simplified result set suitable for search/autocomplete interfaces.
      parameters:
        - name: q
          in: query
          required: true
          description: |
            Search query string. Automatically classified as one of:
            - **cpid**: Matches CPID pattern (e.g., "A1234567890")
            - **stamp_number**: Numeric input interpreted as stamp number
            - **tx_hash**: 64-character hex string matching transaction hash
            - **address**: Bitcoin address (1/3/bc1 prefix)
            - **ticker**: Falls through to generic LIKE search on cpid, creator, and tx_hash
          schema:
            type: string
          example: "KEVIN"
      responses:
        "200":
          description: Successful response with matching stamps
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StampSearchResponseBody"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/src20/create:
    post:
      operationId: createSrc20Token
      tags:
        - Minting
        - SRC-20
      summary: Deploy, Mint, Transfer SRC-20 Tokens
      description: |
        This returns a hex encoded serialized PSBT transaction ready for signing and broadcasting
        via wallet or library.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              discriminator:
                propertyName: op
                mapping:
                  deploy: "#/components/schemas/SRC20DeployData"
                  mint: "#/components/schemas/SRC20MintData"
                  transfer: "#/components/schemas/SRC20TransferData"
            examples:
              deploy:
                summary: Deploy example
                value:
                  toAddress: "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2"
                  changeAddress: "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2"
                  op: "deploy"
                  tick: "APIV2"
                  satsPerVB: 12
                  max: "2100000000"
                  lim: "100000"
                  dec: 18
                  x: "bitcoin_stamps"
                  web: "https://stampchain.io"
                  email: "contact@stampchain.io"
                  tg: "stampchain_official"
                  description: "API Version 2 test token with full metadata"
                  img: "ar:BNttzDav3jHVnNiV7nYbQv-GY0HQ"
                  icon: "ipfs:QmXoypizjW3WknFiJnKLwHCNqzg"
              mint:
                summary: Mint example
                value:
                  toAddress: "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2"
                  changeAddress: "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2"
                  op: "mint"
                  tick: "DOGE"
                  satsPerVB: 20
                  amt: "1000"
              transfer:
                summary: Transfer example
                value:
                  fromAddress: "bc1qdnksce7dgfsehtdxgz6fzdj2k6qfvmyf8uc2vv"
                  toAddress: "bc1qazcm763858nkj2dj986etajv6wquslv8uxwczt"
                  changeAddress: "bc1qdnksce7dgfsehtdxgz6fzdj2k6qfvmyf8uc2vv"
                  op: "transfer"
                  tick: "STAMP"
                  satsPerVB: 20
                  amt: "100000"
      responses:
        "200":
          description: Successful response with the hex value.
          content:
            application/json:
              schema:
                type: object
                properties:
                  hex:
                    type: string
                    description: The hex encoded serialized psbt trx
                  input_value:
                    type: integer
                    description: The input value in sats
                  total_dust_value:
                    type: integer
                    description: The total dust value in sats
                  est_miner_fee:
                    type: integer
                    description: The estimated miner fee in sats
                  est_tx_size:
                    type: integer
                    description: The estimated transaction size
                  inputsToSign:
                    type: array
                    items:
                      type: string
                      description: The inputs to sign
                  changeAddress:
                    type: string
                    description: The change address
                  fee:
                    type: integer
                    description: The estimated miner fee in sats
                  change:
                    type: integer
                    description: The change value
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/trx/stampattach:
    post:
      operationId: attachStampById
      tags:
        - Stamps
      summary: Attach stamp by ID
      description: |
        Creates a PSBT transaction to attach a stamp using its identifier (cpid, stamp number, or tx_hash).
        The stamp will be attached to the specified address. Optionally, a specific UTXO can be specified using inputs_set.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - address
                - identifier
                - quantity
                - options
              properties:
                address:
                  type: string
                  description: The Bitcoin address which owns the stamp
                  example: "bc1q20d2cdvy2x83h3ssrz5lgryy4c9wqxsgc749ej"
                identifier:
                  type: string
                  description: The stamp identifier (cpid, stamp number, or tx_hash)
                  example: "11"
                quantity:
                  type: number
                  description: The quantity of stamps to attach
                  example: 1
                inputs_set:
                  type: string
                  description: Specific UTXO to attach to (txid:vout format)
                  example: "10f8e495a5088dd90a731f4b2657bfb4e94b1f59d3961cbc960900d4e5ba44e5:0"
                options:
                  type: object
                  required:
                    - satsPerVB
                  properties:
                    satsPerVB:
                      type: number
                      description: Fee rate in satoshis per virtual byte
                      example: 20
                    regular_dust_size:
                      type: number
                      description: Override the dust amount for regular outputs (in satoshis)
                      default: 333
                    return_psbt:
                      type: boolean
                      description: Return a PSBT instead of raw transaction
                      default: true
                    verbose:
                      type: boolean
                      description: Include additional transaction details
                      default: true
      responses:
        "200":
          description: Successful response with PSBT transaction
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MintResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/olga/mint:
    post:
      operationId: mintStamp
      tags:
        - Minting
        - Stamps
      summary: Mint a new stamp
      description: Creates a new stamp minting transaction that needs to be signed by the wallet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MintStampInputData"
            examples:
              mint:
                value:
                  sourceWallet: "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2"
                  qty: 1
                  locked: true
                  filename: test.png
                  file: "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgBAMAAACBVGfHAAAAG1BMVEUAAAALOzcKBiAJTzz/1lqZoxgIaSyfQuJmIslgvM+QAAAAAXRSTlMAQObYZgAAAMlJREFUeNp9kNVhAzEMQFVtYE+ge8HfxhsUFkjuFih4gPJ3Jz9mMPuJJVvjzkR0CBJf7CFQB05GKs75EVCwEbAa+3Wg9XmZ5rOz7gljoE9ZmSydzT67lqcdaWrhUCo8m8baKDEt7Qqz4wtVKTVHRI8R2N1bW7wqMb4GLya0KQOYVOUrXfIaHKWY1lsCTfKXyih0msQXeA1td/RoHGOk++8figPKo67o+dqappTnx8FakD2Vxf11QA78F+cZ6cC5BCrd0F+T8UDmIwdjIhoVAu1hnQAAAABJRU5ErkJggg=="
                  satsPerVB: 20
      responses:
        "200":
          description: Successful response with PSBT transaction
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MintResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/trx/stampdetach:
    post:
      operationId: detachStampFromUtxo
      tags:
        - Stamps
        - UTXO
      summary: Detach stamp from UTXO
      description: |
        Creates a PSBT transaction to detach a stamp from a specific UTXO.
        If no destination is provided, the stamp will be detached to the address corresponding to the UTXO.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - utxo
              properties:
                utxo:
                  type: string
                  description: The UTXO from which to detach the stamp
                  example: "10f8e495a5088dd90a731f4b2657bfb4e94b1f59d3961cbc960900d4e5ba44e5:0"
                destination:
                  type: string
                  description: The address to detach the stamp to (optional)
                  example: "bc1qhhv6rmxvq5mj2fc3zne2gpjqduy45urapje64m"
                options:
                  type: object
                  properties:
                    satsPerVB:
                      type: number
                      description: Fee rate in satoshis per virtual byte
                      example: 20
                    regular_dust_size:
                      type: number
                      description: Override the dust amount for regular outputs (in satoshis)
                    multisig_dust_size:
                      type: number
                      description: Override the dust amount for multisig outputs (in satoshis)
                    return_psbt:
                      type: boolean
                      description: Return a PSBT instead of raw transaction
                      default: true
                    verbose:
                      type: boolean
                      description: Include additional transaction details
                      default: true
      responses:
        "200":
          description: Successful response with PSBT transaction
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MintResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/keys:
    post:
      operationId: createApiKey
      tags:
        - API Keys
      summary: Register for a free API key
      description: |
        Creates a new free-tier API key for the given email address.
        Free-tier keys receive 3-5x higher per-minute rate limits than anonymous
        requests and a 50,000 request/day quota.
        Rate-limited to 3 signup attempts per IP per hour.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to associate with the API key
                  example: developer@example.com
      responses:
        "201":
          description: API key created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_key:
                    type: string
                    description: The generated 64-character hex API key
                    example: "a1b2c3d4e5f6..."
                  tier:
                    type: string
                    enum: [free]
                    description: Access tier for the key
                    example: free
                  daily_limit:
                    type: integer
                    description: Maximum requests per day for this tier
                    example: 50000
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          description: Conflict - Email already has an API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: "An API key already exists for this email address."
                code: DUPLICATE_EMAIL
        "429":
          description: Too Many Requests - Signup rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  retryAfter:
                    type: integer
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/v2/keys/usage:
    get:
      operationId: getApiKeyUsage
      tags:
        - API Keys
      summary: Get current API key usage stats
      description: |
        Returns the authenticated key's tier, daily quota, today's usage count,
        and per-endpoint rate limit configuration.
        Requires `X-API-Key` header with a valid registered key.
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: Usage statistics for the authenticated API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  tier:
                    type: string
                    enum: [free, partner]
                    example: free
                  daily_limit:
                    type: integer
                    example: 50000
                  used_today:
                    type: integer
                    example: 1234
                  remaining:
                    type: integer
                    example: 48766
                  rate_limits:
                    type: object
                    description: Per-endpoint rate limit configuration for this tier
                    properties:
                      src20:
                        type: object
                        properties:
                          requests_per_minute:
                            oneOf:
                              - type: integer
                              - type: string
                          requests_per_day:
                            oneOf:
                              - type: integer
                              - type: string
                      stamps:
                        type: object
                        properties:
                          requests_per_minute:
                            oneOf:
                              - type: integer
                              - type: string
                          requests_per_day:
                            oneOf:
                              - type: integer
                              - type: string
                      blocks:
                        type: object
                        properties:
                          requests_per_minute:
                            oneOf:
                              - type: integer
                              - type: string
                          requests_per_day:
                            oneOf:
                              - type: integer
                              - type: string
                      general:
                        type: object
                        properties:
                          requests_per_minute:
                            oneOf:
                              - type: integer
                              - type: string
                          requests_per_day:
                            oneOf:
                              - type: integer
                              - type: string
        "401":
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: "X-API-Key header is required"
        "500":
          $ref: "#/components/responses/InternalServerError"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication

  parameters:
    Limit:
      in: query
      name: limit
      example: 50
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 50
      description: The maximum number of items to return per page. Maximum allowed is 1000.

    Page:
      in: query
      name: page
      example: 1
      schema:
        type: integer
        minimum: 1
      description: The page number to retrieve. Defaults to 1.

    Sort:
      in: query
      name: sort
      example: DESC
      schema:
        type: string
        enum: [ASC, DESC]
      description: The sort order for results. Accepts 'ASC' or 'DESC'.

  schemas:
    Pagination:
      type: object
      properties:
        page:
          type: number
        limit:
          type: number
        totalPages:
          type: number
        total:
          type: number
    SUBPROTOCOLS:
      type: string
      enum:
        - STAMP
        - SRC-20
        - SRC-721
    BlockRow:
      type: object
      properties:
        block_index:
          type: number
        block_hash:
          type: string
        block_time:
          type: string
          format: date-time
        previous_block_hash:
          type: string
        ledger_hash:
          type: string
        txlist_hash:
          type: string
        messages_hash:
          type: string
        tx_count:
          type: number
    DispenseRow:
      type: object
      properties:
        tx_hash:
          type: string
        block_index:
          type: integer
        cpid:
          type: string
        source:
          type: string
        destination:
          type: string
        dispenser_tx_hash:
          type: string
        dispense_quantity:
          type: integer
    DispenserRow:
      type: object
      properties:
        tx_hash:
          type: string
        block_index:
          type: number
        source:
          type: string
        cpid:
          type: string
        give_quantity:
          type: number
        give_remaining:
          type: number
        escrow_quantity:
          type: number
        satoshirate:
          type: number
        btcrate:
          type: number
        origin:
          type: string
        dispenses:
          type: array
          items:
            $ref: "#/components/schemas/DispenseRow"
      required:
        - tx_hash
        - block_index
        - source
        - cpid
        - give_quantity
        - give_remaining
        - escrow_quantity
        - satoshirate
        - btcrate
        - origin
    StampRow:
      type: object
      properties:
        stamp:
          type: number
          nullable: true
        block_index:
          type: number
        cpid:
          type: string
        creator:
          type: string
        divisible:
          type: number
        keyburn:
          type: number
          nullable: true
        locked:
          type: number
        stamp_base64:
          type: string
        stamp_mimetype:
          type: string
        stamp_url:
          type: string
        supply:
          type: number
          nullable: true
        tx_hash:
          type: string
        tx_index:
          type: number
        ident:
          $ref: "#/components/schemas/SUBPROTOCOLS"
        creator_name:
          type: string
          nullable: true
        stamp_hash:
          type: string
        file_hash:
          type: string
        file_size_bytes:
          type: integer
          nullable: true
          description: "Size of the decoded stamp file in bytes"
        floorPrice:
          type: number
          nullable: true
          description: "Current floor price in BTC. Uses lowest open dispenser price, or most recent closed dispenser price if no open dispensers exist"
        floorPriceUSD:
          type: number
          nullable: true
          description: "Floor price converted to USD (floorPrice * BTC/USD rate)"
        marketCapUSD:
          type: number
          nullable: true
          description: "Market capitalization in USD (supply * floorPrice * BTC/USD rate)"
    StampSearchResult:
      type: object
      properties:
        stamp:
          type: number
          nullable: true
          description: "Stamp number"
        cpid:
          type: string
          description: "Counterparty asset ID"
        preview:
          type: string
          description: "URL to stamp preview image"
        mimetype:
          type: string
          description: "MIME type of the stamp content"
        creator:
          type: string
          description: "Creator Bitcoin address"
        tx_hash:
          type: string
          description: "Transaction hash"
    StampSearchResponseBody:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/StampSearchResult"
          description: "Array of matching stamps (max 10 results)"
    StampRowSummary:
      type: object
      properties:
        stamp:
          type: number
          nullable: true
        block_index:
          type: number
        cpid:
          type: string
        creator:
          type: string
        divisible:
          type: number
        keyburn:
          type: number
          nullable: true
        locked:
          type: number
        stamp_base64:
          type: string
        stamp_mimetype:
          type: string
        stamp_url:
          type: string
        supply:
          type: number
          nullable: true
        tx_hash:
          type: string
        tx_index:
          type: number
        ident:
          $ref: "#/components/schemas/SUBPROTOCOLS"
        creator_name:
          type: string
          nullable: true
        stamp_hash:
          type: string
        file_hash:
          type: string
        # NOTE: Root-level price fields removed in v2.3 - use marketData.floorPriceBTC instead
        # floorPrice, floorPriceUSD, marketCapUSD are available in v2.2 only
    BlockStampRow:
      type: object
      properties:
        stamp:
          type: number
          nullable: true
        block_index:
          type: number
        cpid:
          type: string
        creator:
          type: string
        divisible:
          type: number
        keyburn:
          type: number
          nullable: true
        locked:
          type: number
        stamp_base64:
          type: string
        stamp_mimetype:
          type: string
        stamp_url:
          type: string
        supply:
          type: number
          nullable: true
        block_time:
          type: string
          format: date-time
        tx_hash:
          type: string
        tx_index:
          type: number
        ident:
          $ref: "#/components/schemas/SUBPROTOCOLS"
        creator_name:
          type: string
          nullable: true
        stamp_hash:
          type: string
        file_hash:
          type: string
        # NOTE: Root-level price fields removed in v2.3 - use marketData.floorPriceBTC instead
        # NOTE: Fee fields (fee_rate_sat_vb, fee) are only in transaction-specific endpoints, not stamp schemas

    SRC20Balance:
      type: object
      properties:
        address:
          type: string
        p:
          type: string
        tick:
          type: string
        amt:
          type: number
        block_time:
          type: string
          format: date-time
        last_update:
          type: number
          description: "The block index of the last update to the balance"
        deploy_tx:
          type: string
          description: "The tx_hash of the deploy transaction"
          example: "3e3d1b81e06d9f31081da0532ce547b12bc773aad04d645084bbee8d311d6f73"
        deploy_img:
          type: string
          description: "The fully qualified URL to the deploy transaction stamp image (https://stampchain.io/stamps/{deploy_tx}.svg)"
          format: uri
          pattern: "^https://stampchain\\.io/stamps/[a-f0-9]{64}\\.svg$"
          example: "https://stampchain.io/stamps/3e3d1b81e06d9f31081da0532ce547b12bc773aad04d645084bbee8d311d6f73.svg"
        stamp_url:
          type: string
          description: "The fully qualified URL to the transaction stamp content (https://stampchain.io/stamps/{tx_hash}.svg)"
          format: uri
          pattern: "^https://stampchain\\.io/stamps/[a-f0-9]{64}\\.svg$"
          example: "https://stampchain.io/stamps/3e3d1b81e06d9f31081da0532ce547b12bc773aad04d645084bbee8d311d6f73.svg"

    BtcInfo:
      type: object
      properties:
        address:
          type: string
        balance:
          type: number
        txCount:
          type: number
        unconfirmedBalance:
          type: number
        unconfirmedTxCount:
          type: number

    Src20Detail:
      type: object
      properties:
        tx_hash:
          type: string
        block_index:
          type: number
        p:
          type: string
        op:
          type: string
        tick:
          type: string
        creator:
          type: string
        amt:
          type: number
          nullable: true
        deci:
          type: number
        lim:
          type: string
        max:
          type: string
        destination:
          type: string
        block_time:
          type: string
          format: date-time
        creator_name:
          type: string
          nullable: true
        destination_name:
          type: string

        # 🚀 V2.3 CLEAN STRUCTURE: Mint Progress Object
        mint_progress:
          type: object
          nullable: true
          description: "Minting progress information (v2.3+). Contains progress percentage and current/max supply data."
          properties:
            progress:
              type: string
              description: "Minting progress as percentage string (e.g., '75.50')"
              example: "75.50"
            current:
              type: string
              description: "Current total minted amount as string to preserve precision"
              example: "15750000000.000000000000000000"
            max:
              type: string
              description: "Maximum supply as string to preserve precision"
              example: "21000000000.000000000000000000"
            total_mints:
              type: integer
              description: "Total count of MINT transactions for this token (v2.3+)"
              example: 1234

        # 🚀 V2.3 CLEAN STRUCTURE: Market Data Object (for DEPLOY operations)
        market_data:
          type: object
          nullable: true
          description: "Market data information (v2.3+, DEPLOY operations only). Contains pricing, volume, and holder statistics. USD values populated from src20_market_data table."
          properties:
            market_cap_btc:
              type: string
              nullable: true
              description: "Market capitalization in BTC"
              example: "8807.40000000"
            market_cap_usd:
              type: string
              nullable: true
              description: "Market capitalization in USD (calculated from BTC price)"
              example: "528444.00"
            price_btc:
              type: string
              nullable: true
              description: "Current price in BTC"
              example: "0.00041900"
            price_usd:
              type: string
              nullable: true
              description: "Current price in USD (calculated from BTC price)"
              example: "25.14"
            price_source_type:
              type: string
              nullable: true
              description: "Type of price data (v2.3+): 'last_traded' (executed trade), 'floor_ask' (lowest listing), 'composite' (weighted average), 'unknown'"
              enum:
                - last_traded
                - floor_ask
                - composite
                - unknown
              example: "last_traded"
            volume_24h_btc:
              type: string
              nullable: true
              description: "24-hour trading volume in BTC"
            volume_7d_btc:
              type: string
              nullable: true
              description: "7-day trading volume in BTC"
            volume_30d_btc:
              type: string
              nullable: true
              description: "30-day trading volume in BTC"
            change_24h_percent:
              type: string
              nullable: true
              description: "24-hour price change percentage"
            change_7d_percent:
              type: string
              nullable: true
              description: "7-day price change percentage"
            holders:
              type: number
              description: "Number of unique token holders"
              example: 31558
            last_updated:
              type: string
              format: date-time
              description: "Timestamp of last market data update"

        # 📋 V2.2 COMPATIBILITY FIELDS (deprecated in v2.3)
        progress:
          type: string
          nullable: true
          description: "⚠️ DEPRECATED in v2.3: Use mint_progress.progress instead. Minting progress percentage."
        minted_amt:
          type: string
          nullable: true
          description: "⚠️ DEPRECATED in v2.3: Use mint_progress.current instead. Current minted amount."
        holders:
          type: number
          nullable: true
          description: "⚠️ DEPRECATED in v2.3: Use market_data.holders instead. Number of token holders."
        market_cap_btc:
          type: string
          nullable: true
          description: "⚠️ DEPRECATED in v2.3: Use market_data.market_cap_btc instead. Market cap in BTC."
        floor_price_btc:
          type: string
          nullable: true
          description: "⚠️ DEPRECATED in v2.3: Use market_data.floor_price_btc instead. Floor price in BTC."

        # NOTE: Fee fields (fee_rate_sat_vb, fee) are only in transaction-specific endpoints like /api/v2/src20/tx/{tx_hash}, not in general SRC20 or balance schemas
    Src20SnapshotDetail:
      type: object
      properties:
        tick:
          type: string
        address:
          type: string
        balance:
          oneOf:
            - type: number
            - type: string
    SRC101Balance:
      type: object
      properties:
        address:
          type: string
        p:
          type: string
        deploy_hash:
          type: string
        tokenid:
          type: string
        tokenid_utf8:
          type: string
        expire_timestamp:
          type: number
        last_update:
          type: number
        address_btc:
          type: string
        address_eth:
          type: string
        txt_data:
          type: string
        img:
          type: string
    Src101Detail:
      type: object
      properties:
        row_num:
          type: number
        tx_hash:
          type: string
        block_index:
          type: number
        p:
          type: string
        op:
          type: string
        root:
          type: string
        tick:
          type: string
        tick_hash:
          type: string
        name:
          type: string
        tokenid_origin:
          type: string
        tokenid:
          type: string
        tokenid_utf8:
          type: string
        description:
          type: string
        wla:
          type: string
        imglp:
          type: string
        imgf:
          type: string
        deploy_hash:
          type: string
        creator:
          type: string
        pri:
          type: number
        dua:
          type: number
        lim:
          type: number
        coef:
          type: number
        mintstart:
          type: number
          nullable: true
        mintend:
          type: number
          nullable: true
        owner:
          type: string
          nullable: true
        toaddress:
          type: string
          nullable: true
        destination:
          type: string
        destination_nvalue:
          type: string
        block_time:
          type: string
          format: date-time
        status:
          type: string
    StampBalance:
      type: object
      properties:
        stamp:
          type: number
        tx_hash:
          type: string
        stamp_url:
          type: string
        stamp_mimetype:
          type: string
        divisible:
          type: number
        supply:
          type: number
          nullable: true
        locked:
          oneOf:
            - type: number
              nullable: true
            - type: boolean
              nullable: true
        creator:
          type: string
        creator_name:
          type: string
          nullable: true
        balance:
          oneOf:
            - type: number
              nullable: true
            - type: string
              nullable: true
          description: sum of unbound_quantity + quantity in each utxo component
        address:
          type: string
        cpid:
          type: string
        unbounded_quantity:
          type: number
        utxos:
          type: array
          items:
            type: object
            properties:
              utxo:
                type: string
              quantity:
                type: number
    EnhancedStampBalance:
      type: object
      allOf:
        - $ref: "#/components/schemas/StampBalance"
        - type: object
          properties:
            market_data:
              type: object
              oneOf:
                - $ref: "#/components/schemas/SRC20MarketData"
                - $ref: "#/components/schemas/SRC20MarketDataEnhanced"
              nullable: true
              description: Market data structure varies by API version - v2.3 uses enhanced structure with marketDataSources
            recentSalePriceBTC:
              type: number
              nullable: true
              description: "Most recent actual sale price per stamp in BTC. Null indicates no recent sales data available."
            lastPriceBTC:
              type: number
              description: "Best calculated price per stamp in BTC using fallback hierarchy: floorPriceBTC > recentSalePriceBTC > default calculations. This is the recommended price for portfolio calculations."
            walletValueBTC:
              type: number
              description: "Total portfolio value for this stamp (quantity owned × lastPriceBTC). Represents the estimated total BTC worth of all units owned by this wallet."
            openDispensersCount:
              type: number
              description: Count of open dispensers
            holderCount:
              type: number
              description: Number of holders
            volume24hBTC:
              type: number
              nullable: true
              description: 24-hour volume in BTC
            volume7dBTC:
              type: number
              nullable: true
              description: 7-day volume in BTC
            volume30dBTC:
              type: number
              nullable: true
              description: 30-day volume in BTC
            lastUpdated:
              type: string
              format: date-time
              nullable: true
            dataQualityScore:
              type: number
              description: Data quality score (1-10)
    MintStatus:
      type: object
      properties:
        max_supply:
          type: string
        total_minted:
          type: string
        total_mints:
          type: number
        progress:
          type: string
        decimals:
          type: number
        limit:
          oneOf:
            - type: number

    PaginatedStampResponseBody:
      type: object
      allOf:
        - $ref: "#/components/schemas/Pagination"
        - type: object
          properties:
            last_block:
              type: number
            data:
              type: array
              items:
                $ref: "#/components/schemas/StampRowSummary"
    PaginatedStampBalanceResponseBody:
      type: object
      allOf:
        - $ref: "#/components/schemas/Pagination"
        - type: object
          properties:
            last_block:
              type: number
            data:
              type: array
              items:
                $ref: "#/components/schemas/StampBalance"
    EnhancedStampBalanceResponseBody:
      type: object
      allOf:
        - $ref: "#/components/schemas/Pagination"
        - type: object
          properties:
            last_block:
              type: number
            data:
              type: array
              items:
                $ref: "#/components/schemas/EnhancedStampBalance"
            stampValues:
              type: object
              properties:
                stampValues:
                  type: object
                  additionalProperties:
                    type: number
                totalValue:
                  type: number
            metadata:
              type: object
              properties:
                marketDataCacheStatus:
                  type: string
                  enum: [cached, no_data, error]
                enhancedWithMarketData:
                  type: integer
                sortBy:
                  type: string
                sortingMethod:
                  type: string
                  enum: [client, database, none]
    PaginatedSrc20ResponseBody:
      type: object
      allOf:
        - $ref: "#/components/schemas/Pagination"
        - type: object
          properties:
            last_block:
              type: number
            data:
              type: array
              items:
                $ref: "#/components/schemas/Src20Detail"

    TotalSrc101ResponseBody:
      type: object
      properties:
        last_block:
          type: number
        data:
          type: number

    TokenidSrc101ResponseBody:
      type: object
      properties:
        last_block:
          type: number
        data:
          type: string

    PaginatedSrc101ResponseBody:
      type: object
      allOf:
        - $ref: "#/components/schemas/Pagination"
        - type: object
          properties:
            last_block:
              type: number
            data:
              type: array
              items:
                $ref: "#/components/schemas/Src101Detail"
    PaginatedTickResponseBody:
      type: object
      allOf:
        - $ref: "#/components/schemas/Pagination"
        - type: object
          properties:
            last_block:
              type: number
            mint_status:
              $ref: "#/components/schemas/MintStatus"
            data:
              type: array
              items:
                $ref: "#/components/schemas/Src20Detail"
    TickResponseBody:
      type: object
      properties:
        last_block:
          type: number
        mint_status:
          $ref: "#/components/schemas/MintStatus"
        data:
          $ref: "#/components/schemas/Src20Detail"
    Src20ResponseBody:
      type: object
      properties:
        last_block:
          type: number
        data:
          $ref: "#/components/schemas/Src20Detail"
    Src20SnapshotResponseBody:
      type: object
      allOf:
        - $ref: "#/components/schemas/Pagination"
        - type: object
          properties:
            snapshot_block:
              type: number
            data:
              type: array
              items:
                $ref: "#/components/schemas/Src20SnapshotDetail"
    PaginatedSrc20BalanceResponseBody:
      type: object
      properties:
        last_block:
          type: number
        data:
          type: array
          items:
            $ref: "#/components/schemas/SRC20Balance"
    PaginatedSrc20WithMarketDataResponseBody:
      type: object
      properties:
        last_block:
          type: number
        data:
          type: array
          items:
            $ref: "#/components/schemas/SRC20WithMarketData"
    Src20BalanceResponseBody:
      type: object
      properties:
        last_block:
          type: number
        data:
          $ref: "#/components/schemas/SRC20Balance"
    Src101BalanceResponseBody:
      type: object
      properties:
        last_block:
          type: number
        data:
          $ref: "#/components/schemas/SRC101Balance"
    PaginatedSrc101BalanceResponseBody:
      type: object
      properties:
        last_block:
          type: number
        data:
          type: array
          items:
            $ref: "#/components/schemas/SRC101Balance"
    PaginatedBalanceResponseBody:
      type: object
      allOf:
        - $ref: "#/components/schemas/Pagination"
        - type: object
          properties:
            last_block:
              type: number
            btc:
              $ref: "#/components/schemas/BtcInfo"
            data:
              type: object
              properties:
                stamps:
                  type: array
                  items:
                    $ref: "#/components/schemas/StampRow"
                src20:
                  type: array
                  items:
                    $ref: "#/components/schemas/SRC20Balance"
    StampResponseBody:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/StampRow"
        last_block:
          type: number
    PaginatedIdResponseBody:
      type: object
      allOf:
        - $ref: "#/components/schemas/Pagination"
        - type: object
          properties:
            last_block:
              type: number
            ident:
              oneOf:
                - type: string
            data:
              type: array
              items:
                $ref: "#/components/schemas/StampRow"
    BlockInfoResponseBody:
      type: object
      properties:
        block_info:
          $ref: "#/components/schemas/BlockRow"
        data:
          type: array
          items:
            $ref: "#/components/schemas/BlockStampRow"
        last_block:
          type: number
    StampBlockResponseBody:
      type: object
      properties:
        block_info:
          $ref: "#/components/schemas/BlockRow"
        data:
          type: array
          items:
            $ref: "#/components/schemas/BlockStampRow"
        last_block:
          type: number
    SRC20DeployData:
      type: object
      required:
        - toAddress
        - changeAddress
        - op
        - tick
        - max
        - lim
        - dec
      oneOf:
        - required: ["feeRate"]
        - required: ["satsPerVB"]
      properties:
        toAddress:
          type: string
        changeAddress:
          type: string
        op:
          type: string
          enum: ["deploy"]
        tick:
          type: string
        feeRate:
          oneOf:
            - type: number
            - type: string
        satsPerVB:
          oneOf:
            - type: number
            - type: string
        max:
          type: string
          pattern: "^[0-9]+$"
          description: "Maximum supply as numeric string (digits only)"
        lim:
          type: string
          pattern: "^[0-9]+$"
          description: "Limit per mint as numeric string (digits only)"
        dec:
          type: number
          minimum: 0
          maximum: 18
          description: "Number of decimal places (0-18)"
        # Optional metadata fields (database-aligned)
        x:
          type: string
          maxLength: 32
          pattern: "^[a-zA-Z0-9_]{1,32}$"
          description: "Twitter/X username (max 32 chars, alphanumeric and underscore only)"
          example: "bitcoin_stamps"
        web:
          type: string
          maxLength: 255
          pattern: "^https?://[^\\s/$.?#].[^\\s]*$"
          description: "Website URL (max 255 chars)"
          example: "https://stampchain.io"
        email:
          type: string
          maxLength: 255
          pattern: "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
          description: "Contact email address (max 255 chars)"
          example: "contact@stampchain.io"
        tg:
          type: string
          maxLength: 32
          pattern: "^[a-zA-Z0-9_]{1,32}$"
          description: "Telegram handle (max 32 chars, alphanumeric and underscore only)"
          example: "stampchain_official"
        description:
          type: string
          maxLength: 255
          description: "Token description (max 255 chars)"
          example: "A revolutionary token on Bitcoin"
        desc:
          type: string
          maxLength: 255
          description: "Alternative description field (max 255 chars, short form key description)"
          example: "A revolutionary token on Bitcoin"
        img:
          type: string
          maxLength: 32
          pattern: "^(ar|ipfs|fc|ord):[A-Za-z0-9_-]+$"
          description: "Primary image with protocol prefix (max 32 chars). Format: protocol:hash. Supported protocols: ar (Arweave), ipfs (IPFS), fc (Filecoin), ord (Bitcoin Ordinals)"
          example: "ar:BNttzDav3jHVnNiV7nYbQv-GY0HQ"
        icon:
          type: string
          maxLength: 32
          pattern: "^(ar|ipfs|fc|ord):[A-Za-z0-9_-]+$"
          description: "Token icon with protocol prefix (max 32 chars). Format: protocol:hash. Supported protocols: ar (Arweave), ipfs (IPFS), fc (Filecoin), ord (Bitcoin Ordinals)"
          example: "ipfs:QmXoypizjW3WknFiJnKLwHCNqzg"

    SRC20MintData:
      type: object
      required:
        - toAddress
        - changeAddress
        - op
        - tick
        - amt
      oneOf:
        - required: ["feeRate"]
        - required: ["satsPerVB"]
      properties:
        toAddress:
          type: string
        changeAddress:
          type: string
        op:
          type: string
          enum: ["mint"]
        tick:
          type: string
        feeRate:
          oneOf:
            - type: number
            - type: string
        satsPerVB:
          oneOf:
            - type: number
            - type: string
        amt:
          type: string
          pattern: "^[0-9]+$"
          description: "Amount as numeric string (digits only)"

    SRC20TransferData:
      type: object
      required:
        - fromAddress
        - toAddress
        - changeAddress
        - op
        - tick
        - amt
      oneOf:
        - required: ["feeRate"]
        - required: ["satsPerVB"]
      properties:
        fromAddress:
          type: string
        toAddress:
          type: string
        changeAddress:
          type: string
        op:
          type: string
          enum: ["transfer"]
        tick:
          type: string
        feeRate:
          oneOf:
            - type: number
            - type: string
        satsPerVB:
          oneOf:
            - type: number
            - type: string
        amt:
          type: string
          pattern: "^[0-9]+$"
          description: "Amount as numeric string (digits only)"

    MintStampInputData:
      type: object
      required:
        - sourceWallet
        - qty
        - file
      oneOf:
        - required: ["feeRate"]
        - required: ["satsPerVB"]
        - required: ["satsPerKB"]
      properties:
        sourceWallet:
          type: string
          example: "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2"
        assetName:
          type: string
          nullable: true
          example: "My Stamp"
        qty:
          type: number
          example: 1
        locked:
          type: boolean
          example: true
        divisible:
          type: boolean
          default: false
          example: false
        filename:
          type: string
          example: "test.png"
        file:
          type: string
          example: "iVBORw0KGgoAAAANSUhEUgAAA..."
        feeRate:
          type: number
          description: "Fee rate in satoshis per virtual byte / backward compatible"
          example: 20
        satsPerVB:
          oneOf:
            - type: number
            - type: string
          example: 20
        satsPerKB:
          oneOf:
            - type: number
            - type: string
          example: 2000
        service_fee:
          oneOf:
            - type: number
              nullable: true
            - type: string
              nullable: true
          example: 1000
        service_fee_address:
          type: string
          nullable: true
          example: "bc1qxyz..."

    PaginatedCollectionResponseBody:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        totalPages:
          type: integer
        total:
          type: integer
        last_block:
          type: integer
        data:
          type: array
          items:
            $ref: "#/components/schemas/Collection"

    Collection:
      type: object
      properties:
        collection_id:
          type: string
          description: Unique collection identifier (UUID)
        collection_name:
          type: string
          description: Display name of the collection
        collection_description:
          type: string
          description: Description of the collection
        creators:
          type: array
          items:
            type: string
          description: Array of creator addresses
        stamp_count:
          type: integer
          description: Number of stamps in the collection
        total_editions:
          type: number
          description: Total number of editions across all stamps
        img:
          type: string
          nullable: true
          description: Collection image URL
        first_stamp_image:
          type: string
          nullable: true
          description: URL of the first stamp image in the collection
        stamp_images:
          type: array
          items:
            type: string
          description: Array of stamp image URLs
        stamps:
          type: array
          items:
            type: integer
          description: Array of stamp numbers in this collection
        marketData:
          $ref: "#/components/schemas/CollectionMarketData"
          nullable: true
          description: Aggregated market data for the collection from collection_market_data table

    ErrorResponseBody:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        status: # Changed from code to status
          type: integer
          description: HTTP status code
      required:
        - error
        - status
      example:
        error: "Resource not found"
        status: 404

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
      required:
        - error
      example:
        error: "Invalid fee rate"

    MintResponse:
      type: object
      properties:
        hex:
          type: string
          description: The hex encoded serialized psbt transaction
        cpid:
          type: string
          description: The asset name or identifier
        est_tx_size:
          type: integer
          description: Estimated size of the transaction in bytes
        input_value:
          type: integer
          description: Total value of all inputs in satoshis
        total_dust_value:
          type: integer
          description: Total dust value in satoshis
        est_miner_fee:
          type: integer
          description: Estimated miner fee in satoshis
        change_value:
          type: integer
          description: Value returned to change address in satoshis
        txDetails:
          type: array
          description: Array of transaction inputs to sign
          items:
            type: object
            properties:
              txid:
                type: string
                description: Transaction ID of the input
              vout:
                type: integer
                description: Output index in the previous transaction
              signingIndex:
                type: integer
                description: Index for signing this input
            required:
              - txid
              - vout
              - signingIndex
      required:
        - hex
        - cpid
        - est_tx_size
        - input_value
        - total_dust_value
        - est_miner_fee
        - change_value
        - txDetails

    SRC101DeployData:
      type: object
      required:
        - sourceAddress
        - changeAddress
        - op
        - root
        - name
        - lim
        - owner
        - rec
        - tick
        - pri
        - desc
        - mintstart
        - mintend
        - wla
        - imglp
        - imgf
        - idua
        - feeRate
      properties:
        sourceAddress:
          type: string
        changeAddress:
          type: string
        op:
          type: string
          enum: ["deploy"]
        name:
          type: string
        root:
          type: string
        lim:
          type: number
        owner:
          type: string
        rec:
          type: array
        tick:
          type: string
        pri:
          type: object
        desc:
          type: string
        mintstart:
          oneOf:
            - type: number
            - type: string
        mintend:
          oneOf:
            - type: number
            - type: string
        wla:
          type: string
        imglp:
          type: string
        imgf:
          type: string
        idua:
          oneOf:
            - type: number
            - type: string
        feeRate:
          type: number

    SRC101MintData:
      type: object
      required:
        - sourceAddress
        - changeAddress
        - op
        - hash
        - toaddress
        - tokenid
        - dua
        - prim
        - coef
        - sig
        - img
        - feeRate
      properties:
        sourceAddress:
          type: string
        changeAddress:
          type: string
        op:
          type: string
          enum: ["mint"]
        hash:
          type: string
        toaddress:
          type: string
        tokenid:
          type: array
        dua:
          type: number
        prim:
          type: string
        coef:
          type: number
        sig:
          type: string
        img:
          type: array
        feeRate:
          type: number

    SRC101TransferData:
      type: object
      required:
        - sourceAddress
        - changeAddress
        - op
        - hash
        - toaddress
        - tokenid
        - feeRate
      properties:
        sourceAddress:
          type: string
        changeAddress:
          type: string
        op:
          type: string
          enum: ["transfer"]
        hash:
          type: string
        toaddress:
          type: string
        tokenid:
          type: string
        feeRate:
          type: number

    SRC101SetRecordData:
      type: object
      required:
        - sourceAddress
        - changeAddress
        - op
        - hash
        - tokenid
        - type
        - data
        - prim
      properties:
        sourceAddress:
          type: string
        changeAddress:
          type: string
        op:
          type: string
          enum: ["setrecord"]
        hash:
          type: string
        tokenid:
          type: string
        type:
          type: string
        prim:
          type: string
        data:
          type: object
        feeRate:
          type: number

    SRC101RenewData:
      type: object
      required:
        - sourceAddress
        - changeAddress
        - op
        - hash
        - tokenid
        - dua
        - feeRate
      properties:
        sourceAddress:
          type: string
        changeAddress:
          type: string
        op:
          type: string
          enum: ["renew"]
        hash:
          type: string
        tokenid:
          type: string
        dua:
          type: number
        feeRate:
          type: number

    # Market Data Cache Schemas
    StampMarketDataRow:
      type: object
      description: Database row format for stamp market data from stamp_market_data table (snake_case, string decimals)
      required:
        - cpid
        - holder_count
        - unique_holder_count
        - data_quality_score
        - confidence_level
        - last_updated
      properties:
        cpid:
          type: string
          description: Counterparty ID of the stamp
        floor_price_btc:
          type: string
          nullable: true
          description: Floor price in BTC (DECIMAL stored as string for precision)
        recent_sale_price_btc:
          type: string
          nullable: true
          description: Most recent sale price in BTC (DECIMAL stored as string)
        open_dispensers_count:
          type: integer
          description: Number of open dispensers
        closed_dispensers_count:
          type: integer
          description: Number of closed dispensers
        total_dispensers_count:
          type: integer
          description: Total number of dispensers
        holder_count:
          type: integer
          description: Number of addresses holding this stamp
        unique_holder_count:
          type: integer
          description: Number of unique holders (excluding duplicates)
        top_holder_percentage:
          type: string
          description: Percentage held by the top holder (DECIMAL stored as string)
        holder_distribution_score:
          type: string
          description: Distribution score from 0-100 (DECIMAL stored as string)
        volume_24h_btc:
          type: string
          description: 24-hour trading volume in BTC (DECIMAL stored as string)
        volume_7d_btc:
          type: string
          description: 7-day trading volume in BTC (DECIMAL stored as string)
        volume_30d_btc:
          type: string
          description: 30-day trading volume in BTC (DECIMAL stored as string)
        total_volume_btc:
          type: string
          description: All-time trading volume in BTC (DECIMAL stored as string)
        price_source:
          type: string
          nullable: true
          description: Source of the price data
        volume_sources:
          type: string
          nullable: true
          description: JSON string of volume breakdown by source
        data_quality_score:
          type: string
          description: Data quality score from 0-10 (DECIMAL stored as string)
        confidence_level:
          type: string
          description: Confidence level from 0-10 (DECIMAL stored as string)
        last_updated:
          type: string
          format: date-time
          description: Last update timestamp
        last_price_update:
          type: string
          format: date-time
          nullable: true
          description: Last price update timestamp
        update_frequency_minutes:
          type: integer
          description: Update frequency in minutes
        last_sale_tx_hash:
          type: string
          nullable: true
          description: Transaction hash of most recent sale
        last_sale_buyer_address:
          type: string
          nullable: true
          description: Buyer's address from most recent sale
        last_sale_dispenser_address:
          type: string
          nullable: true
          description: Dispenser address used in most recent sale
        last_sale_btc_amount:
          type: string
          nullable: true
          description: Amount in BTC from most recent sale (BIGINT stored as string in satoshis, converted to BTC via / 1e8)
        last_sale_dispenser_tx_hash:
          type: string
          nullable: true
          description: Transaction hash that created the dispenser
        last_sale_block_index:
          type: integer
          nullable: true
          description: Block number of most recent sale
        activity_level:
          type: string
          nullable: true
          enum: [HOT, WARM, COOL, DORMANT, COLD]
          description: Activity level based on trading frequency
        last_activity_time:
          type: integer
          nullable: true
          description: Unix timestamp of last activity

    StampMarketData:
      type: object
      description: Market data for individual stamps from the cache (parsed with proper types)
      properties:
        cpid:
          type: string
          description: Counterparty ID of the stamp
        floorPriceBTC:
          type: number
          nullable: true
          description: Floor price in BTC from dispensers
        recentSalePriceBTC:
          type: number
          nullable: true
          description: Most recent sale price in BTC
        openDispensersCount:
          type: integer
          description: Number of open dispensers
        closedDispensersCount:
          type: integer
          description: Number of closed dispensers
        totalDispensersCount:
          type: integer
          description: Total number of dispensers
        holderCount:
          type: integer
          description: Number of addresses holding this stamp
        uniqueHolderCount:
          type: integer
          description: Number of unique holders (excluding duplicates)
        topHolderPercentage:
          type: number
          description: Percentage held by the top holder
        holderDistributionScore:
          type: number
          description: Distribution score from 0-100
        volume24hBTC:
          type: number
          description: 24-hour trading volume in BTC
        volume7dBTC:
          type: number
          description: 7-day trading volume in BTC
        volume30dBTC:
          type: number
          description: 30-day trading volume in BTC
        totalVolumeBTC:
          type: number
          description: All-time trading volume in BTC
        priceSource:
          type: string
          nullable: true
          description: Source of the price data
        volumeSources:
          type: object
          nullable: true
          description: Breakdown of volume by source
        dataQualityScore:
          type: number
          description: Data quality score from 0-10
        confidenceLevel:
          type: number
          description: Confidence level from 0-10
        lastUpdated:
          type: string
          format: date-time
          description: Last update timestamp
        lastPriceUpdate:
          type: string
          format: date-time
          nullable: true
          description: Last price update timestamp
        updateFrequencyMinutes:
          type: integer
          description: Update frequency in minutes
        lastSaleTxHash:
          type: string
          nullable: true
          description: Transaction hash of most recent sale
        lastSaleBuyerAddress:
          type: string
          nullable: true
          description: Buyer's address from most recent sale
        lastSaleDispenserAddress:
          type: string
          nullable: true
          description: Dispenser address used in most recent sale
        lastSaleBtcAmount:
          type: number
          nullable: true
          description: Amount in BTC from most recent sale (converted from satoshis via BIGINT / 1e8)
        lastSaleDispenserTxHash:
          type: string
          nullable: true
          description: Transaction hash that created the dispenser
        lastSaleBlockIndex:
          type: integer
          nullable: true
          description: Block number of most recent sale
        activityLevel:
          type: string
          nullable: true
          enum: [HOT, WARM, COOL, DORMANT, COLD]
          description: Activity level based on trading frequency
        lastActivityTime:
          type: integer
          nullable: true
          description: Unix timestamp of last activity

    SRC20MarketData:
      type: object
      description: Market data for SRC-20 tokens from the cache
      properties:
        tick:
          type: string
          description: Token ticker symbol
        priceBTC:
          type: number
          nullable: true
          description: Current price in BTC
        priceUSD:
          type: number
          nullable: true
          description: Current price in USD
        floorPriceBTC:
          type: number
          nullable: true
          description: Floor price in BTC
        marketCapBTC:
          type: number
          description: Market capitalization in BTC
        marketCapUSD:
          type: number
          description: Market capitalization in USD
        volume24hBTC:
          type: number
          description: 24-hour trading volume in BTC
        holderCount:
          type: integer
          description: Number of token holders
        circulatingSupply:
          type: string
          description: Circulating supply (string for precision)
        priceChange24hPercent:
          type: number
          description: 24-hour price change percentage
        primaryExchange:
          type: string
          nullable: true
          description: Primary exchange for trading
        exchangeSources:
          type: array
          items:
            type: string
          nullable: true
          description: List of exchange sources
        dataQualityScore:
          type: number
          description: Data quality score from 0-10
        lastUpdated:
          type: string
          format: date-time
          description: Last update timestamp

    SRC20MarketDataRow:
      type: object
      description: Database row format for SRC-20 market data from src20_market_data table (snake_case, string decimals)
      required:
        - tick
        - market_cap_btc
        - market_cap_usd
        - volume_24h_btc
        - holder_count
        - circulating_supply
        - data_quality_score
        - last_updated
      properties:
        tick:
          type: string
          description: Token ticker symbol
        price_btc:
          type: string
          nullable: true
          description: Current price in BTC (DECIMAL stored as string for precision)
        price_usd:
          type: string
          nullable: true
          description: Current price in USD (DECIMAL stored as string for precision)
        floor_price_btc:
          type: string
          nullable: true
          description: Floor price in BTC (DECIMAL stored as string for precision)
        market_cap_btc:
          type: string
          description: Market capitalization in BTC (DECIMAL stored as string)
        market_cap_usd:
          type: string
          description: Market capitalization in USD (DECIMAL stored as string)
        volume_24h_btc:
          type: string
          description: 24-hour trading volume in BTC (DECIMAL stored as string)
        volume_7d_btc:
          type: string
          description: 7-day trading volume in BTC (DECIMAL stored as string)
        volume_30d_btc:
          type: string
          description: 30-day trading volume in BTC (DECIMAL stored as string)
        total_volume_btc:
          type: string
          description: All-time trading volume in BTC (DECIMAL stored as string)
        holder_count:
          type: integer
          description: Number of token holders
        circulating_supply:
          type: string
          description: Circulating supply (DECIMAL stored as string for precision)
        price_change_24h_percent:
          type: string
          description: 24-hour price change percentage (DECIMAL stored as string)
        price_change_7d_percent:
          type: string
          description: 7-day price change percentage (DECIMAL stored as string)
        price_change_30d_percent:
          type: string
          description: 30-day price change percentage (DECIMAL stored as string)
        primary_exchange:
          type: string
          nullable: true
          description: Primary exchange for trading
        exchange_sources:
          type: string
          nullable: true
          description: JSON string array of exchange sources
        data_quality_score:
          type: string
          description: Data quality score from 0-10 (DECIMAL stored as string)
        last_updated:
          type: string
          format: date-time
          description: Last update timestamp

    SRC20MarketDataEnhanced:
      type: object
      description: Enhanced market data for SRC-20 tokens in v2.3 API responses with consistent snake_case naming
      required:
        - tick
        - floor_price_btc
        - market_cap_btc
        - volume_24h_btc
        - holder_count
      properties:
        tick:
          type: string
          description: Token ticker symbol
        floor_price_btc:
          type: number
          description: Floor price per unit in BTC (standardized naming)
        market_cap_btc:
          type: number
          description: Market capitalization in BTC (standardized naming)
        volume_24h_btc:
          type: number
          description: 24-hour trading volume in BTC (standardized naming)
        volume_7d_btc:
          type: number
          description: 7-day trading volume in BTC (standardized naming)
        volume_30d_btc:
          type: number
          description: 30-day trading volume in BTC (standardized naming)
        stamp_url:
          type: string
          nullable: true
          description: Associated stamp URL
        tx_hash:
          type: string
          description: Associated transaction hash (deploy tx for consistency)
        holder_count:
          type: integer
          description: Number of token holders
        market_data_sources:
          type: object
          description: Market data from various exchange sources (consistent snake_case naming)
          properties:
            stampscan:
              type: object
              properties:
                price:
                  type: number
                  description: Price from StampScan
                volume24:
                  type: number
                  description: 24h volume from StampScan
            openstamp:
              type: object
              properties:
                price:
                  type: number
                  description: Price from OpenStamp
                volume24:
                  type: number
                  description: 24h volume from OpenStamp

    CollectionMarketDataRow:
      type: object
      description: Database row format for collection market data from collection_market_data table (snake_case, string decimals)
      required:
        - collection_id
        - last_updated
      properties:
        collection_id:
          type: string
          description: Collection UUID identifier (BINARY(16))
        floor_price_btc:
          type: string
          nullable: true
          description: Floor price in BTC (DECIMAL stored as string)
        avg_price_btc:
          type: string
          nullable: true
          description: Average price in BTC (DECIMAL stored as string)
        total_value_btc:
          type: string
          nullable: true
          description: Total value in BTC (DECIMAL stored as string)
        volume_24h_btc:
          type: string
          description: 24-hour volume in BTC (DECIMAL stored as string)
        volume_7d_btc:
          type: string
          description: 7-day volume in BTC (DECIMAL stored as string)
        volume_30d_btc:
          type: string
          description: 30-day volume in BTC (DECIMAL stored as string)
        total_volume_btc:
          type: string
          description: Total volume in BTC (DECIMAL stored as string)
        total_stamps:
          type: integer
          description: Total number of stamps in collection
        unique_holders:
          type: integer
          description: Total unique holders across collection
        listed_stamps:
          type: integer
          description: Number of stamps currently listed
        sold_stamps_24h:
          type: integer
          description: Number of stamps sold in last 24 hours
        last_updated:
          type: string
          format: date-time
          description: Last update timestamp
        created_at:
          type: string
          format: date-time
          description: Row creation timestamp

    CollectionMarketData:
      type: object
      description: Aggregated market data for collections (parsed with proper types)
      properties:
        collectionId:
          type: string
          description: Collection identifier
        floorPriceBTC:
          type: number
          nullable: true
          description: Floor price in BTC
        avgPriceBTC:
          type: number
          nullable: true
          description: Average price in BTC
        totalValueBTC:
          type: number
          description: Total value in BTC
        volume24hBTC:
          type: number
          description: 24-hour trading volume in BTC
        volume7dBTC:
          type: number
          description: 7-day trading volume in BTC
        volume30dBTC:
          type: number
          description: 30-day trading volume in BTC
        totalVolumeBTC:
          type: number
          description: Total trading volume in BTC
        totalStamps:
          type: integer
          description: Total number of stamps in collection
        uniqueHolders:
          type: integer
          description: Total unique holders across collection
        listedStamps:
          type: integer
          description: Number of stamps currently listed
        soldStamps24h:
          type: integer
          description: Number of stamps sold in last 24 hours
        lastUpdated:
          type: string
          format: date-time
          description: Last update timestamp

    CacheStatus:
      type: string
      enum: [fresh, stale, expired]
      description: Cache status indicator

    MarketDataCacheInfo:
      type: object
      description: Information about cache status
      properties:
        status:
          $ref: "#/components/schemas/CacheStatus"
        ageMinutes:
          type: integer
          description: Age of the cached data in minutes
        nextUpdateIn:
          type: integer
          description: Minutes until next update

    StampWithMarketData:
      allOf:
        - $ref: "#/components/schemas/StampRow"
        - type: object
          properties:
            marketData:
              $ref: "#/components/schemas/StampMarketData"
              nullable: true
            marketDataMessage:
              type: string
              nullable: true
              description: Message when market data is null
            cacheInfo:
              $ref: "#/components/schemas/MarketDataCacheInfo"

    SRC20WithMarketData:
      allOf:
        - $ref: "#/components/schemas/Src20Detail"
        - type: object
          properties:
            marketData:
              type: object
              oneOf:
                - $ref: "#/components/schemas/SRC20MarketData"
                - $ref: "#/components/schemas/SRC20MarketDataEnhanced"
              nullable: true
              description: Market data structure varies by API version - v2.3 uses enhanced structure with marketDataSources
            marketDataMessage:
              type: string
              nullable: true
              description: Message when market data is null
            cacheInfo:
              $ref: "#/components/schemas/MarketDataCacheInfo"

    CollectionWithMarketData:
      allOf:
        - $ref: "#/components/schemas/Collection"
        - type: object
          properties:
            marketData:
              $ref: "#/components/schemas/CollectionMarketData"
              nullable: true
            marketDataMessage:
              type: string
              nullable: true
              description: Message when market data is null
            cacheInfo:
              $ref: "#/components/schemas/MarketDataCacheInfo"

    RecentStampSalesResponseBody:
      type: object
      description: Response body for recent stamp sales
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/EnhancedStampSale"
        pagination:
          $ref: "#/components/schemas/Pagination"
        metadata:
          $ref: "#/components/schemas/RecentSalesMetadata"

    EnhancedStampSale:
      type: object
      description: Enhanced stamp sale information with transaction details
      properties:
        tx_hash:
          type: string
          description: Transaction hash of the sale
        block_index:
          type: integer
          description: Block index where sale occurred
        timestamp:
          type: string
          format: date-time
          description: Transaction timestamp
        cpid:
          type: string
          description: Counterparty ID of the stamp
        stamp_number:
          type: integer
          description: Stamp number
        source:
          type: string
          description: Seller's address
        destination:
          type: string
          description: Buyer's address
        dispenser_tx_hash:
          type: string
          description: Original dispenser transaction hash
        dispense_quantity:
          type: integer
          description: Quantity dispensed
        btc_amount:
          type: number
          description: BTC amount paid
        satoshi_rate:
          type: number
          description: Satoshi rate for the sale
        btc_rate:
          type: number
          description: BTC rate for the sale
        usd_price:
          type: number
          nullable: true
          description: USD price at time of sale
        btc_price_usd:
          type: number
          nullable: true
          description: BTC price in USD at time of sale
        transaction_details:
          $ref: "#/components/schemas/TransactionDetails"
          nullable: true
          description: Full transaction details (when fullDetails=true)

    TransactionDetails:
      type: object
      description: Detailed transaction information
      properties:
        size:
          type: integer
          description: Transaction size in bytes
        weight:
          type: integer
          description: Transaction weight
        fee:
          type: integer
          description: Transaction fee in satoshis
        fee_rate:
          type: number
          description: Fee rate in sat/vB
        input_count:
          type: integer
          description: Number of inputs
        output_count:
          type: integer
          description: Number of outputs
        confirmations:
          type: integer
          description: Number of confirmations
        block_time:
          type: integer
          description: Block timestamp
        block_hash:
          type: string
          description: Block hash

    RecentSalesMetadata:
      type: object
      description: Metadata for recent sales query
      properties:
        day_range:
          type: integer
          description: Number of days queried
        full_details:
          type: boolean
          description: Whether full details were included
        total_sales:
          type: integer
          description: Total number of sales found
        total_volume_btc:
          type: number
          description: Total volume in BTC
        total_volume_usd:
          type: number
          nullable: true
          description: Total volume in USD
        average_price_btc:
          type: number
          description: Average price in BTC
        average_price_usd:
          type: number
          nullable: true
          description: Average price in USD
        unique_stamps:
          type: integer
          description: Number of unique stamps sold
        unique_buyers:
          type: integer
          description: Number of unique buyers
        unique_sellers:
          type: integer
          description: Number of unique sellers
        query_time:
          type: string
          format: date-time
          description: Query execution time
        last_updated:
          type: string
          format: date-time
          description: Last update time

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "Resource not found"
    BadRequest:
      description: Bad Request - Invalid input parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "Invalid request parameters"
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: "Internal server error"