GeckoRS

geckors is a small Python wrapper around CoinGecko's public API for token metadata.

It is designed for:

• resolving a ticker or CoinGecko ID into a token
• caching token metadata locally in SQLite
• keeping dependencies minimal
• exposing a simple object API for common fields such as contract addresses, decimals, and supply

The project is intentionally metadata-focused. It does not try to be a full market-data client.

Features

• CoinGecko-backed token lookup
• local SQLite cache
• normalized contract storage in token_contracts
• alias resolution in token_aliases so repeated lookups are deterministic
• high-level Token object with useful properties
• bulk population helpers
• rate-limit-safe bulk fetch behavior

Installation

Using uv:

uv sync

Or install the package in editable mode:

uv pip install -e .

Quick Start

from geckors import Token

token = Token("ETH")

print(token.id)
print(token.name)
print(token.contract_addresses)
print(token.decimals)
print(token.max_supply)

Useful properties on Token include:

• id
• symbol
• name
• market_cap_rank
• asset_platform_id
• contract_addresses
• platform_details
• decimals
• circulating_supply
• total_supply
• max_supply
• categories
• links
• homepage
• description
• developer_data
• community_data
• public_interest_stats
• raw

Example:

from geckors import Token

token = Token("DAI")
print(token.get_address("ethereum"))
print(token.contract_addresses)

Bulk Population

Populate from symbols:

from geckors import populate_tokens

result = populate_tokens(["BTC", "ETH", "DAI", "WETH"])
print(result)

Populate from explicit CoinGecko IDs:

from geckors import populate_token_ids

result = populate_token_ids(["bitcoin", "ethereum", "dai"])
print(result)

populate_tokens() returns structured results for:

• resolved queries
• inserted IDs
• skipped rows already in cache
• unresolved queries
• ambiguous symbols
• failed requests
• rate-limit state

Storage

By default the SQLite database is stored in the platform data directory:

• Linux/BSD: ~/.local/share/geckors/gecko_rs.db or $XDG_DATA_HOME/geckors/gecko_rs.db
• macOS: ~/Library/Application Support/geckors/gecko_rs.db
• Windows: %LOCALAPPDATA%/geckors/gecko_rs.db

Override order:

1. GECKO_RS_DB
2. config.json in the config directory
3. platform data directory default

Current tables:

• tokens: canonical token metadata keyed by CoinGecko ID
• token_contracts: normalized chain/address/decimals rows
• token_aliases: query-to-token resolution cache

CoinGecko Notes

• CoinGecko ID is the stable internal identity in this project. Symbols are only lookup hints.
• Native assets like ETH may not have token contract addresses. CoinGecko often returns an empty placeholder for those; geckors filters that out.
• Contract coverage is limited to what CoinGecko currently lists for that specific asset ID.
• A successful response is not partially truncated by rate limiting. If CoinGecko rate-limits a request, the request fails.

Rate Limits

This project uses CoinGecko public endpoints. Public usage is rate-limited.

Bulk helpers are defensive:

• they stop cleanly on HTTP 429 by default
• they return a structured summary instead of crashing the whole run

You can also provide:

• COINGECKO_DEMO_API_KEY
• COINGECKO_PRO_API_KEY

if you have one.

Development

Run tests:

uv run python -m unittest discover -s tests -v

Run the example entrypoint:

uv run python main.py