Envelop Discover API

openapi: 3.2.0
info:
  title: Fast Discover API
  version: 0.1.0
tags:
- name: Discover
paths:
  /discover/721/user/{chain_id}/{user_address}/{contract_address}:
    get:
      summary: 'Discover 721: user tokens in a collection'
      description: 'List a user''s ERC-721 tokens on a chain, restricted to one collection.


        Same as `/discover/721/user/{chain_id}/{user_address}` but adds a

        `contract_address` filter (`n.contract_address`), so it returns only the

        tokens the user owns in that specific ERC-721 contract.


        Data sources (via `dbconnector.get_tokens_721`, filtered by

        `n.owner = user_address` AND `n.contract_address = contract_address`):

        token rows from `chain_{chain_id}.token_721 n`; `is_wnft` and wNFT unwrap

        fields (`in_contract_address`, `in_token_id`, `in_asset_type`, `rules`)

        from `chain_{chain_id}.wnft_info`; `sale_status` from

        `chain_{chain_id}.current_sale_status`; `kiosk_display` from the SQL

        function `public.get_kiosk_displays(...)`. `filter_blocked=true` excludes

        URIs listed in `public.blacklist_uri`. `asset_type` is the constant `3`.

        NOTE: unlike the no-contract user endpoint, this variant does NOT attach

        `last_sale`. Query: `page`, `size`, `filter_blocked`, `sale_status`.

        Requires an API key.'
      operationId: discover_721_user_by_contract
      security:
      - APIKeyHeader: []
      - JwtAccessBearer: []
      parameters:
      - name: chain_id
        in: path
        required: true
        schema:
          type: integer
          title: Chain Id
      - name: user_address
        in: path
        required: true
        schema:
          type: string
          title: User Address
      - name: contract_address
        in: path
        required: true
        schema:
          type: string
          title: Contract Address
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Size
      - name: filter_blocked
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Filter Blocked
      - name: sale_status
        in: query
        required: false
        schema:
          title: Sale Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Discover
  /discover/721/user/{chain_id}/{user_address}:
    get:
      summary: 'Discover 721: user tokens'
      description: 'List the ERC-721 tokens a user currently owns on a chain (paginated).


        Data sources (via `dbconnector.get_tokens_721`, filtered by

        `n.owner = user_address`): the token rows come from

        `chain_{chain_id}.token_721 n`; `is_wnft` / wNFT unwrap fields

        (`in_contract_address`, `in_token_id`, `in_asset_type`, `rules`) from

        `chain_{chain_id}.wnft_info`; `sale_status` from

        `chain_{chain_id}.current_sale_status`; `kiosk_display` from the SQL

        function `public.get_kiosk_displays(...)` (the showcase the token is

        currently listed on, or NULL). Query: `page`, `size`, `filter_blocked`,

        `sale_status`. Requires an API key.


        Each token also carries `last_sale` — the token''s most recent kiosk sale,

        or `null` if it was never sold on a kiosk. It is the same DB-only record

        that `/kiosk/item_sales` returns (minus the on-chain `paid` field), pulled

        via `dbconnector.get_kiosk_item_sales` (newest first, `LIMIT 1`):

        `public.kiosk_items ki` ⋈ `public.kiosk_displays kd` on

        `kd.id = ki.display_id`, filtered by chain / `contract_address` /

        `token_id` / `status=''sold''`. Fields: `blocknumber`, `logindex`,

        `txhash` (= `ki.sell_tx_hash`), `display_hash` (= `kd.name_hash`),

        `display_name` (= `kd.name`), `sold_at` (SQL

        `public.get_estimate_date_for_block(ki.chain_id, ki.blocknumber)`),

        `prices` (reshaped to `{payWith, amount}`) and `action=''Sold''`.

        Kiosk is EVM-only, so `last_sale` is `null` on non-EVM chains.'
      operationId: discover_721_user
      security:
      - APIKeyHeader: []
      - JwtAccessBearer: []
      parameters:
      - name: chain_id
        in: path
        required: true
        schema:
          type: integer
          title: Chain Id
      - name: user_address
        in: path
        required: true
        schema:
          type: string
          title: User Address
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Size
      - name: filter_blocked
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Filter Blocked
      - name: sale_status
        in: query
        required: false
        schema:
          title: Sale Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Discover
  /discover/721/{chain_id}/{contract_address}/{token_id}:
    get:
      summary: 'Discover 721: single token'
      description: 'Get a single ERC-721 token by chain / contract / token id.


        Each returned token carries the usual discover fields plus `kiosk_display`

        (the named showcase it is listed on, if any) and a `statistics` object

        (currently `{ sales_count }` — how many of this token''s kiosk listings

        ended in a sale).


        Data sources (via `dbconnector.get_tokens_721`, filtered by

        `n.contract_address` AND `n.token_id`; called with

        `with_kiosk_display=True, with_statistics=True`):

        - Token row from `chain_{chain_id}.token_721 n`; `asset_type` = constant `3`.

        - `is_wnft` and wNFT unwrap fields (`in_contract_address`, `in_token_id`,

        `in_asset_type`, `rules`) from `chain_{chain_id}.wnft_info`.

        - `sale_status` = `st.status_id` from `chain_{chain_id}.current_sale_status`.

        - `kiosk_display` from the SQL function `public.get_kiosk_displays(...)`.

        - `statistics.sales_count` from the `with_statistics` subquery: count of

        `public.kiosk_items` rows with `status=''sold''` for this token. A token

        listed on several showcases contributes one per sold listing; a token

        that was never listed gets `0`. Reshaped here into `{ sales_count }`.

        Lazy-mint sales are NOT counted — a lazy purchase mints a fresh

        buyer-owned copy, leaves the template `on_sale`, and emits no kiosk

        event, so nothing in the DB records it.

        Returned as a (0- or 1-element) list. `filter_blocked=true` excludes

        `public.blacklist_uri` URIs. Requires an API key.'
      operationId: discover_721_token
      security:
      - APIKeyHeader: []
      - JwtAccessBearer: []
      parameters:
      - name: chain_id
        in: path
        required: true
        schema:
          type: integer
          title: Chain Id
      - name: contract_address
        in: path
        required: true
        schema:
          type: string
          title: Contract Address
      - name: token_id
        in: path
        required: true
        schema:
          type: string
          title: Token Id
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Size
      - name: filter_blocked
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Filter Blocked
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Discover
  /discover/721/{chain_id}/{contract_address}:
    get:
      summary: 'Discover 721: collection tokens'
      description: 'List all ERC-721 tokens in a collection (contract), regardless of owner.


        Data sources (via `dbconnector.get_tokens_721`, filtered by

        `n.contract_address = contract_address`): token rows from

        `chain_{chain_id}.token_721 n`; `is_wnft` and wNFT unwrap fields

        (`in_contract_address`, `in_token_id`, `in_asset_type`, `rules`) from

        `chain_{chain_id}.wnft_info`; `sale_status` = `st.status_id` from

        `chain_{chain_id}.current_sale_status`. `asset_type` = constant `3`.

        `filter_blocked=true` excludes `public.blacklist_uri` URIs; `sale_status`

        filters on the on-chain sale status. Ordered newest-first

        (`blocknumber, logindex` DESC), paginated.

        NOTE: this variant is called WITHOUT `with_kiosk_display` / `with_statistics`,

        so items carry neither `kiosk_display`, `statistics` nor `last_sale`.

        Query: `page`, `size`, `filter_blocked`, `sale_status`. Requires an API key.'
      operationId: discover_721_collection
      security:
      - APIKeyHeader: []
      - JwtAccessBearer: []
      parameters:
      - name: chain_id
        in: path
        required: true
        schema:
          type: integer
          title: Chain Id
      - name: contract_address
        in: path
        required: true
        schema:
          type: string
          title: Contract Address
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Size
      - name: filter_blocked
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Filter Blocked
      - name: sale_status
        in: query
        required: false
        schema:
          title: Sale Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Discover
  /discover/1155/user/{chain_id}/{user_address}/{contract_address}:
    get:
      summary: 'Discover 1155: user balances in a collection'
      description: 'List a user''s ERC-1155 balances on a chain, restricted to one collection.


        Data sources (via `dbconnector.get_tokens_1155`, filtered by

        `N.owner = user_address` AND `N.contract_address = contract_address`,

        always with `N.balance > 0`):

        - Per-owner balance rows from `chain_{chain_id}.token_1155_balances n`

        (one row per (owner, contract, token_id); `n.balance` is the held amount).

        `asset_type` = constant `4`.

        - `is_wnft` and wNFT unwrap fields (`in_contract_address`, `in_token_id`,

        `in_asset_type`, `rules`) from `chain_{chain_id}.wnft_info`.

        - `totalSupply` from the SQL function

        `chain_{chain_id}.totalsupply1155(contract_address, token_id)`.

        - `sale_status` = `st.status_id` from `chain_{chain_id}.current_sale_status`.

        `filter_blocked=true` excludes `public.blacklist_uri` URIs. ERC-1155 items

        carry no `kiosk_display` / `statistics` / `last_sale` (those are 721-only).

        Query: `page`, `size`, `filter_blocked`, `sale_status`. Requires an API key.'
      operationId: discover_1155_user_by_contract
      security:
      - APIKeyHeader: []
      - JwtAccessBearer: []
      parameters:
      - name: chain_id
        in: path
        required: true
        schema:
          type: integer
          title: Chain Id
      - name: user_address
        in: path
        required: true
        schema:
          type: string
          title: User Address
      - name: contract_address
        in: path
        required: true
        schema:
          type: string
          title: Contract Address
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Size
      - name: filter_blocked
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Filter Blocked
      - name: sale_status
        in: query
        required: false
        schema:
          title: Sale Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Discover
  /discover/1155/user/{chain_id}/{user_address}:
    get:
      summary: 'Discover 1155: user balances'
      description: 'List the ERC-1155 tokens a user currently holds on a chain (paginated).


        Data sources (via `dbconnector.get_tokens_1155`, filtered by

        `N.owner = user_address`, always with `N.balance > 0`): per-owner balance

        rows from `chain_{chain_id}.token_1155_balances n` (`n.balance` = amount

        held); `is_wnft` and wNFT unwrap fields (`in_contract_address`,

        `in_token_id`, `in_asset_type`, `rules`) from `chain_{chain_id}.wnft_info`;

        `totalSupply` from the SQL function

        `chain_{chain_id}.totalsupply1155(contract_address, token_id)`;

        `sale_status` = `st.status_id` from `chain_{chain_id}.current_sale_status`.

        `asset_type` = constant `4`. `filter_blocked=true` excludes

        `public.blacklist_uri` URIs. No `kiosk_display` / `statistics` / `last_sale`

        (721-only). Query: `page`, `size`, `filter_blocked`, `sale_status`.

        Requires an API key.'
      operationId: discover_1155_user
      security:
      - APIKeyHeader: []
      - JwtAccessBearer: []
      parameters:
      - name: chain_id
        in: path
        required: true
        schema:
          type: integer
          title: Chain Id
      - name: user_address
        in: path
        required: true
        schema:
          type: string
          title: User Address
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Size
      - name: filter_blocked
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Filter Blocked
      - name: sale_status
        in: query
        required: false
        schema:
          title: Sale Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Discover
  /discover/1155/{chain_id}/{contract_address}/{token_id}:
    get:
      summary: 'Discover 1155: token holders'
      description: 'List holders/balances of a single ERC-1155 token by chain / contract / id.


        Because `chain_{chain_id}.token_1155_balances` stores one row per owner,

        this returns every current holder of the token (balance > 0), not a single

        record. Data sources (via `dbconnector.get_tokens_1155`, filtered by

        `N.contract_address = contract_address` AND `N.token_id = token_id`):

        balance rows from `chain_{chain_id}.token_1155_balances n` (`n.owner`,

        `n.balance`); `is_wnft` and wNFT unwrap fields from

        `chain_{chain_id}.wnft_info`; `totalSupply` from the SQL function

        `chain_{chain_id}.totalsupply1155(contract_address, token_id)`;

        `sale_status` from `chain_{chain_id}.current_sale_status`. `asset_type` =

        constant `4`. `filter_blocked=true` excludes `public.blacklist_uri` URIs.

        Query: `page`, `size`, `filter_blocked`. Requires an API key.'
      operationId: discover_1155_token
      security:
      - APIKeyHeader: []
      - JwtAccessBearer: []
      parameters:
      - name: chain_id
        in: path
        required: true
        schema:
          type: integer
          title: Chain Id
      - name: contract_address
        in: path
        required: true
        schema:
          type: string
          title: Contract Address
      - name: token_id
        in: path
        required: true
        schema:
          type: string
          title: Token Id
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Size
      - name: filter_blocked
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Filter Blocked
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Discover
  /discover/1155/{chain_id}/{contract_address}:
    get:
      summary: 'Discover 1155: collection balances'
      description: 'List all ERC-1155 balances in a collection (contract), across all holders.


        Data sources (via `dbconnector.get_tokens_1155`, filtered by

        `N.contract_address = contract_address`, always with `N.balance > 0`):

        per-owner balance rows from `chain_{chain_id}.token_1155_balances n`

        (`n.owner`, `n.token_id`, `n.balance`); `is_wnft` and wNFT unwrap fields

        from `chain_{chain_id}.wnft_info`; `totalSupply` from the SQL function

        `chain_{chain_id}.totalsupply1155(contract_address, token_id)`;

        `sale_status` = `st.status_id` from `chain_{chain_id}.current_sale_status`.

        `asset_type` = constant `4`. `filter_blocked=true` excludes

        `public.blacklist_uri` URIs; `sale_status` filters on the on-chain sale

        status. Query: `page`, `size`, `filter_blocked`, `sale_status`.

        Requires an API key.'
      operationId: discover_1155_collection
      security:
      - APIKeyHeader: []
      - JwtAccessBearer: []
      parameters:
      - name: chain_id
        in: path
        required: true
        schema:
          type: integer
          title: Chain Id
      - name: contract_address
        in: path
        required: true
        schema:
          type: string
          title: Contract Address
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Size
      - name: filter_blocked
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Filter Blocked
      - name: sale_status
        in: query
        required: false
        schema:
          title: Sale Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Discover
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization
    JwtAccessBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic