token_analysis.tokenrisk

Documentation for eth_defi.token_analysis.tokenrisk Python module.

Glider Token Risk API.

Python wrapper for Token Risk API by Hexens, based on Glider
Allows to fetch ERC-20 risk flags and other automatically analysed metadata to determine if a token is some sort of a scam or not
For usage see CachedTokenRisk class
Read Token Risk REST API documentation

Module Attributes

DEFAULT_AVOID_RISKS

List of Token Risk flags we do not want to trade by default

Functions

`has_risk_flags`(data[, avoid_risks])	Check if any of the risk flags are set in Token Risk reply.
`is_tradeable_token`(data[, symbol, ...])	Risk assessment for open-ended trade universe.

Classes

`CachedTokenRisk`	Add file-system based cache for Token Risk API.
`TokenRisk`	Token Risk API.
`TokenRiskFlags`	All evaluated flags are returned, value being true or false.
`TokenRiskReply`	Token Risk JSON payload.
`TokenRiskSmartContractInfo`	Token Risk info about if a smart contract is proxy and verified

Exceptions

TokenRiskError

Wrap bad API replies from Token Risk.

DEFAULT_CACHE_PATH = PosixPath('/home/runner/.cache/tradingstrategy/glide-token-risk.sqlite'): The default location of SQLite cache of Token Risk replies

DEFAULT_AVOID_RISKS = ['risk_balance_manipulation_in_non_standard_functions']: List of Token Risk flags we do not want to trade by default

exception TokenRiskError

Bases: Exception

Wrap bad API replies from Token Risk.

Has attribute status_code

Parameters: status_code – to reflect the HTTP code (e.g. 404 if Token Risk does not have data)

__init__(msg, status_code, address)

Parameters

status_code (int) – to reflect the HTTP code (e.g. 404 if Token Risk does not have data)
msg (str) –
address (str) –

__new__(**kwargs)

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class TokenRiskSmartContractInfo

Bases: TypedDict

Token Risk info about if a smart contract is proxy and verified

__init__(*args, **kwargs)

__new__(**kwargs)

clear() → None. Remove all items from D.

copy() → a shallow copy of D

fromkeys(value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from mapping/iterable E and F.: If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class TokenRiskFlags

Bases: TypedDict

All evaluated flags are returned, value being true or false.

Example:

{
'description': "The token contract's transfer or transferFrom "
                             'functions have a hidden fee functionality that '
                             'can be turned on. This may mean that the '
                             'receiver address can get fewer or a different '
                             'amount of tokens than passed within the transfer '
                             'functions.',
              'key': 'risk_hidden_fees',
              'severity': 'high',
              'sub_title': 'Hidden fee functionality included in transfers',
              'title': 'Hidden fees',
              'value': 'false'}

__init__(*args, **kwargs)

__new__(**kwargs)

clear() → None. Remove all items from D.

copy() → a shallow copy of D

fromkeys(value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from mapping/iterable E and F.: If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class TokenRiskReply

Bases: TypedDict

Token Risk JSON payload.

Example:

{'address': '0x7aaaa5b10f97321345acd76945083141be1c5631',
 'cached': False,
 'cached_at': '2025-08-07T09:00:36.460660',
 'chain_id': '56',
 'data_fetched_at': '2025-08-07T09:00:36.460616',
 'execution_time': 0.001073565,
 'info': {'implementation_address': None,
          'is_proxy': False,
          'is_verified': True,
          'proxy_address': None},
 'market_endorsed': False,
 'results': [{'description': "The token contract's transfer or transferFrom "
                             'functions have a hidden fee functionality that '
                             'can be turned on. This may mean that the '
                             'receiver address can get fewer or a different '
                             'amount of tokens than passed within the transfer '
                             'functions.',
              'key': 'risk_hidden_fees',
              'severity': 'high',
              'sub_title': 'Hidden fee functionality included in transfers',
              'title': 'Hidden fees',
              'value': 'false'},

 ...

 'score': 0}

cached: bool: Added to the response if it was locally cached

data_fetched_at: str: ISO format of the orignal reply caching timestamp

score: int: 0 - 100, but prefer flag checks in results yourself

__init__(*args, **kwargs)

__new__(**kwargs)

clear() → None. Remove all items from D.

copy() → a shallow copy of D

fromkeys(value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from mapping/iterable E and F.: If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class TokenRisk

Bases: object

Token Risk API.

Glider Token Risk API by Hexens.
Intelligent support for API throttling, etc.

Parameters

api_key – From Glider
session – Custom request session object
retries –
Set up retry policy.

Handle API throttling.

Set None to disable retries.

__init__(api_key, session=None, retries=15)

Parameters

api_key (str) – From Glider
session (requests.sessions.Session) – Custom request session object
retries (int | None) –
Set up retry policy.

Handle API throttling.

Set None to disable retries.

fetch_token_info(chain_id, address)

Get Token Risk token data.

This is a synchronous method and may block long time if Token Risk does not have cached results.

https://Token Risk.com/api/v2/tokens/{chain_id}/{address}

Parameters

chain_id (int) – Integer. Example for Ethereum mainnet is 1.
address (Union[str, eth_typing.evm.HexAddress]) – ERC-20 smart contract address.

Returns

Raw Token Risk JSON reply.

Return type

eth_defi.token_analysis.tokenrisk.TokenRiskReply

class CachedTokenRisk

Bases: eth_defi.token_analysis.tokenrisk.TokenRisk

Add file-system based cache for Token Risk API.

Example:

TOKEN_RISK_API_KEY = os.environ.get("TOKEN_RISK_API_KEY")

token_risk = CachedTokenRisk(
    TOKEN_RISK_API_KEY,
)

# COW on BNB Chain
data = token_risk.fetch_token_info(56, "0x7aaaa5b10f97321345acd76945083141be1c5631")

assert data["score"] == 0
assert not is_tradeable_token(data)

You can also pass your custom SQLite file for caching:

path = Path("./cache/token_risk.sqlite")
token_risk = CachedTokenRisk(
    api_key=os.environ["TOKEN_RISK_API_KEY"],
    cache_file=path,
)

Parameters

api_key – Token Risk API key.
session – requests.Session for persistent HTTP connections
cache_file –
Path to a local file system SQLite file used as a cached.

For simple local use cases.
cache –
Direct custom cache interface as a Python dict interface.

For your own database caching.

Cache keys are format: cache_key = f”{chain_id}-{address}”. Cache values are JSON blobs as string.

__init__(api_key, cache_file=PosixPath('/home/runner/.cache/tradingstrategy/glide-token-risk.sqlite'), session=None, cache=None, retries=15)

Parameters

api_key (str) – Token Risk API key.
session (requests.sessions.Session) – requests.Session for persistent HTTP connections
cache_file (pathlib.Path | None) –
Path to a local file system SQLite file used as a cached.

For simple local use cases.
cache (dict | None) –
Direct custom cache interface as a Python dict interface.

For your own database caching.

Cache keys are format: cache_key = f”{chain_id}-{address}”. Cache values are JSON blobs as string.
retries (int | None) –

fetch_token_info(chain_id, address)

Get Token Risk info.

Use local file cache if available.

Returns

Data passed through Token Risk.

A special member cached is set depending on whether the reply was cached or not.

Parameters

chain_id (int) –
address (Union[str, eth_typing.evm.HexAddress]) –

Return type

eth_defi.token_analysis.tokenrisk.TokenRiskReply

get_diagnostics()

Get a diagnostics message.

Use for logging what kind of data we have collected

Example output:

Token sniffer info is:

        Token Risk cache database /Users/moo/.cache/tradingstrategy/Token Risk.sqlite summary:

        Entries: 195
        Max score: 100
        Min score: 0
        Avg score: 56.6

Returns: Multi-line human readable string
Return type: str

has_risk_flags(data, avoid_risks=['risk_balance_manipulation_in_non_standard_functions'])

Check if any of the risk flags are set in Token Risk reply.

Parameters

data (eth_defi.token_analysis.tokenrisk.TokenRiskReply) – Token Risk reply data
avoid_risks (Collection[str]) – List of risk flags to avoid, by their “key” value

Returns

True if any of the risks is set

Return type

bool

is_tradeable_token(data, symbol=None, whitelist={'AAVE', 'DAI', 'ETH', 'FLOKI', 'MKR', 'NEXO', 'PEPE', 'SNX', 'SYN', 'USDC', 'USDS', 'USDT', 'WBNB', 'WBTC', 'WETH', 'cbBTC'}, risk_score_threshold=5, avoid_risks=['risk_balance_manipulation_in_non_standard_functions'])

Risk assessment for open-ended trade universe.

Based on Token Risk reply, determine if we want to trade this token or not

Note

This will alert for USDT/USDC, etc. so be careful.

Parameters

symbol (str | None) – For manual whitelist check.
whitelist –
Always whitelist these if the token symbol matches.

E.g. WBTC needs to be whitelisted, as its risk score is 45.
avoid_risks (Collection[str]) – If any of these risk flags is set, short circuit to zero
risk_score_threshold –
If the risk score is below this, we do not want to trade.

Default is zero, so if the token has any risk flags set, we do not want to trade.

Between 0-100.
data (eth_defi.token_analysis.tokenrisk.TokenRiskReply) –

Returns

True if we want to trade

Return type

bool