Blockscout Tokens API
The Tokens API from Blockscout — 11 operation(s) for tokens.
OpenAPI Specification
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})$