openapi: 3.0.3
info:
  title: Deezy API
  description: Deezy Rare Satoshi Circulation and Hunting API
  version: 1.0.0
components:
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: x-api-token
      description: >-
        Your api token. obtain one by emailing support@deezy.io or messaging
        @dannydeezy on telegram. on testnet you can set this to
        `00000000000000000000000000000000` and it will work.
servers:
  - url: https://api.deezy.io
    description: Mainnet
  - url: https://api-testnet.deezy.io
    description: Testnet
paths:
  /v1/sat-hunting/circulation:
    get:
      tags:
        - Sat Circulation
      summary: Get Circulation Data
      description: Get the circulation data of sats
      operationId: getCirculationData
      security:
        - apiToken: []
      parameters:
        - name: rarity
          in: query
          description: >-
            The rarity tag(s) to filter by. Examples: `?rarity=uncommon` or can
            do multiple tags like: `?rarity=uncommon,pizza`. Valid rarities are:
            2009, uncommon, rare, epic, black_uncommon, black_rare, black_epic,
            palindrome, jan2009, vintage, nakamoto, pizza, jpeg, hitman,
            silkroad, alpha, omega, 1_digit, 2_digits, 3_digits,
            perfect_palinception, uniform_palinception, rodarmor, 450x, block_9,
            block_78, block_286, block_666, fibonacci, sequence_palindrome,
            legacy
          required: true
          schema:
            type: string
        - name: trailing_0s
          in: query
          description: >-
            Filter for sats with a specific number of trailing zeroes. Must be
            used with the `uncommon` rarity tag. Example:
            `?rarity=uncommon&trailing_0s=12`
          required: false
          schema:
            type: integer
        - name: trailing_9s
          in: query
          description: >-
            Filter for sats with a specific number of trailing nines. Must be
            used with the `black_uncommon` rarity tag. Example:
            `?rarity=black_uncommon&trailing_9s=11`
          required: false
          schema:
            type: integer
        - name: year_mined
          in: query
          description: >-
            Filter for sats that were mined in a specific year. Example:
            `?rarity=uncommon&year_mined=2010`
          required: false
          schema:
            type: integer
        - name: block
          in: query
          description: >-
            Filter by a specific block. Example:
            `?rarity=perfect_palinception&block=666`
          required: false
          schema:
            type: integer
        - name: block_start
          in: query
          description: >-
            Only search for sats mined at this block height or later. Example:
            `?rarity=perfect_palinception&block_start=10000`. Can be used in
            combination with `block_end`.
          required: false
          schema:
            type: integer
        - name: block_end
          in: query
          description: >-
            Only search for sats mined at this block height or earlier. Example:
            `?rarity=perfect_palinception&block_end=10000`. Can be used in
            combination with `block_start`.
          required: false
          schema:
            type: integer
        - name: time_start
          in: query
          description: >-
            Only search for sats mined after this datetime or later. Example:
            `?rarity=perfect_palinception&time_start=2009-01-01T14:15:22Z` or
            `?rarity=perfect_palinception&time_start=2009-01-01`. Can be used in
            combination with `time_end`.
          required: false
          schema:
            type: string
            format: date-time
        - name: time_end
          in: query
          description: >-
            Only search for sats mined before this datetime or earlier. Example:
            `?rarity=perfect_palinception&time_end=2010-01-01T14:15:22Z` or
            `?rarity=perfect_palinception&time_end=2010-01-01`. Can be used in
            combination with `time_start`.
          required: false
          schema:
            type: string
            format: date-time
        - name: include_top_holders
          in: query
          description: If set to `true` will return a list of the top 500 holders
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Circulation data for the specified rarity tag(s)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      n_total:
                        type: integer
                        description: Total that will ever exist
                      n_mined:
                        type: integer
                        description: Total that have been mined so far
                      n_epoch:
                        type: integer
                        description: >-
                          Total where since block 630,000 (the May 2020 halving)
                          either the sat has moved or its current address has
                          conducted a send
                      n_365:
                        type: integer
                        description: >-
                          Total where in the past 365 days either the sat has
                          moved or its current address has conducted a send
                      n_seq:
                        type: integer
                        description: >-
                          Total that have been sequestered, which we define to
                          be if the sat has been on a UTXO of size 20,000 sats
                          or lower since block 745,855 (the release date of
                          ordinals)
                      n_inscribed:
                        type: integer
                        description: Total that have been inscribed
                      n_seq_holders:
                        type: integer
                        description: >-
                          Total number of distinct addresses that are holding
                          sequestered satoshis of this rarity
                      n_total_holders:
                        type: integer
                        description: >-
                          Total number of distinct addresses that are holding
                          satoshis of this rarity
                      top_seq_holders:
                        type: array
                        description: >-
                          An ordered list of the top holders of sequestered
                          satoshis of this rarity with counts. Only included if
                          `include_top_holders` is set.
                        items:
                          type: object
                          additionalProperties: false
                          properties:
                            address:
                              type: string
                            'n':
                              type: number
                              description: number held
                            max_send_height:
                              type: number
                              description: >-
                                the latest block height in which this address
                                sent something. A value of -1 means the address
                                has never sent funds
                            max_receive_height:
                              type: number
                              description: >-
                                the latest block height in which this address
                                received something
                      top_holders:
                        type: array
                        description: >-
                          An ordered list of the top holders of satoshis of this
                          rarity with counts. Only included if
                          `include_top_holders` is set.
                        items:
                          type: object
                          additionalProperties: false
                          properties:
                            address:
                              type: string
                            'n':
                              type: number
                              description: number held
                            max_send_height:
                              type: number
                              description: >-
                                the latest block height in which this address
                                sent something
                            max_receive_height:
                              type: number
                              description: >-
                                the latest block height in which this address
                                received something
                      updated_at:
                        type: string
                        format: date-time
                        description: Most recent update of the underlying data
        '500':
          description: Internal Server Error
  /v1/sat-hunting/scan:
    post:
      tags:
        - Sat Hunting
      summary: Scan a UTXO or Address for Special Sats
      description: >-
        Initiate a scanning operation to look for special sats in a UTXO or
        address. Either `utxo_to_scan` or `address_to_scan` must be provided.
      operationId: scanUtxoOrAddress
      security:
        - apiToken: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              oneOf:
                - properties:
                    utxo_to_scan:
                      type: string
                      description: The UTXO to scan for special satoshis.
                      example: >-
                        4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b:0
                  required:
                    - utxo_to_scan
                - properties:
                    address_to_scan:
                      type: string
                      description: The address to scan for special satoshis.
                      example: bc1qy3c3vn2pfrmk8t5qt2apqqxx48l80senpfmqqh
                  required:
                    - address_to_scan
              properties:
                extract:
                  type: boolean
                  example: true
                  description: >-
                    Whether to return a PSBT that extracts the special sats to
                    addresses of your choice
                special_sat_addresses:
                  type: array
                  items:
                    type: string
                  example:
                    - >-
                      bc1ptjcfjm8f7gz8umrh0sg3ve8ewq3gm0q9m7khhplny8u7m0nvqf8s0ym0zh
                    - >-
                      bc1ptnadrqyv2862egv6ywanrpllknxw7tks2j9ddlwll9c8ada492cqy67rqd
                    - >-
                      bc1pgfyhzsjmkdtknrh3puzartyxjyztkpm7pfgmuleekj7akksr06lqvmxz8g
                  description: >-
                    List of addresses (taproot preferred) where you'd like the
                    special sats to be sent to. Must provide at least one
                    address if "extract" is true. If there are more special sat
                    outputs than addresses provided, we will re-use the
                    addresses provided as needed.
                regular_funds_addresses:
                  type: array
                  items:
                    type: string
                  example:
                    - >-
                      bc1pdeyrsp2zyevlyenmqv4n240ww9hppf54x4eem5p473lqxh6jepts0wg28y
                    - >-
                      bc1pd7u90a2xvq3nkh4jdtym35uwa8h5xz9xhtcjkj7nj9vdn328hjvsctgu5r
                    - >-
                      bc1p3j5hrnxw7nkc0367pfygggf4pwata98zs7u75jcqp8cxklzak7yq9jfk9z
                  description: >-
                    List of addresses (taproot preferred) where you'd like the
                    regular (non-special) sats sent to. Must provide at least
                    one address if "extract" is true. If there are more regular
                    sat outputs than addresses provided, we will re-use the
                    addresses provided as needed.
                extraction_fee_rate:
                  type: number
                  example: 10
                  description: >-
                    Optional fee rate in sats/vbyte of the extraction
                    transaction. If not provided, we will use the current next
                    block minimum fee rate.
                excluded_tags:
                  type: array
                  items:
                    type: array
                    items:
                      type: string
                  example:
                    - - omega
                      - prime
                    - - omega
                    - - alpha
                      - prime
                    - - alpha
                    - - block_78
                    - - vintage_nakamoto
                    - - pizza
                  description: >-
                    Optional list of tag combinations to exclude from the scan.
                    The default value for the excluded tags, if not provided, is
                    [['omega'], ['alpha'], ['block_78'], ['vintage_nakamoto'],
                    ['pizza']]. To scan the full set of tags, pass an empty
                    array. 
                included_tags:
                  type: array
                  items:
                    type: array
                    items:
                      type: string
                  example:
                    - - omega
                      - prime
                    - - omega
                    - - alpha
                      - prime
                    - - alpha
                    - - block_78
                    - - vintage_nakamoto
                    - - pizza
                  description: >-
                    Optional list of tag combinations to include from the scan.
                    If included_tags is set, it will override excluded_tags
                    settings.
                min_tag_sizes:
                  type: object
                  additionalProperties:
                    type: integer
                  example:
                    block_78: 100
                    vintage_nakamoto: 300
                  description: >-
                    Optional mapping of tag names to their minimum size values
                    for filtering. The key is the tag name and the value is the
                    minimum sat size required for that tag to be extracted.
                max_tag_ages:
                  type: object
                  additionalProperties:
                    type: integer
                    format: int32
                    description: >-
                      The maximum year (inclusive) for the tag to be considered.
                      The tag will be included if it is from this year or
                      earlier.
                  example:
                    alpha: 2009
                    omega: 2010
                  description: >-
                    You can use the optional mapping of tag names to their
                    maximum age values for filtering. This allows you to specify
                    the maximum year for a tag to be considered, and the tag
                    will only be included if it is from that year or earlier.
                    The key should be the tag name, and the value should be the
                    maximum year (inclusive). This is a sub-filter applied
                    before excluded_tags or included_tags.
                tag_limits:
                  type: object
                  additionalProperties:
                    type: integer
                    format: int32
                    description: >-
                      The maximum number of satoshis to be extracted for the
                      tag.
                  example:
                    alpha: 10
                    omega: 15
                  description: >-
                    Optional mapping of tag names to their maximum number of
                    satoshis to be extracted. The key is the tag name and the
                    value is the maximum number of satoshis allowed for that tag
                    to be extracted.
                tag_by_address:
                  type: object
                  additionalProperties:
                    type: string
                  example:
                    uncommon: address123
                    omega: address345
                  description: >-
                    An object mapping rarity tags to Bitcoin addresses. This is
                    used to direct special satoshis identified by their rarity
                    tags to specific addresses. The script will use the first
                    matching tag to determine where to send the sat. The order
                    of the tag:address pairs in your configuration matters. For
                    example, if your configuration is { 'uncommon':
                    'address123', 'omega': 'address345' } and the script finds
                    an uncommon omega sat, it will be sent to 'address123'.
                    However, if your configuration is { 'omega': 'address345',
                    'uncommon': 'address123' }, the sat would be sent to
                    'address345'.


                    Combination of multiple tags is also allowed, ex:  {
                    'omega/block_78': 'address345'}. This will direct bundle to
                    'address345' if it has both omega and block_78 tags.
                split_trigger:
                  type: string
                  example: NEVER
                  description: >-
                    Optional parameter saying when to split the outputs to
                    regular funds addresses into smaller chunks. Options are
                    NEVER (default), NO_SATS (split only when no special sats
                    are found) or ALWAYS (always split). This can be useful to
                    shake up the coin selection of an exchange if they happen to
                    return the same sats to you over and over again. Splitting
                    up the outputs can cause the exchange to give you fresh sats
                    on your next withdrawal.
                split_target_size_sats:
                  type: integer
                  example: 100000000
                  description: >-
                    The target output size of the regular funds outputs when
                    splitting is enabled.
                withdraw_address:
                  type: string
                  example: bc1q2utnxf5d4y2vqmly5w675dqxtgd0fqhnezmq52
                  description: >-
                    Optional parameter saying when to attempt to create an
                    output of withdraw_size_sats amount to the specified address
                    within the extraction PSBT.
                withdraw_size_sats:
                  type: integer
                  example: 100000000
                  description: >-
                    The target output size of the withdrawal output when
                    withdrawal_address is provided.
                split_special_ranges:
                  type: boolean
                  example: false
                  description: >-
                    Whether to split large chunk of sats, if it contains another
                    special sats (subset).

                    Large chunk will be split into: [A, B, CHANGE] or [A, B, A]
                    if sets are valid accordingly to minimum sizes
                    configurations 

                     Ex: you have 5M of block_9 with 600 sats of 450x inside, MIN_TAG_SIZES is 1M for block_9. Enabling this flag will result into outputs of 4.5M block_9, 600 block_9 450x, rest will go to change since remaining is less then 1M.
        required: true
      responses:
        '200':
          description: ID of the scan operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: >-
                      An ID of the scan operation. Use the GET endpoint with
                      this ID to lookup the result. The time to complete the
                      scan depends on the size of the UTXO being scanned and can
                      range from a few seconds to a few minutes.
                    example: 20a27d48e7ae0db029a01b1fd06fd6d8
        '500':
          description: Internal Server Error
  /v1/sat-hunting/scan/{id}:
    get:
      tags:
        - Sat Hunting
      summary: Get Result of UTXO or Address Scan
      description: >-
        It can be used to check the status of a scanning operation, and to
        retrieve the results of a completed scan.
      operationId: getUtxoOrAddressScanResult
      security:
        - apiToken: []
      parameters:
        - name: id
          in: path
          description: >-
            The ID of the scanning operation, as returned from the earlier POST
            request
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rare Sat Info for the Provided UTXO or address
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: >-
                      The status of the scan operation - PENDING, PROCESSING, or
                      COMPLETED
                    example: COMPLETED
                  utxo:
                    type: string
                    description: The UTXO that was scanned for special satoshis
                    example: >-
                      4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b:0
                  address:
                    type: string
                    description: The address that was scanned for special satoshis
                    example: bc1qy3c3vn2pfrmk8t5qt2apqqxx48l80senpfmqqh
                  runes:
                    type: array
                    description: >-
                      A list of Runes identified in the provided UTXO or
                      address. If no Runes were found, this will be an empty
                      array.
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        name:
                          type: string
                          description: The unique name of the Rune
                          example: CUBS•FIRST•RUNES•TOKEN
                        symbol:
                          type: string
                          description: The symbol of the Rune
                          example: R
                        amount:
                          type: number
                          description: The amount of the Rune received
                          example: 100
                        divisibility:
                          type: number
                          description: The divisibility of the Rune received
                          example: 8
                  satributes:
                    type: array
                    description: >-
                      A list of special satoshis identified in the provided UTXO
                      or address. If no special sats were found, this will be an
                      empty array.
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        name:
                          type: string
                          description: The name representation of the sat number
                          example: nuztfvrevcn
                        block:
                          type: number
                          description: The minted block number of the satoshi
                          example: 9
                        epoch:
                          type: number
                          description: The minted epoch number of the satoshi
                          example: 0
                        period:
                          type: number
                          description: The minted period number of the satoshi
                          example: 13
                        cycle:
                          type: number
                          description: The minted cycle number of the satoshi
                          example: 0
                        unique_digits:
                          type: number
                          description: The number of distinct digits in the satoshi number
                          example: 4
                        timestamp:
                          type: string
                          description: The timestamp of the minted block of the satoshi
                          example: '2009-01-17T05:46:32Z'
                        rarity_tags:
                          type: array
                          items:
                            type: string
                          description: The rarities associated with this chunk of satoshis
                          example:
                            - uncommon
                            - vintage
                        inscriptions:
                          type: array
                          items:
                            type: string
                          description: >-
                            The names of the collections for any inscriptions
                            found on the satoshi
                          example:
                            - bitcoin-frogs
                            - bitcoin-punks
                        sat_number:
                          type: number
                          description: >-
                            The ordinal number of the first satoshi in this
                            chunk
                          example: 961435802136035
                        offset:
                          type: number
                          description: The offset in the utxo of this satoshi
                          example: 12002
                        size:
                          type: number
                          description: >-
                            The size of this rarity chunk. (Some special sats
                            arrive in chunks - for example you may find 1000
                            consecutive block-9 sats, in which case the size is
                            1000)
                          example: 1
                  extraction_psbt:
                    type: string
                    description: >-
                      A base64-encoded unsigned PSBT that extracts the special
                      sats to addreses of your choice. Only returned if
                      "extract" is true in the request body. If no special sats
                      were identified, this will be null. WARNING: You should
                      run additional verification locally to check that the fee
                      rate is reasonable and that all outputs are to addresses
                      you control before signing and broadcasting.
                    example: >-
                      cHNidP8BAHECAAAAAeJQY2VLRtutKgQYFUajEKpjFfl0Uyrm6x23OumDpe/4AQAAAAD/////AkxREgEAAAAAFgAUv6pTgbKHN60CZ+RQn5yOuH6c2WiA8PoCAAAAABYAFJDbOFU0E6zFF/M+g/AKDyqI2iUaAAAAAAABAOsCAAAAAAEBbxqXgEf9DlzcqqNM610s5pL1X258ra6+KJ22etb7HAcBAAAAAAAAAAACACT0AAAAAAAiACC7U1W0iJGhQ6o7CexDh5k36V6v3256xpA9/xmB2BybTFZdDQQAAAAAFgAUKp2ThzhswyM2QHlyvmMB6tQB7V0CSDBFAiEA4Md8RIZYqFdUPsgDyomlzMJL9bJ6Ho23JGTihXtEelgCIAeNXRLyt88SOuuWFVn3IodCE4U5D6DojIHesRmikF28ASEDHYFzMEAxfmfq98eSSnZtUwb1w7mAtHG65y8qiRFNnIkAAAAAAQEfVl0NBAAAAAAWABQqnZOHOGzDIzZAeXK+YwHq1AHtXQEDBAEAAAAAAAA=
                  excluded_tags:
                    type: array
                    items:
                      type: array
                      items:
                        type: string
                    example:
                      - - omega
                      - - alpha
                      - - block_78
                      - - vintage_nakamoto
                      - - pizza
                    description: The value used for excluded_tags in the scan.
                  included_tags:
                    type: array
                    items:
                      type: array
                      items:
                        type: string
                    example:
                      - - omega
                      - - alpha
                      - - block_78
                      - - vintage_nakamoto
                      - - pizza
                    description: The value used for included_tags in the scan.
                  min_tag_sizes:
                    type: object
                    additionalProperties:
                      type: integer
                    example:
                      block_78: 100
                      vintage_nakamoto: 300
                    description: The value used for min_tag_sizes in the scan.
                  tag_limits:
                    type: object
                    additionalProperties:
                      type: integer
                    example:
                      alpha: 10
                      omega: 15
                    description: The value used for tag_limits in the scan.
                  tag_by_address:
                    type: object
                    additionalProperties:
                      type: string
                    example:
                      uncommon: address123
                      omega: address345
                    description: The value used for tag_by_address in the scan.
                  split_trigger:
                    type: string
                    example: NEVER
                    description: The value used for split_trigger in the scan.
                  split_target_size_sats:
                    type: integer
                    example: 100000000
                    description: The value used for split_target_size_sats in the scan.
                  withdraw_address:
                    type: string
                    example: bc1q2utnxf5d4y2vqmly5w675dqxtgd0fqhnezmq52
                    description: The value used for withdraw_address in the scan.
                  withdraw_size_sats:
                    type: integer
                    example: 100000000
                    description: The value used for withdraw_size_sats in the scan.
                  withdraw_success:
                    type: boolean
                    example: true
                    description: >-
                      If withdraw_address was provided, denotes if a withdrawal
                      output was sucessfully created.
                  split_special_ranges:
                    type: boolean
                    example: true
                    description: The value used for split_special_ranges in the scan.
        '500':
          description: Internal Server Error
  /v1/sat-hunting/scans:
    get:
      tags:
        - Sat Hunting
      summary: Get status of UTXO Scans
      description: Get the status of scanning operations.
      operationId: getUtxoScans
      security:
        - apiToken: []
      parameters:
        - name: limit
          in: query
          description: The number of requests to return. Defaults to 100.
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: The offset of requests to return. Defaults to 0.
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Scan requests for the Provided API User
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    request_id:
                      type: string
                      description: The request_id for the scan
                      example: 358c7d411b3491cf9ed5d65d984a6415
                    status:
                      type: string
                      description: >-
                        The status of the scan (can be "PENDING", "PROCESSING",
                        or "COMPLETE")
                      example: PENDING
        '500':
          description: Internal Server Error
  /v1/sat-hunting/tags:
    get:
      tags:
        - Sat Hunting
      summary: Get Rarity Tags
      description: >-
        Get list of recognized rarity tags; these values can be used for the
        excluded_tags and included_tags parameters in the scan request.
      operationId: getRarityTags
      security:
        - apiToken: []
      responses:
        '200':
          description: Currently recognized rarity tags for sat scanning
          content:
            application/json:
              schema:
                type: object
                properties:
                  rarity_tags:
                    type: array
                    items:
                      type: string
                    description: Name of each rarity_tag
                    example: mythic
        '500':
          description: Internal Server Error
  /v1/sat-hunting/user/limits:
    get:
      tags:
        - Sat Hunting
      summary: Get User Limits
      description: >-
        This endpoint retrieves the user limits for sat hunting. The user's plan
        allows for a certain amount of BTC every certain number of days, and
        allows purchasing additional volume at a rate of a certain number of
        satoshis per 1 BTC of scan volume. Contact help@deezy.io for questions
        or to change your plan.
      operationId: getUserLimits
      parameters:
        - name: x-api-token
          in: header
          required: true
          description: API token for the user
          schema:
            type: string
      responses:
        '200':
          description: >-
            Success response. Returns the user's limits for sat hunting,
            including the amount limit, unit of the amount, number of days for
            the limit, subscription cost, one-time cost, and user volume.
          content:
            application/json:
              schema:
                type: object
                properties:
                  payment_address:
                    type: string
                    description: Payment address of the user
                    example: 1bc1q...
                  amount:
                    type: number
                    description: Amount limit for the user
                    example: 97666993630
                  unit:
                    type: string
                    description: Unit of the amount, typically 'sats'
                    example: sats
                  days:
                    type: number
                    description: Number of days for the limit
                    example: 30
                  subscription_cost:
                    type: number
                    description: Subscription cost for the user
                    example: 100000000
                  one_time_cost:
                    type: number
                    description: >-
                      Subscription cost for the user in satoshis per 1 BTC of
                      scan volume
                    example: 200000
                  user_volume:
                    type: number
                    description: User consumed volume for the current period
                    example: 97666993631
                  remaining_volume:
                    type: number
                    description: User remaining volume
                    example: 97666993631
        '400':
          description: Bad request response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /v1/sat-hunting/earnings:
    get:
      tags:
        - Sat Hunting
      summary: Get Earnings Summary (DRAFT - not implemented yet)
      description: >-
        Retrieves a summary of earnings based on specified criteria. It allows
        grouping by specific attributes such as year, month, etc., and filtering
        based on the number of days ago.
      operationId: getEarnings
      security:
        - apiToken: []
      parameters:
        - name: group_by
          in: query
          description: >-
            Group the results by a specified attribute. Valid values include:
            'year', 'month', 'epoch', 'period', or 'block'.
          required: false
          schema:
            type: string
        - name: days_ago
          in: query
          description: >-
            Filter the results to include data from the specified number of days
            ago. Defaults to 30 days.
          required: false
          schema:
            type: integer
            default: 30
      responses:
        '200':
          description: >-
            A summary of earnings with optional grouping and time-based
            filtering.
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: array
                    items:
                      type: object
                      properties:
                        rarity_tags:
                          type: array
                          items:
                            type: string
                        count:
                          type: integer
                        group_by_value:
                          type: string
                        floor_price_sats:
                          type: integer
                        total_value_sats:
                          type: integer
                    description: The summary of earnings.
                    example:
                      - rarity_tags:
                          - omega
                        count: 100
                        group_by_value: 2023-03
                        floor_price_sats: 1000
                        total_value_sats: 100000
                      - rarity_tags:
                          - uncommon
                          - block_9
                        count: 1
                        group_by_value: 2009-04
                        floor_price_sats: 250000
                        total_value_sats: 250000
                  group_by:
                    type: string
                    description: The group_by parameter used in the query.
                  days_ago:
                    type: integer
                    description: The days_ago parameter used in the query.
        '500':
          description: Internal Server Error
