Metadata-Version: 2.4
Name: geckors
Version: 0.1.0
Summary: Minimal CoinGecko-backed token metadata cache for Python.
Keywords: coingecko,crypto,token,sqlite,metadata
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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`:

```bash
uv sync
```

Or install the package in editable mode:

```bash
uv pip install -e .
```

## Quick Start

```python
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:

```python
from geckors import Token

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

## Bulk Population

Populate from symbols:

```python
from geckors import populate_tokens

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

Populate from explicit CoinGecko IDs:

```python
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:

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

Run the example entrypoint:

```bash
uv run python main.py
```
