openapi: 3.0.0
info:
  description: API for BlockScout web app
  version: 1.0.0
  title: BlockScout Addresses Tokens API
  contact:
    email: support@blockscout.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://eth.blockscout.com/api/v2/
  description: Ethereum mainnet
- url: https://optimism.blockscout.com/api/v2/
  description: Optimism mainnet
- url: https://base.blockscout.com/api/v2/
  description: Base mainnet
- url: https://eth-sepolia.blockscout.com/api/v2/
  description: Ethereum testnet
tags:
- name: Tokens
paths:
  /tokens:
    get:
      summary: get tokens list
      operationId: get_tokens_list
      parameters:
      - in: query
        name: q
        schema:
          type: string
          example: USDT
      - in: query
        name: type
        schema:
          type: string
          example: ERC-20,ERC-721,ERC-1155
      responses:
        '200':
          description: token
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - next_page_params
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TokenInfo'
                  next_page_params:
                    type: object
                    example:
                      contract_address_hash: '0x68749665ff8d2d112fa859aa293f07a622782f38'
                      holders_count: 1011
                      is_name_null: false
                      items_count: 50
                      market_cap: '482534473.2170469'
                      name: Tether Gold
        '400':
          description: bad input parameter
      tags:
      - Tokens
  /tokens/{address_hash}:
    get:
      summary: get token info
      operationId: get_token
      parameters:
      - $ref: '#/components/parameters/addressHash'
      responses:
        '200':
          description: token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenInfo'
        '400':
          description: bad input parameter
      tags:
      - Tokens
  /tokens/{address_hash}/transfers:
    get:
      summary: get token token transfers
      operationId: get_token_token_transfers
      parameters:
      - $ref: '#/components/parameters/addressHash'
      responses:
        '200':
          description: token
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - next_page_params
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TokenTransfer'
                  next_page_params:
                    type: object
                    example:
                      block_number: 27736955
                      index: 61
        '400':
          description: bad input parameter
      tags:
      - Tokens
  /tokens/{address_hash}/holders:
    get:
      summary: get token holders
      operationId: get_token_holders
      parameters:
      - $ref: '#/components/parameters/addressHash'
      responses:
        '200':
          description: token
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - next_page_params
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Holder'
                  next_page_params:
                    type: object
                    example:
                      items_count: 2
                      value: 789999999999999970440
        '400':
          description: bad input parameter
      tags:
      - Tokens
  /tokens/{address_hash}/counters:
    get:
      summary: get token holders
      operationId: get_token_counters
      parameters:
      - $ref: '#/components/parameters/addressHash'
      responses:
        '200':
          description: token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCounters'
        '400':
          description: bad input parameter
      tags:
      - Tokens
  /tokens/{address_hash}/instances:
    get:
      summary: get NFT instances
      operationId: get_nft_instances
      parameters:
      - $ref: '#/components/parameters/addressHash'
      responses:
        '200':
          description: token
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - next_page_params
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/NFTInstance'
                  next_page_params:
                    type: object
                    example:
                      unique_token: 97464
        '400':
          description: bad input parameter
      tags:
      - Tokens
  /tokens/{address_hash}/instances/{id}:
    get:
      summary: get NFT instance by id
      operationId: get_nft_instance
      parameters:
      - $ref: '#/components/parameters/addressHash'
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NFTInstance'
        '400':
          description: bad input parameter
      tags:
      - Tokens
  /tokens/{address_hash}/instances/{id}/transfers:
    get:
      summary: get transfers of NFT instance
      operationId: get_nft_instance_transfers
      parameters:
      - $ref: '#/components/parameters/addressHash'
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: token
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - next_page_params
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TokenTransfer'
                  next_page_params:
                    type: object
                    example:
                      block_number: 27736955
                      index: 61
                      token_id: 50
        '400':
          description: bad input parameter
      tags:
      - Tokens
  /tokens/{address_hash}/instances/{id}/holders:
    get:
      summary: get token instance holders
      operationId: get_token_instance_holders
      parameters:
      - $ref: '#/components/parameters/addressHash'
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: token
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - next_page_params
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Holder'
                  next_page_params:
                    type: object
                    example:
                      value: 789999999999999970440
                      token_id: '953848'
                      items_count: 50
        '400':
          description: bad input parameter
      tags:
      - Tokens
  /tokens/{address_hash}/instances/{id}/transfers-count:
    get:
      summary: get transfers count of NFT instance
      operationId: get_nft_instance_transfers_count
      parameters:
      - $ref: '#/components/parameters/addressHash'
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: token
          content:
            application/json:
              schema:
                type: object
                required:
                - transfers_count
                properties:
                  transfers_count:
                    type: integer
                    example: 10
        '400':
          description: bad input parameter
      tags:
      - Tokens
  /tokens/{address_hash}/instances/{id}/refetch-metadata:
    patch:
      summary: re-fetch token instance metadata
      operationId: refetch_token_instance_metadata
      parameters:
      - $ref: '#/components/parameters/addressHash'
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecaptchaBody'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - next_page_params
                properties:
                  message:
                    type: string
                    example: OK
        '403':
          description: Invalid reCAPTCHA response
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - next_page_params
                properties:
                  message:
                    type: string
                    example: Invalid reCAPTCHA response
      tags:
      - Tokens
components:
  schemas:
    WatchlistName:
      type: object
      required:
      - display_name
      - label
      properties:
        display_name:
          type: string
          example: name to show
        label:
          type: string
          example: label
    TotalERC20:
      required:
      - decimals
      - value
      properties:
        decimals:
          type: string
          example: '18'
        value:
          type: string
          example: '1000'
    TokenInfo:
      type: object
      required:
      - address
      - circulating_market_cap
      - icon_url
      - symbol
      - name
      - decimals
      - type
      - holders
      - exchange_rate
      - total_supply
      properties:
        circulating_market_cap:
          type: string
          example: '83606435600.3635'
        icon_url:
          type: string
          example: https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xdAC17F958D2ee523a2206206994597C13D831ec7/logo.png
        name:
          type: string
          example: Tether USD
        decimals:
          type: string
          example: '6'
        symbol:
          type: string
          example: USDT
        address_hash:
          type: string
          example: '0x394c399dbA25B99Ab7708EdB505d755B3aa29997'
        type:
          type: string
          example: ERC-20
        holders_count:
          type: string
          example: '837494234523'
        exchange_rate:
          type: string
          example: '0.99'
        total_supply:
          type: string
          example: '10000000'
    AddressTag:
      type: object
      required:
      - address_hash
      - display_name
      - label
      properties:
        address_hash:
          type: string
          example: '0xEb533ee5687044E622C69c58B1B12329F56eD9ad'
        display_name:
          type: string
          example: name to show
        label:
          type: string
          example: label
    RecaptchaBody:
      required:
      - recaptcha_response
      properties:
        recaptcha_response:
          type: string
          example: '123'
    Holder:
      required:
      - address
      - value
      - token
      properties:
        address_hash:
          $ref: '#/components/schemas/AddressParam'
        value:
          type: string
          example: '10000'
        token_id:
          type: string
          example: '10000'
    TokenCounters:
      required:
      - token_holders_count
      - transfers_count
      properties:
        token_holders_count:
          type: string
          example: '100'
        transfers_count:
          type: string
          example: '1000'
    TotalERC721:
      required:
      - token_id
      properties:
        token_id:
          type: string
          example: '1'
        token_instance:
          $ref: '#/components/schemas/NFTInstance'
    NFTInstance:
      required:
      - is_unique
      - id
      - token
      - owner
      properties:
        is_unique:
          type: boolean
        id:
          type: string
          example: '431'
        holder_address_hash:
          type: string
          example: '0x394c399dbA25B99Ab7708EdB505d755B3aa29997'
        image_url:
          type: string
          example: example.com/picture.png
        animation_url:
          type: string
          example: example.com/video.mp4
        external_app_url:
          type: string
          example: d-app.com
        metadata:
          type: object
          example:
            year: 2023
            tags:
            - poap
            - event
            name: 'Social Listening Committee #2 Attendees'
            image_url: https://assets.poap.xyz/chanel-poap-4c-2023-logo-1675083420470.png
            home_url: https://app.poap.xyz/token/6292128
            external_url: https://api.poap.tech/metadata/99010/6292128
            description: This is the POAP for attendees of the second Social Listening Committee.
            attributes:
            - value: 01-Feb-2023
              trait_type: startDate
            - value: 01-Feb-2023
              trait_type: endDate
            - value: 'false'
              trait_type: virtualEvent
            - value: Paris
              trait_type: city
            - value: France
              trait_type: country
            - value: https://www.chanel.com
              trait_type: eventURL
        owner:
          $ref: '#/components/schemas/AddressParam'
        token:
          $ref: '#/components/schemas/TokenInfo'
    AddressParam:
      type: object
      required:
      - hash
      - implementation_name
      - is_contract
      - is_verified
      - name
      - private_tags
      - public_tags
      - watchlist_names
      properties:
        hash:
          type: string
          example: '0xEb533ee5687044E622C69c58B1B12329F56eD9ad'
        implementation_name:
          type: string
          example: implementationName
        name:
          type: string
          example: contractName
        ens_domain_name:
          type: string
          example: domain.eth
        metadata:
          type: object
          example:
            slug: tag_slug
            name: Tag name
            tagType: name
            ordinal: 0
            meta: {}
        is_contract:
          type: boolean
        private_tags:
          type: array
          items:
            $ref: '#/components/schemas/AddressTag'
        watchlist_names:
          type: array
          items:
            $ref: '#/components/schemas/WatchlistName'
        public_tags:
          type: array
          items:
            $ref: '#/components/schemas/AddressTag'
        is_verified:
          type: boolean
    TotalERC1155:
      required:
      - token_id
      - decimals
      - value
      properties:
        token_id:
          type: string
          example: '1'
        decimals:
          type: string
          example: null
        value:
          type: string
          example: '1000'
        token_instance:
          $ref: '#/components/schemas/NFTInstance'
    TokenTransfer:
      type: object
      required:
      - block_hash
      - from
      - log_index
      - to
      - token
      - total
      - transaction_hash
      - type
      properties:
        block_hash:
          type: string
          example: '0xf569ec751152b2f814001fc730f7797aa155e4bc3ba9cb6ba24bc2c8c9468c1a'
        from:
          $ref: '#/components/schemas/AddressParam'
        log_index:
          type: integer
          example: 16
        method:
          type: string
          example: transfer
        timestamp:
          type: string
          example: '2023-07-03T20:09:59.000000Z'
        to:
          $ref: '#/components/schemas/AddressParam'
        token:
          $ref: '#/components/schemas/TokenInfo'
        total:
          oneOf:
          - $ref: '#/components/schemas/TotalERC20'
          - $ref: '#/components/schemas/TotalERC721'
          - $ref: '#/components/schemas/TotalERC1155'
        transaction_hash:
          type: string
          example: '0x6662ad1ad2ea899e9e27832dc202fd2ef915a5d2816c1142e6933cff93f7c592'
        type:
          type: string
          example: token_transfer
  parameters:
    id:
      name: id
      schema:
        type: integer
      in: path
      required: true
      description: integer id
    addressHash:
      name: address_hash
      in: path
      description: Address hash
      required: true
      schema:
        type: string
        pattern: ^0x([A-Fa-f0-9]{40})$