Blockaid Token API
The Token API from Blockaid — 10 operation(s) for token.
OpenAPI Specification
openapi: 3.1.0
info:
title: Blockaid Asset Management Token API
description: Blockaid Risk Score API
termsOfService: https://www.blockaid.io/legal/terms-of-use
license:
name: Proprietary
url: https://www.blockaid.io/legal
version: 1.0.0
servers:
- url: https://api.blockaid.io
description: Production server
- url: https://client.blockaid.io
description: Clients server
tags:
- name: Token
paths:
/v0/token/scan:
post:
tags:
- Token
summary: Scan Token
description: Gets a token address and scan the token to identify any indication of malicious behavior
operationId: scan-token
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TokenValidationRequest'
examples:
Malicious ERC20 Token:
summary: Ethereum - Malicious ERC20 Token
value:
chain: ethereum
address: '0x66587563e933bbf3974b89156b47bb82b921eb35'
Malicious BSC ERC20 Token:
summary: BSC - Malicious ERC20 Token
value:
chain: bsc
address: '0x53da1d6c114d02be5db1c8c37a40a15920f007da'
Benign ERC721 Token:
summary: Ethereum - Benign ERC721 Token
value:
chain: ethereum
address: '0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d'
Malicious ERC721 Token:
summary: Polygon - Malicious ERC721 Token
value:
chain: polygon
address: '0x37f2db133d402d339aaa9202379f15b549077f9a'
Malicious Base Token:
summary: Base - Malicious Token
value:
chain: base
address: '0x7b28085cefd0818e7ed7e8379a20f5cd34d770a7'
Warning ERC20 Token:
summary: BSC - Warning ERC20 Token
value:
chain: bsc
address: '0xcAC0C41a420Fa8AaE94A058E8D328A583F78EE37'
Malicious Impersonator ERC20 Token:
summary: BSC - Impersonator ERC20 Token
value:
chain: bsc
address: '0x53da1d6c114d02be5db1c8c37a40a15920f007da'
Malicious Rugpull Token:
summary: Malicious Rugpull Token
value:
chain: base
address: '0xfb7e4d31e5882826fcca1bf0197ed3c0d91eb3b1'
Malicious Backdoor Token:
summary: Token With Malicious Backdoor
value:
chain: base
address: '0x34b8a376c4547348acc700b751031fed76ed7de9'
Spam Solana Token:
summary: Solana - Unstable Token Price
value:
chain: solana
address: Ftkcs3GywU2jLjDD2WiFXcMCpQEPz3eCWk856uX7pump
Spam Starknet Token:
summary: Starknet - Airdrop Token
value:
chain: starknet
address: '0x005b9282d14bcc3c27c34ba16540d11f8252f9121929eeb3ab04d2b93e5357f8'
Benign Sui Token:
summary: Sui - Benign Token
value:
chain: sui
address: 0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI
Spam Sui Token:
summary: Sui - Spam Token
value:
chain: sui
address: 0x1decfb4bbe641608e970bad1a9cf953d98177f094fb673096f12ed6ebd88a1e8::rnft::TICKET_NFT
Malicious Hedera Token:
summary: Hedera - Malicious Metadata Token
value:
chain: hedera
address: 0.0.7910054
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TokenValidationResponse'
'404':
description: 'Token scan result is not available. This can occur when:
1. The token scan result is not yet available — try again later
2. The address is not a token
3. For cache-only requests: the token has never been scanned (cache miss); a backend rescan is triggered — retry later or wait for webhook updates.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Token scan not available:
summary: Token Scan Result Not Available
value:
detail: Token scan is not available yet. Please try again later.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: false
security:
- APIKey: []
- ClientID: []
/v0/token/report:
post:
tags:
- Token
summary: Report Token
description: Report for misclassification of a token.
operationId: token-report
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReportRequest_TokenReportParams_'
examples:
Token report request_id example:
summary: Token report request_id example
value:
event: FALSE_POSITIVE
report:
type: request_id
request_id: 11111111-1111-1111-1111-111111111111
details: Details about the report
Token report params example:
summary: Token report params example
value:
event: FALSE_POSITIVE
report:
type: params
params:
address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
chain: ethereum
details: Details about the report
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: true
security:
- APIKey: []
- ClientID: []
/v0/token-bulk/scan:
post:
tags:
- Token
summary: Scan Token Bulk
description: Gets a list of token addresses and scan the tokens to identify any indication of malicious behaviour
operationId: scan-token-bulk
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkTokenValidationRequest'
examples:
Ethereum Tokens:
summary: Ethereum - Bulk Tokens
value:
chain: ethereum
tokens:
- '0x66587563e933bbf3974b89156b47bb82b921eb35'
- '0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BulkTokenValidationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: false
security:
- APIKey: []
- ClientID: []
/v0/token/snapshot/full:
get:
tags:
- Token
summary: Full Snapshot
description: 'This endpoint provides a state snapshot of all token scans, allowing you to synchronize with the latest state
Specify your preferred page size to manage response size.
Use the provided cursor to navigate through the pages.
The cursor value will be null on the final page, indicating there are no more results to fetch.
To retrieve the complete data set, iterate through all pages using the cursors provided in the response'
operationId: token-snapshot-full
parameters:
- required: true
deprecated: false
explode: false
schema:
$ref: '#/components/schemas/TokenScanSupportedChains'
name: chain
in: query
allowEmptyValue: false
allowReserved: false
- description: Cursor to start from, if not provided, the first page will be returned
required: false
deprecated: false
explode: false
schema:
anyOf:
- type: string
- type: 'null'
title: Cursor
description: Cursor to start from, if not provided, the first page will be returned
name: cursor
in: query
allowEmptyValue: false
allowReserved: false
- description: Number of tokens to return in a page
required: false
deprecated: false
explode: false
schema:
type: integer
maximum: 5000.0
exclusiveMinimum: 0.0
title: Size
description: Number of tokens to return in a page
default: 50
name: size
in: query
allowEmptyValue: false
allowReserved: false
- description: Filter tokens by type. Allowed values are "Fungible" or "NonFungible". If not provided, all types will be included.
required: false
deprecated: false
explode: false
schema:
anyOf:
- type: string
enum:
- Fungible
- NonFungible
- type: 'null'
title: Token Type
description: Filter tokens by type. Allowed values are "Fungible" or "NonFungible". If not provided, all types will be included.
name: token_type
in: query
allowEmptyValue: false
allowReserved: false
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TokenCursorPage_TokenValidationResponse_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: false
security:
- APIKey: []
- ClientID: []
/v0/token/snapshot/diff:
get:
tags:
- Token
summary: Diff Snapshot
description: 'Retrieve tokens that experienced a state change within the specified timeframe
Specify your preferred page size to manage response size.
Specify the time frame in minutes.
it is recommended to use timeframes shorter than 30 minutes
Use the provided cursor to navigate through the pages.
The cursor value will be null on the final page, indicating there are no more results to fetch.
To retrieve the complete data set, iterate through all pages using the cursors provided in the response'
operationId: token-snapshot-diff
parameters:
- required: true
deprecated: false
explode: false
schema:
$ref: '#/components/schemas/TokenScanSupportedChains'
name: chain
in: query
allowEmptyValue: false
allowReserved: false
- description: Timeframe in minutes
required: false
deprecated: false
explode: false
schema:
type: integer
maximum: 360.0
exclusiveMinimum: 0.0
title: Timeframe
description: Timeframe in minutes
default: 10
name: timeframe
in: query
allowEmptyValue: false
allowReserved: false
- description: Cursor to start from, if not provided, the first page will be returned
required: false
deprecated: false
explode: false
schema:
anyOf:
- type: string
- type: 'null'
title: Cursor
description: Cursor to start from, if not provided, the first page will be returned
name: cursor
in: query
allowEmptyValue: false
allowReserved: false
- description: Number of tokens to return in a page
required: false
deprecated: false
explode: false
schema:
type: integer
maximum: 5000.0
exclusiveMinimum: 0.0
title: Size
description: Number of tokens to return in a page
default: 50
name: size
in: query
allowEmptyValue: false
allowReserved: false
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TokenCursorPage_TokenValidationResponse_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: false
security:
- APIKey: []
- ClientID: []
/v0/token/hooks/{chain}:
get:
tags:
- Token
summary: Get a webhook
description: Get information about an existing webhook for a given chain
operationId: get-hook
parameters:
- required: true
deprecated: false
explode: false
schema:
$ref: '#/components/schemas/TokenScanSupportedChains'
name: chain
in: path
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Hook'
'404':
description: Hook not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: false
security:
- APIKey: []
- ClientID: []
post:
tags:
- Token
summary: Create a new webhook
description: Creates a webhook subscription for a chain to receive real-time token scan updates.
operationId: create-hook
parameters:
- required: true
deprecated: false
explode: false
schema:
$ref: '#/components/schemas/TokenScanSupportedChains'
name: chain
in: path
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HookRequest'
examples:
Create Hook Filter Example:
summary: Create Hook Filter Example
value:
url: https://example.com/
shared_secret_key: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
filter:
filter_type: token_address
token_addresses:
- '0x1234567890abcdef1234567890abcdef12345678'
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/Hook'
'400':
description: Host not reachable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: false
security:
- APIKey: []
- ClientID: []
delete:
tags:
- Token
summary: Delete a webhook
description: Deletes the webhook subscription for a chain and stops further token scan updates.
operationId: delete-hook
parameters:
- required: true
deprecated: false
explode: false
schema:
$ref: '#/components/schemas/TokenScanSupportedChains'
name: chain
in: path
responses:
'204':
description: Successful Response
'404':
description: Hook not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: false
security:
- APIKey: []
- ClientID: []
/v0/token/hooks/:
get:
tags:
- Token
summary: List all webhooks
description: List all active webhook subscriptions across all chains
operationId: list-hooks
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Hook'
type: array
title: Response List-Hooks
deprecated: false
security:
- APIKey: []
- ClientID: []
/v0/token/bulk-export/jobs:
post:
tags:
- Token
summary: Create Export Job
description: Creates an asynchronous job to export token scan data for a chain in the requested format.
operationId: create-bulk-export-job
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkExportJobRequest'
description: Export job request
examples:
Create Export Job Example:
summary: Create Export Job Example
value:
chain: ethereum
token_type: fungible
format: jsonl_gzip
sync_start_time: 0
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BulkExportJobResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: false
security:
- APIKey: []
- ClientID: []
/v0/token/bulk-export/jobs/{job_id}:
get:
tags:
- Token
summary: Get Job Status
description: Retrieves the current status of the job and download URLs when status is `succeeded`.
operationId: get-bulk-export-job-status
parameters:
- description: The ID of an export job you already created.
required: true
deprecated: false
explode: false
schema:
type: string
title: Job Id
description: The ID of an export job you already created.
name: job_id
in: path
responses:
'200':
description: Job status retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BulkExportJobStatusResponse'
examples:
Job Status Running:
summary: Job Status Running
value:
status: running
Job Status Succeeded:
summary: Job Status Succeeded
value:
status: succeeded
files:
- https://s3.amazonaws.com/bucket/path/file1.json.gz?signature=...
- https://s3.amazonaws.com/bucket/path/file2.json.gz?signature=...
expires_in: 86390
chain: ethereum
tokens_count: 150000
'404':
description: Job not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: false
security:
- APIKey: []
- ClientID: []
/v0/token/recent-rugpull-risks:
get:
tags:
- Token
summary: Get Recent Rugpull Risks
description: Returns recently detected pre-dump rugpull-risk token addresses for the requested chain.
operationId: get-recent-rugpull-risks
parameters:
- description: Which chain to look at for recent rugpull tokens.
required: true
deprecated: false
explode: false
schema:
$ref: '#/components/schemas/TokenScanSupportedChains'
description: Which chain to look at for recent rugpull tokens.
name: chain
in: query
allowEmptyValue: false
allowReserved: false
- description: Maximum number of token addresses to return (between 1 and 20)
required: false
deprecated: false
explode: false
schema:
type: integer
maximum: 20
minimum: 1
title: Results Limit
description: Maximum number of token addresses to return (between 1 and 20)
default: 5
name: results_limit
in: query
allowEmptyValue: false
allowReserved: false
responses:
'200':
description: List of token addresses identified as recent rugpull risks
content:
application/json:
schema:
type: array
items:
type: string
title: Response Get-Recent-Rugpull-Risks
examples:
Rugpull Addresses:
summary: List of Rugpull Addresses
value:
- '0xfb7e4d31e5882826fcca1bf0197ed3c0d91eb3b1'
- '0x34b8a376c4547348acc700b751031fed76ed7de9'
'422':
description: Validation Error - Invalid chain or parameters
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: false
security:
- APIKey: []
- ClientID: []
components:
schemas:
AttackType:
properties:
score:
type: string
title: Score
description: Score between 0 to 1 (double) that indicates the assurance this attack happened
threshold:
type: string
title: Threshold
description: If score is higher or equal to this field, the token is using this attack type
default: '1.0'
features:
type: object
title: Features
description: Object contains an extra information related to the attack
type: object
required:
- score
title: AttackType
TokenValidationResponse:
properties:
result_type:
$ref: '#/components/schemas/ResultType'
description: General indication
malicious_score:
type: string
title: Malicious Score
description: Score between 0 to 1 (double)
attack_types:
additionalProperties:
$ref: '#/components/schemas/AttackType'
type: object
title: Attack Types
description: Dictionary of detected attacks found during the scan
chain:
$ref: '#/components/schemas/TokenScanSupportedChains'
description: Blockchain network
address:
type: string
title: Address
description: Token address to validate (EVM / Solana)
metadata:
anyOf:
- $ref: '#/components/schemas/SolanaMetadata'
- $ref: '#/components/schemas/BitcoinMetadataToken'
- $ref: '#/components/schemas/EvmMetadataToken'
title: Metadata
description: Metadata of the token
fees:
$ref: '#/components/schemas/Fees'
description: Fees associated with the token
features:
items:
$ref: '#/components/schemas/Feature'
type: array
title: Features
description: List of features associated with the token
default: []
trading_limits:
$ref: '#/components/schemas/TradingLimits'
description: Trading limits of the token
financial_stats:
$ref: '#/components/schemas/FinancialStats'
description: financial stats of the token
type: object
required:
- result_type
- malicious_score
- attack_types
- chain
- address
- metadata
- fees
- trading_limits
- financial_stats
title: TokenValidationResponse
RequestIDReport:
properties:
type:
type: string
const: request_id
title: Type
description: The type identifier indicating that a request ID from a previous scan is being used.
request_id:
type: string
title: Request Id
description: 'The request ID of a previous request. This can be found in the value of the `x-request-id` field in the headers of the response of the previous request. For instance: `6c3cf6c1-a80d-4927-91b9-03d841ea61fe`.'
type: object
required:
- type
- request_id
title: RequestIDReport
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
BulkTokenValidationRequest:
properties:
metadata:
$ref: '#/components/schemas/TokenMetadata'
description: Optional token metadata context (e.g., source/integration hints) used to enrich results.
default: {}
chain:
$ref: '#/components/schemas/TokenScanSupportedChains'
tokens:
items:
type: string
type: array
title: Tokens
description: A list of token addresses to scan
type: object
required:
- chain
- tokens
title: BulkTokenValidationRequest
BulkScanError:
properties:
message:
$ref: '#/components/schemas/BulkScanErrorType'
description: Error message describing why the scan failed for this token
type: object
required:
- message
title: BulkScanError
TokenReportParams:
properties:
address:
type: string
title: Address
description: The address of the token to report on.
chain:
$ref: '#/components/schemas/TokenScanSupportedChains'
type: object
required:
- address
- chain
title: TokenReportParams
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
TokenMetadata:
properties:
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
description: cross reference transaction against the domain.
type: object
title: TokenMetadata
FinancialStats:
properties:
supply:
anyOf:
- type: integer
- type: 'null'
title: Supply
description: token supply
holders_count:
anyOf:
- type: integer
- type: 'null'
title: Holders Count
description: Amount of token holders
usd_price_per_unit:
anyOf:
- type: number
- type: 'null'
title: Usd Price Per Unit
description: token price in USD
burned_liquidity_percentage:
anyOf:
- type: number
- type: 'null'
title: Burned Liquidity Percentage
description: Token liquidity burned percentage
locked_liquidity_percentage:
anyOf:
- type: number
- type: 'null'
title: Locked Liquidity Percentage
description: Token liquidity locked percentage
top_holders:
items:
$ref: '#/components/schemas/TopHolder'
type: array
title: Top Holders
description: Top token holders
default: []
total_reserve_in_usd:
anyOf:
- type: number
- type: 'null'
title: Total Reserve In Usd
description: Total reserve in USD
dev_holding_percentage:
anyOf:
- type: number
- type: 'null'
title: Dev Holding Percentage
description: Percentage of token's supply held in known developer wallets (0.0 to 100.0)
examples:
- 18.8
initial_snipers_holding_percentage:
anyOf:
- type: number
- type: 'null'
title: Initial Snipers Holding Percentage
description: Percentage of token's supply _currently_ held by sniper bots (0.0 to 100.0). Currently available for Solana only.
examples:
- 18.8
snipers_holding_percentage:
anyOf:
- type: number
- type: 'null'
title: Snipers Holding Percentage
description: Percentage of token's supply _initially_ held by sniper bots (0.0 to 100.0). Currently available for Solana only.
examples:
- 18.8
bundlers_holding_percentage:
anyOf:
- type: number
- type: 'null'
title: Bundlers Holding Percentage
description: Percentage of token currently held by bundlers - wallets that bought in the exact same Solana slot, at any point in the token's life-cycle. Currently available for Solana only.
examples:
- 18.8
insiders_holding_percentage:
anyOf:
- type: number
- type: 'null'
title: Insiders Holding Percentage
description: Percentage of supply that is currently held by insiders - defined as wallets exhibiting early acquisition behaviors typically associated with insider activity.
examples:
- 18.8
markets:
items:
$ref: '#/components/schemas/TokenMarket'
type: array
title: Markets
description: Token markets/pools
type: object
title: FinancialStats
Amount:
properties:
amount:
anyOf:
- type: number
- type: 'null'
title: Amount
description: ''
amount_wei:
anyOf:
- type: string
- type: 'null'
title: Amount Wei
description: ''
type: object
title: Amount
ImpersonationSource:
type: string
enum:
- TOP_TOKEN
- USER_DEFINED
title: ImpersonationSource
description: Source of the impersonation match
SolanaMetadata:
properties:
type:
anyOf:
- type: string
- type: 'null'
title: Type
description: Type of the token
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: Name of the token
symbol:
anyOf:
- type: string
- type: 'null'
title: Symbol
description: Symbol of the token
decimals:
anyOf:
- type: integer
- type: 'null'
title: Decimals
description: Decimals of the token
image_url:
anyOf:
- type: string
- type:
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/blockaid/refs/heads/main/openapi/blockaid-token-api-openapi.yml