tckr 0.1.0__tar.gz

tckr-0.1.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to `tckr` are documented here. Format roughly follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[SemVer](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Capability / tier registry (`tckr.registry`): per-module tier
+  (`keyless-free` / `keyed-free` / `keyed-paid`), required env vars, and an
+  `is_configured()` check. Drives MCP tool descriptions, CLI status, and the
+  `capabilities` introspection tool.
+- Agent toolkit (`tckr.agent_toolkit`) — extracted from the
+  Market-Research-Comp sibling project and refactored into a platform-neutral
+  core + per-platform adapters:
+  - `agent_toolkit.core` — 20+ tool functions and `ToolSpec` registry; no SDK deps.
+  - `adapters/claude_sdk` — Claude Agent SDK in-process MCP server (`tckr[agent-claude]`).
+  - `adapters/mcp_stdio` — universal MCP stdio server, console-script `tckr-mcp`
+    (`tckr[agent-mcp]`). Works with any MCP-compatible client.
+  - `adapters/openai` — OpenAI function-calling shape (`tckr[agent-openai]`).
+  - `adapters/langchain` — LangChain `StructuredTool` wrappers (`tckr[agent-langchain]`).
+
+## [0.1.0] — 2026-05-24
+
+First tagged release. Inventory of what shipped during the build-up
+(2026-05-22 through 2026-05-24):
+
+### Added — data-source modules
+
+- `geckoterminal` — DEX pools, tokens by contract, OHLCV (Base / Solana / ETH). Keyless.
+- `dexscreener` — DEX pairs, search, latest token profiles, paid-boost rankings. Keyless.
+- `hyperliquid` — single-exchange perps: funding, OI, marks. Keyless.
+- `defillama` — chain/protocol TVL, DEX volume, stablecoins, yields. Keyless.
+- `coinalyze` — cross-exchange perps aggregator (funding spread, OI, liquidations
+  across Binance / Bybit / OKX / Hyperliquid). Requires `COINALYZE_API_KEY` (free).
+- `goplus` — EVM token contract security scans (honeypot detection, taxes, owner
+  privileges, holder distribution). Keyless.
+- `honeypot` — sell-simulation backstop on ETH / BSC / Base. Keyless.
+- `birdeye` — Solana-focused token analytics (overview, top holders, security).
+  Requires `BIRDEYE_API_KEY` (free tier).
+- `pumpfun` — Solana memecoin launchpad. Discovery (new / about-to-bond /
+  graduated) via Moralis or Bitquery; on-chain bonding-curve state via Helius.
+  Adds Bitquery-exclusive analytics (top_traders, live_trades, migration_events,
+  curve_trajectory, holder_distribution). Requires `MORALIS_API_KEY` or
+  `BITQUERY_API_KEY` for discovery; `HELIUS_API_KEY` for state.
+- `neynar` — Farcaster API (cast search, channel feeds, trending fungibles).
+  Requires `NEYNAR_API_KEY`; most endpoints require paid tier as of 2026-05.
+- `wallet_pnl` — FIFO PnL across Solana + Base wallets. Auto-resolves ATA →
+  owner. Per-token realized + unrealized USD; filters wSOL/WETH/stables.
+  Composite — reuses Helius / Alchemy / Moralis / Birdeye keys.
+- `lp_lock` — LP-lock detection for Uniswap V2 pairs, V3 positions, V4 positions
+  on Base / ETH. Auto-detects pool type from input shape. Covers UNCX V2/V3/V4
+  and Team Finance ETH lockers. Requires `ALCHEMY_API_KEY` (free).
+- `virtuals` — Virtuals Protocol AI-agent launchpad on Base. Tracks the
+  42K-VIRTUAL bonding-curve graduation threshold. Keyless.
+- `clanker` — Clanker Farcaster-native token launcher (Base, multi-chain).
+  Carries `requestor_fid` for direct cross-link with `neynar`. Keyless.
+- `jito` — Solana MEV intel. `tip_floor`, `bundle_status`, and the headline
+  `snipe_score(sigs)` — feeds e.g. `pumpfun.live_trades` signatures to quantify
+  bot-sniping intensity on a launch. Uses `HELIUS_API_KEY`.
+- `alchemy` — EVM (Base, ETH) wallet balances + transfers. Requires `ALCHEMY_API_KEY`.
+- `helius` — Solana RPC convenience layer. Requires `HELIUS_API_KEY`.
+
+### Added — infrastructure
+
+- `_http` — shared httpx-based fetch helper with retry on 429/5xx.
+- `cache` — async TTL cache, instantiated per-module.
+- `settings` — env-driven config (API keys + per-source TTLs), no other deps.
+- `cli` — `tckr <subcommand>` for ad-hoc queries (dex / token / perps /
+  tvl / wallet).

tckr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tckr contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tckr-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml
+recursive-include tckr *.py
+recursive-exclude tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

tckr-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: tckr
+Version: 0.1.0
+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
+
+A reusable async crypto data layer. Stitches together free (and free-tier) public
+APIs into one clean, cached, typed interface — built to be `pip install -e`'d
+into multiple local projects rather than copy-pasted between them.
+
+Every call is async, cached per-source (TTL), and degrades gracefully — a dead
+or rate-limited upstream returns `None` / `[]` rather than raising. Modules that
+need an API key log a warning and return empty when the key is absent rather
+than crashing the caller.
+
+## Sources
+
+| Module | Source | Key? | Provides |
+|---|---|---|---|
+| `geckoterminal` | GeckoTerminal API v2 | no | DEX pools, tokens by contract address, OHLCV (Base, Solana, ETH, …) |
+| `dexscreener` | Dexscreener API | no | DEX pairs, search, latest token profiles, paid-boost rankings |
+| `hyperliquid` | Hyperliquid API | no | Single-exchange perps: funding, open interest, marks |
+| `coinalyze` | Coinalyze API | free key | Cross-exchange perps: funding spread, OI, liquidations across Binance/Bybit/OKX/Hyperliquid/etc |
+| `defillama` | DefiLlama API | no | Chain/protocol TVL, DEX volume, stablecoins, yields |
+| `goplus` | GoPlus Security API | no | EVM token contract security scans (honeypot detection, taxes, owner privileges, holder dist) |
+| `honeypot` | honeypot.is API | no | EVM sell-simulation backstop (ETH / BSC / Base) — actually attempts a swap to verify exit |
+| `birdeye` | Birdeye public API | free key | Solana-focused token analytics: overview, top holders, trader PnL, security |
+| `pumpfun` | Moralis / Bitquery (discovery + analytics) + Helius (state) | free key(s) | Solana memecoin launchpad. Discovery: new / about-to-bond / graduated lists. On-chain: bonding-curve state via SPL balance. Bitquery-exclusive analytics: top_traders, live_trades, migration_events, curve_trajectory, holder_distribution. |
+| `neynar` | Neynar (Farcaster) | paid for most | Cast search, channel feeds, trending casts + fungibles, KOL helpers. 8 functions wired; only `user_by_username` works on free tier as of May 2026 — others return 402 until upgrade (degrade gracefully). |
+| `wallet_pnl` | Helius (Solana) + Moralis (Base) + birdeye (prices) | uses existing keys | FIFO PnL across Sol+Base wallets. Auto-resolves ATA → owner. Per-token realized + unrealized USD. Filters wSOL/WETH/stables as counter assets by default. |
+| `lp_lock` | Alchemy (EVM) | uses existing key | LP-lock detection for Uniswap V2 pairs, V3 positions, and V4 positions on Base / ETH. Auto-detects from input shape (40-hex-char address vs 64-hex-char PoolId). V2 returns `locked_pct`; V3/V4 return `n_locked_positions` + per-position detail. Covers UNCX V2, V3, V4 lockers; Team Finance on ETH. Team Finance Base + per-lock unlock_at are TODOs. |
+| `virtuals` | api.virtuals.io | no key | Virtuals Protocol AI-agent launchpad on Base. `new_tokens` / `about_to_graduate` / `recently_graduated` / `genesis_launches` / `token_info`. Tracks the 42K-VIRTUAL bonding-curve graduation threshold. |
+| `clanker` | clanker.world/api | no key | Clanker Farcaster-native token launcher (Base + multi-chain). `new_tokens` / `trending_tokens` / `tokens_by_fid` / `tokens_by_deployer` / `holders` / `token_info`. Carries `requestor_fid` for direct cross-link with [[neynar]]. |
+| `jito` | block-engine.jito.wtf + Helius | uses HELIUS_API_KEY | Solana MEV intel. `tip_floor()`, `tip_accounts()`, `bundle_status()`, `inflight_bundle_status()`, `tx_jito_info(sig)`, `snipe_score(sigs)`. Killer use case: feed `pumpfun.live_trades` signatures into `snipe_score` to quantify how heavily a launch was bot-sniped. |
+| `alchemy` | Alchemy RPC | free key | EVM (Base, ETH) on-chain wallet balances + transfers |
+| `helius` | Helius RPC | free key | Solana RPC convenience layer (balances, transfers) |
+| `coingecko` | CoinGecko v3 | no key (rate-limited) / free demo key / paid Pro | Canonical spot / market / historical prices; `simple_price`, `coin_markets`, `coin`, `market_chart`, `search`, `trending`, `global_stats`, `categories`. |
+| `polymarket` | Polymarket Gamma API | no | Prediction-market odds (binary YES/NO). `markets`, `top_volume`, `market`, `events`. |
+| `pyth` | Pyth Hermes | no | On-chain oracle prices for ~400 feeds (crypto, equities, FX, metals, rates). `feeds`, `latest_price`, `latest_price_for_symbols`. Sub-second cadence. |
+| `etherscan` | Etherscan V2 | free key | Unified EVM block explorer across ~70 chains (ETH=1, Base=8453, Arb, Op, Polygon, BNB, ...). `balance`, `token_transfers`, `contract_source`, `contract_abi`, `gas_oracle`, `eth_supply`. Backwards-compat with `BASESCAN_API_KEY`. |
+| `solscan` | Solscan | no (public) / free key (Pro) | Solana block explorer. Public endpoints (`token_meta`, `account_info`, `account_tokens`, `token_holders`, `tx_detail`) work keyless; `SOLSCAN_API_KEY` upgrades to Pro for richer parsing + higher RL. |
+| `lunarcrush` | LunarCrush API4 | free key | Social-sentiment scoring: Galaxy Score, AltRank, social volume, topic feeds. `coins_list`, `coin`, `coin_time_series`, `topic`, `topics_list`. Free tier ~100 req/day. |
+| `messari` | Messari API v1/v2 | paid (mostly) | Research-grade asset profiles, metrics, news. `asset`, `asset_metrics`, `asset_profile`, `news_feed`, `assets`. Most endpoints moved behind paid plans in 2024-2025. |
+| `tokenterminal` | Token Terminal API v2 | paid (mostly) | Protocol fundamentals: revenue, fees, P/E, treasury. `projects`, `project`, `project_metrics`, `metric_history`, `market_sectors`. Free tier exposes catalog; historical series are paid. |
+| `thegraph` | The Graph | no (public gateway, throttled) / free key (decentralized) | Generic GraphQL access to indexed subgraphs (Uniswap, Aave, Compound, Lido, etc.). `query_subgraph(id, query, vars)`, `uniswap_v3_top_pools`. |
+
+## Install
+
+```
+pip install -e path/to/tckr
+```
+
+## Usage
+
+```python
+import asyncio
+from tckr import geckoterminal, coinalyze
+
+async def main():
+    pools = await geckoterminal.trending_pools("base", limit=5)
+    for p in pools:
+        print(p["name"], p["price_usd"], p["volume_24h_usd"])
+
+    # Cross-exchange funding spread for one coin — the killer Coinalyze use case
+    agg = await coinalyze.funding_aggregate("BTC")
+    if agg:
+        a = agg["aggregate"]
+        print(f"BTC funding APR — min {a['min_apr_pct']:.1f}%  "
+              f"max {a['max_apr_pct']:.1f}%  spread {a['spread_apr_pct']:.1f}%")
+
+asyncio.run(main())
+```
+
+## Configuration
+
+All env vars are optional — modules without keys still work; modules with keys
+no-op until set. See `tckr/settings.py` for the full list.
+
+API keys (only needed for the modules that declare them in the table above):
+
+- `COINALYZE_API_KEY` — free signup at coinalyze.net (no card).
+- `BIRDEYE_API_KEY` — free tier at birdeye.so (~30 req/min on the endpoints used here).
+- `MORALIS_API_KEY` — free tier at moralis.com; primary source for `pumpfun` discovery (`new_tokens`, `about_to_bond`, `recently_graduated`).
+- `BITQUERY_API_KEY` — free tier at bitquery.io; fallback for `pumpfun.new_tokens` (Bitquery has the richest Pump.fun-specific schema). Either Moralis or Bitquery alone gets you working discovery. On-chain `bonding_state` only needs `HELIUS_API_KEY`. Also unlocks the 5 Bitquery-exclusive analytics functions (top_traders, live_trades, migration_events, curve_trajectory, holder_distribution).
+- `NEYNAR_API_KEY` — free signup at dev.neynar.com. As of May 2026 the free tier only includes `user_by_username` — `search_casts`, `channel_feed`, `trending_fungibles` and the other 5 require a paid plan.
+- `ALCHEMY_API_KEY` — free tier covers Base + ETH at app.alchemy.com.
+- `HELIUS_API_KEY` — free tier at helius.dev.
+- `BASESCAN_API_KEY` — currently declared but not consumed by any shipped module; reserved for the planned etherscan/basescan module.
+- `COINGECKO_API_KEY` — CoinGecko Pro plan (paid). Uses `pro-api.coingecko.com` and unlocks Pro-only endpoints + 500 req/min+.
+- `COINGECKO_DEMO_API_KEY` — CoinGecko Demo plan (free signup). Same public endpoints with a slightly higher rate-limit than no-key.
+- `ETHERSCAN_API_KEY` — Etherscan V2 (free signup at etherscan.io). One key works across all V2-supported chains via the `chainid` parameter (ETH, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, zkSync, ...). The legacy `BASESCAN_API_KEY` env is also accepted as a fallback.
+- `SOLSCAN_API_KEY` — Solscan Pro (paid). Public endpoints work without it.
+- `LUNARCRUSH_API_KEY` — required for any LunarCrush call. Free signup at lunarcrush.com (~100 req/day on free tier).
+- `MESSARI_API_KEY` — Messari. Free 'Hobbyist' tier limited to ~20 req/min on a small subset; most useful endpoints are paid (Pro / Enterprise).
+- `TOKENTERMINAL_API_KEY` — Token Terminal. Free tier covers project catalog + limited metrics; full historical series + most metrics are paid.
+- `THEGRAPH_API_KEY` — optional. Without it the public gateway is used (heavily throttled); with it the decentralized network gateway gives much higher quota.
+
+Cache TTLs (override only if you know why):
+
+- `TCKR_DEX_TTL_S`, `TCKR_DEX_OHLCV_TTL_S`, `TCKR_PERPS_TTL_S`,
+  `TCKR_TVL_TTL_S`, `TCKR_ONCHAIN_TTL_S`, `TCKR_FUNDING_AGG_TTL_S`,
+  `TCKR_LIQUIDATION_TTL_S`, `TCKR_SECURITY_TTL_S`,
+  `TCKR_HONEYPOT_TTL_S`, `TCKR_BIRDEYE_TTL_S`, `TCKR_TOKEN_METADATA_TTL_S`,
+  `TCKR_COINGECKO_TTL_S` (default 30), `TCKR_COINGECKO_HISTORY_TTL_S` (default 600),
+  `TCKR_POLYMARKET_TTL_S` (default 30),
+  `TCKR_PYTH_PRICE_TTL_S` (default 10), `TCKR_PYTH_CATALOG_TTL_S` (default 3600),
+  `TCKR_ETHERSCAN_TTL_S` (default 30), `TCKR_ETHERSCAN_CONTRACT_TTL_S` (default 86400),
+  `TCKR_ETHERSCAN_GAS_TTL_S` (default 15), `TCKR_ETHERSCAN_STATS_TTL_S` (default 600),
+  `TCKR_SOLSCAN_TTL_S` (default 60),
+  `TCKR_LUNARCRUSH_TTL_S` (default 120),
+  `TCKR_MESSARI_TTL_S` (default 300),
+  `TCKR_TOKENTERMINAL_TTL_S` (default 300), `TCKR_TOKENTERMINAL_HISTORY_TTL_S` (default 3600),
+  `TCKR_THEGRAPH_TTL_S` (default 60).
+
+HTTP behavior:
+
+- `TCKR_HTTP_TIMEOUT_S` (default 15.0), `TCKR_HTTP_MAX_RETRIES` (default 2).
+
+## New-pair / early-stage strategies (Sol + Base)
+
+The thesis: the highest-asymmetry crypto trades are early entries on new
+tokens that grow. The full toolkit for that is now shipped — `pumpfun` and
+`virtuals` / `clanker` cover discovery on each chain's dominant launchpad;
+`bonding_state` + `lp_lock` cover safety; `wallet_pnl` covers smart-money
+tracking; `jito` quantifies bot-sniping intensity; `neynar` adds the
+Farcaster social signal on Base. The modules compose:
+
+- `pumpfun.live_trades(mint)` signatures → `jito.snipe_score(sigs)` →
+  "how bot-sniped is this launch?"
+- `clanker.new_tokens()` `requestor_fid` → `neynar.user_popular_casts(fid)` →
+  "what is this deployer saying about their token?"
+- `clanker.new_tokens()` `pool_address` (V4 PoolId) → `lp_lock(pool_id)` →
+  "is this Clanker token's LP locked?"
+- `pumpfun.top_traders(mint)` wallets → `wallet_pnl(wallet)` → "is the top
+  buyer of this token actually profitable across their other trades?"
+
+Future open items (no fixed timeline): per-lock `unlock_at` decoding for
+UNCX V2/V3/V4, Team Finance Base address, V3/V4 USD-value-of-locked-liquidity
+(needs tick math), neynar paid-tier endpoints when budgeted.
+
+## Consumers
+
+`tckr` is currently consumed by:
+
+- **Market-Research-Comp** (sibling repo) — uses the fundamental-trading subset
+  (`geckoterminal`, `dexscreener` basics, `hyperliquid`, `coinalyze`, `defillama`).
+  Contract-safety + Solana-analytics modules ship in the library but are not
+  exposed to those agents — reserved for the future new-pair app sketched above.

tckr-0.1.0/README.md

@@ -0,0 +1,144 @@
+# tckr
+
+A reusable async crypto data layer. Stitches together free (and free-tier) public
+APIs into one clean, cached, typed interface — built to be `pip install -e`'d
+into multiple local projects rather than copy-pasted between them.
+
+Every call is async, cached per-source (TTL), and degrades gracefully — a dead
+or rate-limited upstream returns `None` / `[]` rather than raising. Modules that
+need an API key log a warning and return empty when the key is absent rather
+than crashing the caller.
+
+## Sources
+
+| Module | Source | Key? | Provides |
+|---|---|---|---|
+| `geckoterminal` | GeckoTerminal API v2 | no | DEX pools, tokens by contract address, OHLCV (Base, Solana, ETH, …) |
+| `dexscreener` | Dexscreener API | no | DEX pairs, search, latest token profiles, paid-boost rankings |
+| `hyperliquid` | Hyperliquid API | no | Single-exchange perps: funding, open interest, marks |
+| `coinalyze` | Coinalyze API | free key | Cross-exchange perps: funding spread, OI, liquidations across Binance/Bybit/OKX/Hyperliquid/etc |
+| `defillama` | DefiLlama API | no | Chain/protocol TVL, DEX volume, stablecoins, yields |
+| `goplus` | GoPlus Security API | no | EVM token contract security scans (honeypot detection, taxes, owner privileges, holder dist) |
+| `honeypot` | honeypot.is API | no | EVM sell-simulation backstop (ETH / BSC / Base) — actually attempts a swap to verify exit |
+| `birdeye` | Birdeye public API | free key | Solana-focused token analytics: overview, top holders, trader PnL, security |
+| `pumpfun` | Moralis / Bitquery (discovery + analytics) + Helius (state) | free key(s) | Solana memecoin launchpad. Discovery: new / about-to-bond / graduated lists. On-chain: bonding-curve state via SPL balance. Bitquery-exclusive analytics: top_traders, live_trades, migration_events, curve_trajectory, holder_distribution. |
+| `neynar` | Neynar (Farcaster) | paid for most | Cast search, channel feeds, trending casts + fungibles, KOL helpers. 8 functions wired; only `user_by_username` works on free tier as of May 2026 — others return 402 until upgrade (degrade gracefully). |
+| `wallet_pnl` | Helius (Solana) + Moralis (Base) + birdeye (prices) | uses existing keys | FIFO PnL across Sol+Base wallets. Auto-resolves ATA → owner. Per-token realized + unrealized USD. Filters wSOL/WETH/stables as counter assets by default. |
+| `lp_lock` | Alchemy (EVM) | uses existing key | LP-lock detection for Uniswap V2 pairs, V3 positions, and V4 positions on Base / ETH. Auto-detects from input shape (40-hex-char address vs 64-hex-char PoolId). V2 returns `locked_pct`; V3/V4 return `n_locked_positions` + per-position detail. Covers UNCX V2, V3, V4 lockers; Team Finance on ETH. Team Finance Base + per-lock unlock_at are TODOs. |
+| `virtuals` | api.virtuals.io | no key | Virtuals Protocol AI-agent launchpad on Base. `new_tokens` / `about_to_graduate` / `recently_graduated` / `genesis_launches` / `token_info`. Tracks the 42K-VIRTUAL bonding-curve graduation threshold. |
+| `clanker` | clanker.world/api | no key | Clanker Farcaster-native token launcher (Base + multi-chain). `new_tokens` / `trending_tokens` / `tokens_by_fid` / `tokens_by_deployer` / `holders` / `token_info`. Carries `requestor_fid` for direct cross-link with [[neynar]]. |
+| `jito` | block-engine.jito.wtf + Helius | uses HELIUS_API_KEY | Solana MEV intel. `tip_floor()`, `tip_accounts()`, `bundle_status()`, `inflight_bundle_status()`, `tx_jito_info(sig)`, `snipe_score(sigs)`. Killer use case: feed `pumpfun.live_trades` signatures into `snipe_score` to quantify how heavily a launch was bot-sniped. |
+| `alchemy` | Alchemy RPC | free key | EVM (Base, ETH) on-chain wallet balances + transfers |
+| `helius` | Helius RPC | free key | Solana RPC convenience layer (balances, transfers) |
+| `coingecko` | CoinGecko v3 | no key (rate-limited) / free demo key / paid Pro | Canonical spot / market / historical prices; `simple_price`, `coin_markets`, `coin`, `market_chart`, `search`, `trending`, `global_stats`, `categories`. |
+| `polymarket` | Polymarket Gamma API | no | Prediction-market odds (binary YES/NO). `markets`, `top_volume`, `market`, `events`. |
+| `pyth` | Pyth Hermes | no | On-chain oracle prices for ~400 feeds (crypto, equities, FX, metals, rates). `feeds`, `latest_price`, `latest_price_for_symbols`. Sub-second cadence. |
+| `etherscan` | Etherscan V2 | free key | Unified EVM block explorer across ~70 chains (ETH=1, Base=8453, Arb, Op, Polygon, BNB, ...). `balance`, `token_transfers`, `contract_source`, `contract_abi`, `gas_oracle`, `eth_supply`. Backwards-compat with `BASESCAN_API_KEY`. |
+| `solscan` | Solscan | no (public) / free key (Pro) | Solana block explorer. Public endpoints (`token_meta`, `account_info`, `account_tokens`, `token_holders`, `tx_detail`) work keyless; `SOLSCAN_API_KEY` upgrades to Pro for richer parsing + higher RL. |
+| `lunarcrush` | LunarCrush API4 | free key | Social-sentiment scoring: Galaxy Score, AltRank, social volume, topic feeds. `coins_list`, `coin`, `coin_time_series`, `topic`, `topics_list`. Free tier ~100 req/day. |
+| `messari` | Messari API v1/v2 | paid (mostly) | Research-grade asset profiles, metrics, news. `asset`, `asset_metrics`, `asset_profile`, `news_feed`, `assets`. Most endpoints moved behind paid plans in 2024-2025. |
+| `tokenterminal` | Token Terminal API v2 | paid (mostly) | Protocol fundamentals: revenue, fees, P/E, treasury. `projects`, `project`, `project_metrics`, `metric_history`, `market_sectors`. Free tier exposes catalog; historical series are paid. |
+| `thegraph` | The Graph | no (public gateway, throttled) / free key (decentralized) | Generic GraphQL access to indexed subgraphs (Uniswap, Aave, Compound, Lido, etc.). `query_subgraph(id, query, vars)`, `uniswap_v3_top_pools`. |
+
+## Install
+
+```
+pip install -e path/to/tckr
+```
+
+## Usage
+
+```python
+import asyncio
+from tckr import geckoterminal, coinalyze
+
+async def main():
+    pools = await geckoterminal.trending_pools("base", limit=5)
+    for p in pools:
+        print(p["name"], p["price_usd"], p["volume_24h_usd"])
+
+    # Cross-exchange funding spread for one coin — the killer Coinalyze use case
+    agg = await coinalyze.funding_aggregate("BTC")
+    if agg:
+        a = agg["aggregate"]
+        print(f"BTC funding APR — min {a['min_apr_pct']:.1f}%  "
+              f"max {a['max_apr_pct']:.1f}%  spread {a['spread_apr_pct']:.1f}%")
+
+asyncio.run(main())
+```
+
+## Configuration
+
+All env vars are optional — modules without keys still work; modules with keys
+no-op until set. See `tckr/settings.py` for the full list.
+
+API keys (only needed for the modules that declare them in the table above):
+
+- `COINALYZE_API_KEY` — free signup at coinalyze.net (no card).
+- `BIRDEYE_API_KEY` — free tier at birdeye.so (~30 req/min on the endpoints used here).
+- `MORALIS_API_KEY` — free tier at moralis.com; primary source for `pumpfun` discovery (`new_tokens`, `about_to_bond`, `recently_graduated`).
+- `BITQUERY_API_KEY` — free tier at bitquery.io; fallback for `pumpfun.new_tokens` (Bitquery has the richest Pump.fun-specific schema). Either Moralis or Bitquery alone gets you working discovery. On-chain `bonding_state` only needs `HELIUS_API_KEY`. Also unlocks the 5 Bitquery-exclusive analytics functions (top_traders, live_trades, migration_events, curve_trajectory, holder_distribution).
+- `NEYNAR_API_KEY` — free signup at dev.neynar.com. As of May 2026 the free tier only includes `user_by_username` — `search_casts`, `channel_feed`, `trending_fungibles` and the other 5 require a paid plan.
+- `ALCHEMY_API_KEY` — free tier covers Base + ETH at app.alchemy.com.
+- `HELIUS_API_KEY` — free tier at helius.dev.
+- `BASESCAN_API_KEY` — currently declared but not consumed by any shipped module; reserved for the planned etherscan/basescan module.
+- `COINGECKO_API_KEY` — CoinGecko Pro plan (paid). Uses `pro-api.coingecko.com` and unlocks Pro-only endpoints + 500 req/min+.
+- `COINGECKO_DEMO_API_KEY` — CoinGecko Demo plan (free signup). Same public endpoints with a slightly higher rate-limit than no-key.
+- `ETHERSCAN_API_KEY` — Etherscan V2 (free signup at etherscan.io). One key works across all V2-supported chains via the `chainid` parameter (ETH, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, zkSync, ...). The legacy `BASESCAN_API_KEY` env is also accepted as a fallback.
+- `SOLSCAN_API_KEY` — Solscan Pro (paid). Public endpoints work without it.
+- `LUNARCRUSH_API_KEY` — required for any LunarCrush call. Free signup at lunarcrush.com (~100 req/day on free tier).
+- `MESSARI_API_KEY` — Messari. Free 'Hobbyist' tier limited to ~20 req/min on a small subset; most useful endpoints are paid (Pro / Enterprise).
+- `TOKENTERMINAL_API_KEY` — Token Terminal. Free tier covers project catalog + limited metrics; full historical series + most metrics are paid.
+- `THEGRAPH_API_KEY` — optional. Without it the public gateway is used (heavily throttled); with it the decentralized network gateway gives much higher quota.
+
+Cache TTLs (override only if you know why):
+
+- `TCKR_DEX_TTL_S`, `TCKR_DEX_OHLCV_TTL_S`, `TCKR_PERPS_TTL_S`,
+  `TCKR_TVL_TTL_S`, `TCKR_ONCHAIN_TTL_S`, `TCKR_FUNDING_AGG_TTL_S`,
+  `TCKR_LIQUIDATION_TTL_S`, `TCKR_SECURITY_TTL_S`,
+  `TCKR_HONEYPOT_TTL_S`, `TCKR_BIRDEYE_TTL_S`, `TCKR_TOKEN_METADATA_TTL_S`,
+  `TCKR_COINGECKO_TTL_S` (default 30), `TCKR_COINGECKO_HISTORY_TTL_S` (default 600),
+  `TCKR_POLYMARKET_TTL_S` (default 30),
+  `TCKR_PYTH_PRICE_TTL_S` (default 10), `TCKR_PYTH_CATALOG_TTL_S` (default 3600),
+  `TCKR_ETHERSCAN_TTL_S` (default 30), `TCKR_ETHERSCAN_CONTRACT_TTL_S` (default 86400),
+  `TCKR_ETHERSCAN_GAS_TTL_S` (default 15), `TCKR_ETHERSCAN_STATS_TTL_S` (default 600),
+  `TCKR_SOLSCAN_TTL_S` (default 60),
+  `TCKR_LUNARCRUSH_TTL_S` (default 120),
+  `TCKR_MESSARI_TTL_S` (default 300),
+  `TCKR_TOKENTERMINAL_TTL_S` (default 300), `TCKR_TOKENTERMINAL_HISTORY_TTL_S` (default 3600),
+  `TCKR_THEGRAPH_TTL_S` (default 60).
+
+HTTP behavior:
+
+- `TCKR_HTTP_TIMEOUT_S` (default 15.0), `TCKR_HTTP_MAX_RETRIES` (default 2).
+
+## New-pair / early-stage strategies (Sol + Base)
+
+The thesis: the highest-asymmetry crypto trades are early entries on new
+tokens that grow. The full toolkit for that is now shipped — `pumpfun` and
+`virtuals` / `clanker` cover discovery on each chain's dominant launchpad;
+`bonding_state` + `lp_lock` cover safety; `wallet_pnl` covers smart-money
+tracking; `jito` quantifies bot-sniping intensity; `neynar` adds the
+Farcaster social signal on Base. The modules compose:
+
+- `pumpfun.live_trades(mint)` signatures → `jito.snipe_score(sigs)` →
+  "how bot-sniped is this launch?"
+- `clanker.new_tokens()` `requestor_fid` → `neynar.user_popular_casts(fid)` →
+  "what is this deployer saying about their token?"
+- `clanker.new_tokens()` `pool_address` (V4 PoolId) → `lp_lock(pool_id)` →
+  "is this Clanker token's LP locked?"
+- `pumpfun.top_traders(mint)` wallets → `wallet_pnl(wallet)` → "is the top
+  buyer of this token actually profitable across their other trades?"
+
+Future open items (no fixed timeline): per-lock `unlock_at` decoding for
+UNCX V2/V3/V4, Team Finance Base address, V3/V4 USD-value-of-locked-liquidity
+(needs tick math), neynar paid-tier endpoints when budgeted.
+
+## Consumers
+
+`tckr` is currently consumed by:
+
+- **Market-Research-Comp** (sibling repo) — uses the fundamental-trading subset
+  (`geckoterminal`, `dexscreener` basics, `hyperliquid`, `coinalyze`, `defillama`).
+  Contract-safety + Solana-analytics modules ship in the library but are not
+  exposed to those agents — reserved for the future new-pair app sketched above.

tckr-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tckr"
+version = "0.1.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "crypto", "defi", "dex", "perps", "tvl", "solana", "base", "ethereum",
+    "hyperliquid", "geckoterminal", "dexscreener", "defillama", "coinalyze",
+    "agent", "mcp", "llm", "claude", "openai", "langchain",
+]
+authors = [
+    { name = "tckr contributors" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "solders>=0.21",
+    "eth-abi>=5.0",
+    "eth-hash[pycryptodome]>=0.7",
+]
+
+[project.optional-dependencies]
+# Each adapter is opt-in. Install only what your agent platform needs.
+agent-claude    = ["claude-agent-sdk>=0.1"]
+agent-mcp       = ["mcp>=1.0"]
+agent-openai    = ["openai>=1.40"]
+agent-langchain = ["langchain-core>=0.3"]
+# Convenience meta-extras:
+agent      = ["tckr[agent-claude,agent-mcp]"]
+agent-all  = ["tckr[agent-claude,agent-mcp,agent-openai,agent-langchain]"]
+# Development:
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "build>=1.2",
+]
+
+[project.scripts]
+tckr     = "tckr.cli:main"
+# Universal MCP stdio server — spawn from any MCP-compatible client (Claude
+# Code, Cline, Continue.dev, OpenAI Agents, custom orchestrators…).
+# Requires `tckr[agent-mcp]`.
+tckr-mcp = "tckr.agent_toolkit.adapters.mcp_stdio:main"
+
+[project.urls]
+Homepage      = "https://github.com/tckr-org/tckr"
+Repository    = "https://github.com/tckr-org/tckr"
+Issues        = "https://github.com/tckr-org/tckr/issues"
+Changelog     = "https://github.com/tckr-org/tckr/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+include = ["tckr*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "needs_keys: test requires API keys in the environment",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+# Pragmatic default — surface clear bugs without being aesthetically opinionated.
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = [
+    "E501",  # line length handled by formatter
+    "B008",  # function-call default args (httpx uses them)
+    "E701",  # single-line `if x: y = z` is a deliberate terse idiom in this codebase
+    "UP031", # %-format in GraphQL query bodies stays readable; f-strings collide with {...}
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B018"]  # bare expressions in tests are fine (asserts)

tckr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tckr-0.1.0/tckr/__init__.py

@@ -0,0 +1,54 @@
+"""tckr — a reusable async crypto data layer + agent toolkit.
+
+Import source modules directly:
+
+    geckoterminal   DEX pools, tokens by address, OHLCV (Base, Solana, …)
+    dexscreener     DEX pairs, search, new-pair discovery, paid-boost rankings
+    hyperliquid     perps: funding, open interest, marks (single-exchange)
+    coinalyze       perps cross-exchange: funding spread, OI, liquidations
+    defillama       chain/protocol TVL, DEX volume, stablecoins, yields
+    goplus          EVM token contract security scans (honeypot, taxes, holders)
+    honeypot        EVM sell-simulation backstop (subset of chains)
+    birdeye         Solana-focused token analytics (holders, trades, security)
+    pumpfun         Solana memecoin launchpad: discovery + bonding-curve state
+    neynar          Farcaster API: cast search, channel feeds, trending fungibles
+    wallet_pnl      FIFO position tracking across Solana + Base wallets
+    lp_lock         LP-lock detection (Base / EVM) via known locker contracts
+    virtuals        Virtuals Protocol AI-agent launchpad (Base, multi-chain)
+    clanker         Clanker Farcaster-native token launcher (Base, multi-chain)
+    jito            Solana MEV: tip floor, bundle status, snipe-score for txs
+    alchemy         on-chain wallet balances + transfers
+    helius          Solana RPC convenience layer
+    coingecko       canonical spot / market / historical prices (v3 + Pro)
+    polymarket      Polymarket Gamma API: prediction-market odds
+    pyth            Pyth Network on-chain oracle prices (~400 feeds, keyless)
+    etherscan       Etherscan V2 unified EVM block explorer (~70 chains, one key)
+    solscan         Solana block explorer (public + Pro paths)
+    lunarcrush      social sentiment: Galaxy Score, AltRank, topic feeds
+    messari         research-grade asset profiles, metrics, news
+    tokenterminal   protocol fundamentals (revenue, P/E, treasury)
+    thegraph        GraphQL access to indexed subgraphs (Uniswap, Aave, ...)
+
+Every network call is async, cached (tckr.cache.TTLCache), and degrades
+gracefully — it returns None / [] rather than raising when an upstream fails.
+Modules that need an API key log a warning and return empty when the key is
+absent rather than crashing the caller.
+
+Capability registry: `tckr.registry` tracks per-module tier and which
+env vars unlock each. `capabilities()` returns the live state as JSON; the CLI
+`tckr status` prints it. The same registry powers tier tags on tool
+descriptions in `tckr.agent_toolkit`.
+
+Agent toolkit (optional extras): `pip install tckr[agent-claude]` for
+the Claude Agent SDK in-process MCP server, `tckr[agent-mcp]` for the
+universal stdio MCP server (console script `tckr-mcp`, works with any
+MCP client), `tckr[agent-openai]` for OpenAI function-calling, or
+`tckr[agent-langchain]` for LangChain `StructuredTool` wrappers.
+"""
+from __future__ import annotations
+
+from tckr.registry import capabilities  # re-exported for convenience
+
+__version__ = "0.1.0"
+
+__all__ = ["capabilities", "__version__"]

tckr-0.1.0/tckr/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m tckr <command>` as an alternative to the
+`tckr` script entry point installed by pyproject.toml.
+"""
+from tckr.cli import main
+
+raise SystemExit(main())