token-network

Resolve blockchain networks and tokens by name and get config (contract addresses, decimals, confirmations). All returned objects are Pydantic models (TokenDto, NetworkConfigDto, TokenOnNetworkDto, NetworkDataDto).

Install

pip install token-network

From source:

pip install -e .

Examples

Get a network and its settings

from token_network import network

# By name (callable)
bitcoin = network("bitcoin")

bitcoin.decimal               # 8  (base token decimals)
bitcoin.confirmation_number    # 2  (required confirmations)
bitcoin.wallet_address_regex   # wallet validation regex for this network
bitcoin.approximate_confirmation_time # 1200  (approx. seconds to confirm)
bitcoin.config                # NetworkConfigDto (Pydantic)
bitcoin.__dict__()            # Full data: {"config": {...}, "tokens": [...]}

Wallet address validation

Each network includes a wallet_address_regex pattern in its config. Use it to validate addresses for that chain:

from token_network import network, get_network, validate_wallet_address

# Direct property (same style as .decimal / .confirmation_number)
network("ethereum").wallet_address_regex
# ^(0x)[0-9A-Fa-f]{40}$

# Via config
network("ethereum").config.wallet_address_regex
get_network("bitcoin").config.wallet_address_regex

# In full network dict
network("ethereum").to_dict()["config"]["wallet_address_regex"]

# Validate an address
validate_wallet_address("ethereum", "0xdAC17F958D2ee523a2206206994597C13D831ec7")  # True
validate_wallet_address("ethereum", "0x123")  # False

List tokens on a network

from token_network import network

ethereum = network("ethereum")
tokens = ethereum.tokens      # list of TokenOnNetworkDto

for t in tokens:
    print(t.token.symbol, t.contract_address or "native", t.decimal)
# ETH None 18
# USDT 0xdAC17F958D2ee523a2206206994597C13D831ec7 6
# ...

Get one token on a network

from token_network import get_token_on_network

usdt = get_token_on_network(network="ethereum", token_abbr="USDT")

usdt.contract_address   # "0xdAC17F958D2ee523a2206206994597C13D831ec7"
usdt.decimal            # 6
usdt.native             # False
usdt.token.symbol       # "USDT"
usdt.__dict__()         # All fields as dict (or use .model_dump())

Same via attribute access

from token_network import network

# network.ethereum.usdt is the same as get_token_on_network(network="ethereum", token_abbr="USDT")
usdt = network.ethereum.usdt
assert usdt.contract_address == "0xdAC17F958D2ee523a2206206994597C13D831ec7"

Get token or network by identifier (Pydantic models)

from token_network import get_token, get_network, get_token_network

# Token by symbol, slug, or name (case-insensitive)
token = get_token("USDT")       # TokenDto
print(token.symbol, token.precision)   # USDT 6

# Network with config + tokens
net = get_network("bitcoin")    # NetworkDataDto
print(net.config.base_token)           # BTC
print(len(net.tokens))                 # 1 (e.g. BTC)

# Token on a specific network
ton = get_token_network("USDT", "bsc")  # TokenOnNetworkDto
print(ton.contract_address)

List all networks and tokens

from token_network import get_networks, get_tokens

get_networks()   # ['bitcoin', 'bsc', 'dogecoin', 'ethereum', 'ripple', 'solana', 'tron']
get_tokens()     # ['AAVE', 'BNB', 'BTC', 'ETH', 'USDT', ...]

Testnet config

from token_network import NetworkAccessor

testnet = NetworkAccessor(testnet=True)
bsc = testnet("bsc")
usdt_test = testnet.bsc.usdt   # USDT on BSC from token_networks_testnet.yaml

Error handling

from token_network import network, get_token_on_network, TokenNetworkError

try:
    network("unknown_chain")
except TokenNetworkError as e:
    print(e)  # Unknown network: 'unknown_chain'. Known networks: ...

try:
    get_token_on_network(network="bitcoin", token_abbr="USDT")
except TokenNetworkError as e:
    print(e)  # Token 'USDT' is not on network 'bitcoin'. Available on this network: ['BTC']

API summary

All identifiers are case-insensitive. Unknown network/token raises TokenNetworkError.

Pydantic models

• TokenDto — Token definition (slug, symbol, name, precision, factor). From get_token().
• NetworkConfigDto — Chain config (slug, name, network_type, base_token_decimal, confirmation_number, wallet_address_regex, …). From network("x").config and inside TokenOnNetworkDto.network.
• TokenOnNetworkDto — Token on a network (network, token, contract_address, decimal, native, type). From get_token_on_network(), get_token_network(), network.ethereum.usdt.
• NetworkDataDto — Result of get_network(): config + tokens (list of TokenOnNetworkDto).

Use .model_dump() to export any model as a dict.

Data sources

YAML under token_network/data/:

• networks.yaml — chain config (including wallet_address_regex per network)
• tokens.yaml — token definitions
• token_networks.yaml — mainnet bindings (token + network → contract, decimals)
• token_networks_testnet.yaml — testnet bindings (used with NetworkAccessor(testnet=True))

Development

pip install -e ".[dev]"
pytest