token-network 0.2.0

Validate input and return token network config (e.g. network.bitcoin, network.bsc.usdt)

token-network

Python library that validates input and returns token network config. Resolve networks and tokens by name/symbol and get merged config (e.g. USDT on BSC with contract address and decimals).

Install

pip install token-network

From source (development):

pip install -e .

Quick start

Mainnet (default) — uses token_networks.yaml:

from token_network import network, get_network, get_token, get_token_network, TokenNetworkError

# Attribute access
network.bitcoin.config          # Bitcoin network config
network.bsc.usdt               # USDT on BSC (contract, decimal, etc.)

# By name/symbol
get_network("bitcoin")         # Full network data
get_token("USDT")              # Token info by symbol, slug, or name
get_token_network("USDT", "bsc")  # Token-on-network config

Testnet — use a dedicated accessor with token_networks_testnet.yaml:

from token_network import NetworkAccessor, TokenNetworkError

testnet = NetworkAccessor(testnet=True)
testnet.bsc.usdt               # USDT on BSC from testnet config
testnet.get_network("bsc")
testnet.get_token_network("USDT", "bsc")

---

API reference

All identifiers (network name, token symbol/slug/name) are case-insensitive. Unknown network or token raises TokenNetworkError.

Attribute access: network

The default network object uses mainnet config (token_networks.yaml). Use network.<network> and optionally network.<network>.<token> for direct access.

For testnet config, create an accessor with NetworkAccessor(testnet=True) and use it the same way (see Quick start).

Usage	Returns
network.bitcoin	Network node (see below)
network.bitcoin.config	Network config dict
network.bitcoin.tokens	List of token bindings on this network
network.bitcoin.to_dict()	{"config": {...}, "tokens": [...]}
network.bsc.usdt	Token-on-network dict (network + token + contract_address, decimal, native)

Example

network.bitcoin.config
# {'network_type': 'UTXO', 'token_standard': 'BTC', 'base_token': 'BTC', 'base_token_decimal': 8, ...}

network.bsc.usdt
# {'network': {...}, 'token': {...}, 'contract_address': '0x55d398326f99059fF775485246999027B3197955', 'decimal': 18, 'native': False}

---

get_networks()

Returns a sorted list of all network ids.

Returns: list[str] — e.g. ['bitcoin', 'bsc', 'dogecoin', 'ethereum', 'ripple', 'solana', 'tron']

Example

from token_network import get_networks
get_networks()
# ['bitcoin', 'bsc', 'dogecoin', 'ethereum', 'ripple', 'solana', 'tron']

Also available as network.get_networks().

---

get_tokens()

Returns a sorted list of all token symbols.

Returns: list[str] — e.g. ['AAVE', 'BNB', 'BTC', 'ETH', 'USDT', ...]

Example

from token_network import get_tokens
get_tokens()
# ['AAVE', 'BNB', 'BTC', 'DOGE', 'ETH', 'LINK', 'SHIB', 'SOL', 'TRX', 'UNI', 'USDC', 'USDT', 'XRP']

Also available as network.get_tokens().

---

get_token(identifier)

Get token object by symbol, slug, or name (case-insensitive).

Parameters

• identifier — Token symbol (e.g. USDT), slug (e.g. usdt), or name (e.g. tether).

Returns: dict — Token info: slug, symbol, standard_symbol, name, precision, factor.

Raises: TokenNetworkError if no token matches.

Example

from token_network import get_token
get_token("USDT")
# {'slug': 'usdt', 'symbol': 'USDT', 'standard_symbol': 'USDT', 'name': 'tether', 'precision': 6, 'factor': '1e6'}
get_token("tether")   # same
get_token("btc")      # Bitcoin token info

Also available as network.get_token(identifier).

---

get_network(identifier)

Get network object by network name/id (case-insensitive).

Parameters

• identifier — Network name (e.g. bitcoin, bsc, ethereum).

Returns: dict with keys:

• config — Network config (network_type, token_standard, base_token, confirmation_number, etc.).
• tokens — List of token bindings on this network.

Raises: TokenNetworkError if network is unknown.

Example

from token_network import get_network
get_network("bitcoin")
# {'config': {'network_type': 'UTXO', 'base_token': 'BTC', ...}, 'tokens': [...]}
get_network("BSC")

Also available as network.get_network(identifier). Same shape as network.bitcoin.to_dict().

---

get_token_network(token_identifier, network_identifier)

Get token_network config for a token on a network (case-insensitive).

Parameters

• token_identifier — Token symbol, slug, or name (e.g. USDT, usdt, tether).
• network_identifier — Network name (e.g. bsc, ethereum).

Returns: dict with keys:

• network — Network config.
• token — Token info (slug, symbol, name, precision, factor).
• contract_address — Contract address or None for native.
• decimal / decimals — Decimals on this network.
• native / type — Whether it is the chain’s native asset.

Raises: TokenNetworkError if token or network is unknown, or if the token is not on that network.

Example

from token_network import get_token_network
get_token_network("USDT", "bsc")
# {'network': {...}, 'token': {...}, 'contract_address': '0x55d398326f99059fF775485246999027B3197955', 'decimal': 18, 'native': False}
get_token_network("tether", "BSC")   # same
get_token_network("ETH", "ethereum")

Same data as network.bsc.usdt. Also available as network.get_token_network(token_identifier, network_identifier).

---

TokenNetworkError

Exception raised when:

• A network name is unknown.
• A token (symbol/slug/name) is unknown.
• A token is requested on a network where it is not defined.

Example

from token_network import get_network, get_token, get_token_network, TokenNetworkError

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

try:
    get_token("unknown_token")
except TokenNetworkError as e:
    print(e)  # Unknown token: 'unknown_token'. Known tokens: [...]

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

---

Data sources

Config is loaded from YAML in the package’s data directory:

File	Content
networks.yaml	Chain config (network_type, token_standard, base_token, confirmation_number, …)
tokens.yaml	Token definitions (symbol, slug, name, precision, factor)
token_networks.yaml	Token–network bindings for mainnet (contract_address, decimal, native)
token_networks_testnet.yaml	Token–network bindings for testnet (used when NetworkAccessor(testnet=True))

• The default network and top-level helpers (get_network, get_token_network, …) use mainnet (token_networks.yaml).
• For testnet, use NetworkAccessor(testnet=True); it loads token_networks_testnet.yaml instead.

To change data, edit the YAML files in token_network/data/.

---

Publishing to PyPI

To allow pip install token-network from PyPI:

1. Create an account on pypi.org.
2. pip install build twine
3. python -m build then twine upload dist/*

For testing: twine upload --repository testpypi dist/*, then
pip install --index-url https://test.pypi.org/simple/ token-network.

---

Development

pip install -e ".[dev]"
pytest