Metadata-Version: 2.4
Name: tckr
Version: 0.2.2
Summary: Async, cached, gracefully-degrading aggregator over the major free crypto data APIs (DEX, perps, TVL, on-chain, social, launchpads, MEV) — plus an agent toolkit that exposes the data to any LLM platform via MCP, the Claude Agent SDK, OpenAI function calling, or LangChain.
Author: tckr contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/tckr-org/tckr
Project-URL: Repository, https://github.com/tckr-org/tckr
Project-URL: Issues, https://github.com/tckr-org/tckr/issues
Project-URL: Changelog, https://github.com/tckr-org/tckr/blob/main/CHANGELOG.md
Keywords: crypto,defi,dex,perps,tvl,solana,base,ethereum,hyperliquid,geckoterminal,dexscreener,defillama,coinalyze,agent,mcp,llm,claude,openai,langchain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: solders>=0.21
Requires-Dist: eth-abi>=5.0
Requires-Dist: eth-hash[pycryptodome]>=0.7
Provides-Extra: agent-claude
Requires-Dist: claude-agent-sdk>=0.1; extra == "agent-claude"
Provides-Extra: agent-mcp
Requires-Dist: mcp>=1.0; extra == "agent-mcp"
Provides-Extra: agent-openai
Requires-Dist: openai>=1.40; extra == "agent-openai"
Provides-Extra: agent-langchain
Requires-Dist: langchain-core>=0.3; extra == "agent-langchain"
Provides-Extra: agent
Requires-Dist: tckr[agent-claude,agent-mcp]; extra == "agent"
Provides-Extra: agent-all
Requires-Dist: tckr[agent-claude,agent-langchain,agent-mcp,agent-openai]; extra == "agent-all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# tckr

[![PyPI](https://img.shields.io/pypi/v/tckr.svg)](https://pypi.org/project/tckr/)
[![CI](https://github.com/allogenes-labs/tckr/actions/workflows/ci.yml/badge.svg)](https://github.com/allogenes-labs/tckr/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**One pip install, 26 crypto data sources, ready for agents.**

tckr stitches the major free crypto APIs — DEX pools, perps, TVL, on-chain wallets, contract safety, launchpads, MEV, social, prediction markets, oracles — into one async, typed Python interface. Every call is TTL-cached per source and returns `None` / `[]` rather than raising when an upstream fails or a key is missing, so a partial install still works. The same registry powers an agent toolkit for Claude, OpenAI, MCP, and LangChain.

```bash
pip install tckr              # data layer
pip install tckr[agent-mcp]   # + universal MCP server for any LLM
pip install tckr[agent-all]   # + all four agent adapters
```

## Works out of the box

13 sources are keyless. Try it:

```python
import asyncio
from tckr import quotes, geckoterminal, defillama

async def main():
    # USD prices for any symbol — falls back from CoinGecko to Hyperliquid on rate limits
    print(await quotes.get(["BTC", "ETH", "SOL", "HYPE"]))

    # Trending DEX pools on Base
    for p in await geckoterminal.trending_pools("base", limit=5):
        print(p["name"], p["price_usd"], p["volume_24h_usd"])

    # Base chain TVL + top protocols
    print(await defillama.chain("base"))

asyncio.run(main())
```

No keys, no rate-limit boilerplate, no provider routing.

## Wire it into agents

Spawn the universal MCP server from any MCP-compatible client (Claude Desktop, Claude Code, Cline, Continue.dev, custom orchestrators):

```bash
pip install tckr[agent-mcp]
tckr-mcp        # listens on stdio
```

Or import the adapter for your platform:

```python
# Claude Agent SDK
from tckr.agent_toolkit.adapters.claude_sdk import build_crypto_mcp_server

# OpenAI / Anthropic function calling
from tckr.agent_toolkit.adapters.openai import get_openai_tools, get_anthropic_tools, execute_tool

# LangChain
from tckr.agent_toolkit.adapters.langchain import get_langchain_tools
```

All adapters serve the same 44 tools from one platform-neutral core. Each tool description auto-injects a tier tag (`[keyless]`, `[keyed-free: needs X]`, `[paid OK]`) from the capability registry, so the model knows what'll work before it tries. A `capabilities` introspection tool lets the agent self-discover the live state:

```python
import tckr
print(tckr.capabilities()["summary"])
# {'total': 26, 'configured': 14, 'by_tier': {'keyless-free': 13, 'keyed-free': 10, 'keyed-paid': 3}}
```

## Unlock more with free API keys

Free signups, no credit cards. Ranked by what we actually use in production (Market-Research-Comp, the sibling agent project tckr was extracted from):

| Key | What it unlocks | Sign up |
|---|---|---|
| `ALCHEMY_API_KEY` | EVM wallet balances + LP-lock detection on Base / ETH (2 modules) | [alchemy.com](https://alchemy.com) |
| `HELIUS_API_KEY` | Solana RPC + Jito MEV intel + wallet PnL (3 modules) | [helius.dev](https://helius.dev) |
| `COINALYZE_API_KEY` | Cross-exchange perps: funding spread, OI, liquidations (Binance / Bybit / OKX / HL) | [coinalyze.net](https://coinalyze.net) |
| `BIRDEYE_API_KEY` | Solana token analytics, top holders, contract security | [birdeye.so](https://birdeye.so) |
| `MORALIS_API_KEY` *or* `BITQUERY_API_KEY` | Pump.fun discovery (new / about-to-bond / graduated). Either one alone is sufficient | [moralis.io](https://moralis.io) / [bitquery.io](https://bitquery.io) |
| `COINGECKO_DEMO_API_KEY` | Higher rate limit on the most-used price endpoint — free tier 429s under any real load | [coingecko.com](https://coingecko.com) |
| `ETHERSCAN_API_KEY` | ~70 EVM chains via the unified V2 API (one key covers ETH, Base, Arb, Op, Polygon, BNB, …) | [etherscan.io](https://etherscan.io) |
| `LUNARCRUSH_API_KEY` | Galaxy Score, AltRank, topic feeds, social sentiment | [lunarcrush.com](https://lunarcrush.com) |
| `THEGRAPH_API_KEY` | Higher-quota subgraph access (Uniswap, Aave, etc.) — public gateway works keyless but throttles fast | [thegraph.com](https://thegraph.com) |

**Tip:** Alchemy + Helius alone open up everything on-chain (EVM + Solana). Add Coinalyze if you care about perps; Birdeye if you focus on Solana memecoins.

## Paid keys for deeper work

These actually buy you something beyond rate-limit bumps:

| Key | What you get |
|---|---|
| `NEYNAR_API_KEY` | Farcaster cast search, channel feeds, trending fungibles — keyless tier only has user lookup |
| `COINGECKO_API_KEY` (Pro) | 500+ req/min plus Pro-only endpoints (top movers, NFT, full historical OHLC) |
| `MESSARI_API_KEY` | Research-grade asset profiles + deep metrics — most useful endpoints moved paid in 2024 |
| `TOKENTERMINAL_API_KEY` | Protocol fundamentals: revenue, fees, P/E, treasury, full historical series |
| `SOLSCAN_API_KEY` (Pro) | Richer Solana transaction parsing, higher rate limit |

All keys are optional. Modules without their key gracefully no-op (return `None` / `[]`); `tckr status` shows what's configured right now.

## Sources

| Module | Tier | Key env var(s) | Provides |
|---|---|---|---|
| `geckoterminal` | keyless | — | DEX pools, tokens, OHLCV (Base / Solana / ETH / …) |
| `dexscreener` | keyless | — | DEX pairs, search, new-pair listings, paid-boost rankings |
| `hyperliquid` | keyless | — | Single-exchange perps: funding, OI, marks, candle history |
| `defillama` | keyless | — | Chain / protocol TVL, DEX volume, stablecoins, yields |
| `goplus` | keyless | — | EVM contract security scans (honeypot, taxes, holders) |
| `honeypot` | keyless | — | EVM sell-simulation (ETH / BSC / Base) |
| `virtuals` | keyless | — | Virtuals Protocol AI-agent launchpad (Base) |
| `clanker` | keyless | — | Clanker Farcaster-native token launcher |
| `coingecko` | keyless / keyed | `COINGECKO_DEMO_API_KEY`, `COINGECKO_API_KEY` | Spot / market / historical prices; trending; categories |
| `polymarket` | keyless | — | Prediction-market odds (binary YES/NO) |
| `pyth` | keyless | — | On-chain oracle prices: ~400 feeds (crypto, equities, FX, metals) |
| `solscan` | keyless / keyed | `SOLSCAN_API_KEY` (Pro) | Solana block explorer |
| `thegraph` | keyless / keyed | `THEGRAPH_API_KEY` | Generic GraphQL access to indexed subgraphs |
| `alchemy` | keyed-free | `ALCHEMY_API_KEY` | EVM (Base, ETH) wallet balances + transfers |
| `helius` | keyed-free | `HELIUS_API_KEY` | Solana RPC convenience layer |
| `coinalyze` | keyed-free | `COINALYZE_API_KEY` | Cross-exchange perps: funding spread, OI, liquidations |
| `birdeye` | keyed-free | `BIRDEYE_API_KEY` | Solana token analytics (overview, holders, security) |
| `etherscan` | keyed-free | `ETHERSCAN_API_KEY` | Unified EVM block explorer (~70 chains via `chainid`) |
| `lunarcrush` | keyed-free | `LUNARCRUSH_API_KEY` | Social sentiment: Galaxy Score, AltRank, topic feeds |
| `lp_lock` | keyed-free | `ALCHEMY_API_KEY` | LP-lock detection: Uniswap V2 / V3 / V4 on Base / ETH |
| `jito` | keyed-free | `HELIUS_API_KEY` | Solana MEV: tip floor, bundle status, snipe-score |
| `pumpfun` | keyed-free | `MORALIS_API_KEY` *or* `BITQUERY_API_KEY` (+ `HELIUS_API_KEY` for state) | Pump.fun launchpad: discovery + bonding curve + analytics |
| `wallet_pnl` | keyed-free | composite (Helius / Alchemy / Moralis / Birdeye) | FIFO PnL across Solana + Base wallets |
| `neynar` | keyed-paid | `NEYNAR_API_KEY` | Farcaster cast search, channel feeds, trending |
| `messari` | keyed-paid | `MESSARI_API_KEY` | Research-grade asset profiles, metrics, news |
| `tokenterminal` | keyed-paid | `TOKENTERMINAL_API_KEY` | Protocol fundamentals: revenue, fees, P/E, treasury |

## Composition

Sources are designed to chain. A few examples:

- `pumpfun.live_trades(mint)` → `jito.snipe_score(sigs)` — how bot-sniped is this launch?
- `clanker.new_tokens()[i]["requestor_fid"]` → `neynar.user_popular_casts(fid)` — what's the deployer saying about their token?
- `clanker.new_tokens()[i]["pool_address"]` (V4 PoolId) → `lp_lock(pool_id)` — is the Clanker LP locked?
- `pumpfun.top_traders(mint)` → `wallet_pnl(wallet)` — is the top buyer actually profitable across their other trades?

## Fallback cascades: `tckr.quotes` and `tckr.history`

Real consumers usually want best-available data, not a specific provider. Two cascade modules wrap the common pattern so callers don't reimplement it:

```python
from tckr import quotes, history

# USD spot price, CoinGecko → Hyperliquid fallback
q = await quotes.get(["BTC", "ETH", "NEAR", "HYPE"])
# {'BTC': {'price': 77150.0, 'source': 'coingecko', ...}, 'HYPE': {'price': 63.6, 'source': 'hyperliquid', ...}}

# 30-day daily candles, CoinGecko market_chart → Hyperliquid candleSnapshot
h = await history.candles(["BTC", "HYPE"], days=30)
```

Each result carries a `source` field so callers can detect when fallback ran. The same cascades are exposed as agent tools (`quote`, `candles`).

Hyperliquid is the canonical free-tier fallback: keyless, no rate limit at typical reading volume, and covers ~230 majors + mid-caps — almost the entire CoinGecko "interesting" universe minus long-tail alts (which belong in DEX pool contexts anyway).

## Diagnostics: `tckr.health()` and `tckr update`

Every HTTP call updates a per-provider rolling summary. Read it to see which sources are currently rate-limited or down:

```python
import tckr
print(tckr.health())
# {"coingecko":  {"ok_count": 14, "fail_count": 3, "last_status": 429, "last_429_ts": "..."},
#  "hyperliquid": {"ok_count": 22, "fail_count": 0, "last_status": 200, ...}}
```

Exposed as an agent tool too (`health`) — useful when an agent is reasoning about why data looks thin.

The CLI checks PyPI for new releases once a day and shows an upgrade banner in `tckr status`. To install:

```bash
tckr update              # one-step upgrade
tckr update --check      # dry-run; just report if a new version exists
```

Detects pipx / `uv tool` / PEP 668 system-managed installs and suggests the right command instead of failing. Set `TCKR_NO_UPDATE_CHECK=1` to silence the implicit banner.

## Configuration

All API keys are optional. Set them as env vars (or via a `.env` file picked up by your shell); `tckr status` shows what's configured right now. Cache TTLs and HTTP behavior (timeouts, retries) are tunable via `TCKR_*` env vars — see [`tckr/settings.py`](tckr/settings.py).

## Agent toolkit adapters

The agent toolkit (`tckr.agent_toolkit`) wraps each useful function as a read-only tool with a JSON Schema, then exposes the same registry through four adapters:

| Extra | Adapter | What it gives you |
|---|---|---|
| `tckr[agent-mcp]` | `adapters.mcp_stdio` | Universal MCP stdio server (`tckr-mcp` console script). Works with any MCP-compatible client. |
| `tckr[agent-claude]` | `adapters.claude_sdk` | In-process MCP server for the Claude Agent SDK (`build_crypto_mcp_server()`). |
| `tckr[agent-openai]` | `adapters.openai` | OpenAI function-calling shapes (`get_openai_tools()`, also `get_anthropic_tools()`) + `execute_tool(name, args)` dispatcher. |
| `tckr[agent-langchain]` | `adapters.langchain` | LangChain `StructuredTool` instances (`get_langchain_tools()`). |

`tckr[agent]` installs the two most-used adapters (`agent-claude` + `agent-mcp`); `tckr[agent-all]` installs all four.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, release process, and how to add new data-source modules or agent tools.

## License

MIT — see [LICENSE](LICENSE).
