chainq 0.11.0__tar.gz

chainq-0.11.0/.env.example

@@ -0,0 +1,5 @@
+CHAINQ_COINGECKO_API_KEY=
+CHAINQ_OPENSEA_API_KEY=
+CHAINQ_HTTP_TIMEOUT=10
+CHAINQ_RPC_TIMEOUT=6
+CHAINQ_RPC_ETHEREUM=

chainq-0.11.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run pytest -q

chainq-0.11.0/.github/workflows/release.yml

@@ -0,0 +1,81 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  npm:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - run: npm install -g npm@latest
+      - run: npm version --no-git-tag-version --allow-same-version "${GITHUB_REF_NAME#v}"
+        working-directory: npm
+      - run: npm publish
+        working-directory: npm
+
+  homebrew:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Wait for PyPI to serve the release
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          for _ in $(seq 1 30); do
+            curl -fsS "https://pypi.org/pypi/chainq/$VERSION/json" >/dev/null && exit 0
+            sleep 10
+          done
+          echo "PyPI never served chainq $VERSION" >&2
+          exit 1
+      - name: Bump tap formula
+        env:
+          TAP_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          git clone "https://x-access-token:${TAP_TOKEN}@github.com/Sergio-prog/homebrew-tap.git" tap
+          python3 scripts/update_tap_formula.py "$VERSION" tap/Formula/chainq.rb
+          cd tap
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add Formula/chainq.rb
+          git commit -m "chainq $VERSION"
+          git push

chainq-0.11.0/.gitignore

@@ -0,0 +1,8 @@
+.env
+.venv/
+__pycache__/
+.ruff_cache/
+.pytest_cache/
+dist/
+*.egg-info/
+.DS_Store

chainq-0.11.0/AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS.md
+
+chainq is an agent-first CLI for onchain and crypto market data. Python 3.12+, uv, Typer, httpx, web3.py. Vision and priorities live in [ROADMAP.md](ROADMAP.md) — keep it in sync when shipping features.
+
+## Rules
+
+- No code comments; code must be self-explanatory.
+- Conventional commits, branches, and PR titles. Never commit, push, or open a PR without the owner's explicit ask.
+- Before any commit: `uv run ruff check .` and `uv run pytest -q` must pass.
+- Live-test every new or changed command against real endpoints (`uv run chainq ...`) — unit tests deliberately don't mock providers.
+- Version is defined only in `pyproject.toml` (read at runtime via importlib.metadata). Bump semver on user-visible changes.
+- `.env` holds real keys and is gitignored; never commit it, never print its values.
+- Data sources, in order of preference: the protocol's official API (Aave GraphQL, Pendle, Hyperliquid/Lighter info APIs) → onchain helper/periphery contracts (most protocols deploy them — e.g. Uniswap v3 factory/pool, Aave UiPoolDataProvider) → third-party indexers (DexScreener, DefiLlama) only for discovery/ranking that the first two can't do. Verify new RPC endpoints and API shapes live before shipping (`eth_chainId`, sample responses) — do not trust remembered addresses or schemas.
+
+## Output contract (do not break)
+
+- Every query command supports `--json`, `-q`, `-v`, and `--format text|json|table|toon`; default text is one human-readable line per result.
+- Errors go to stderr with exit code 1; stdout stays clean for parsing.
+- A new command ships with: the contract flags above, an entry in `skills/chainq/SKILL.md`, and a README example.
+
+## Architecture
+
+- `chainq/cli.py` registers commands; `chainq/commands/*` are thin Typer layers; protocol commands (aave, hl) mount under the `protocols` group.
+- `chainq/providers/*` are HTTP clients (CoinGecko, Hyperliquid, Aave GraphQL) using `chainq/cache.py` (TTL 30–300s, `~/.cache/chainq/`).
+- `chainq/networks.py` and `chainq/tokens.py` are curated registries (checksummed addresses — tests enforce); `chainq/rpc.py` wraps web3 with RPC fallback; `chainq/output.py` owns all formatting.
+- `chainq/update.py` — self-update + once-daily version reminder (disable via `CHAINQ_NO_UPDATE_CHECK`).
+
+## Important files
+
+- `ROADMAP.md` — vision, shipped versions, what to build next.
+- `skills/chainq/SKILL.md` — the agent skill, primary distribution channel; update on any command change.
+- `install.sh` — public installer (uv/pipx from git; switch to PyPI after publishing).

chainq-0.11.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

chainq-0.11.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio-prog
+
+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.

chainq-0.11.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: chainq
+Version: 0.11.0
+Summary: Agent-friendly CLI for onchain and crypto market data: balances, gas, transactions, raw RPC, asset prices, Aave, Hyperliquid.
+Project-URL: Repository, https://github.com/Sergio-prog/chainq
+Project-URL: Issues, https://github.com/Sergio-prog/chainq/issues
+Project-URL: Roadmap, https://github.com/Sergio-prog/chainq/blob/main/ROADMAP.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,blockchain,cli,crypto,defi,ethereum,onchain,web3
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.6
+Requires-Dist: typer>=0.12
+Requires-Dist: web3>=7.6
+Description-Content-Type: text/markdown
+
+# chainq
+
+**One CLI for the crypto world — built for AI agents, pleasant for humans.**
+
+Query asset prices, wallet balances, gas, transactions, raw EVM RPC, Aave markets, and Hyperliquid perps from a single tool. Zero setup: curated public RPC endpoints with automatic fallback are built in, and no command below needs an API key.
+
+```console
+$ chainq price eth btc hype
+ETH (Ethereum): $1,691.88  24h +4.82%  mcap $204.11B
+BTC (Bitcoin): $61,302.00  24h +1.85%  mcap $1.23T
+HYPE (Hyperliquid): $65.79  24h +4.38%  mcap $14.63B
+
+$ chainq balance vitalik.eth
+vitalik.eth (0xd8dA…6045) on Ethereum: 5.6955 ETH (~$9,635.87)
+
+$ chainq protocols aave markets -n base --format table -l 3
+network: base
+market  symbol  supply_apy_pct  borrow_apy_pct    supplied_usd  utilization_pct
+------  ------  --------------  --------------  --------------  ---------------
+Base    USDC            3.1684          4.2507  176,010,037.57          83.2569
+Base    WETH            1.5411          2.2608  160,504,459.31          80.4814
+Base    cbBTC           0.0149          0.7126  144,452,332.80           4.2015
+```
+
+## Why
+
+Agents are terrible at juggling five different APIs, auth schemes, and SDKs — and great at running one predictable CLI. chainq gives every command three output modes:
+
+| Mode | Flag | Output |
+|---|---|---|
+| human | *(default)* | one readable line per result |
+| machine | `--json` | structured JSON for parsing |
+| table | `--format table` | aligned columns for humans scanning lists |
+| toon | `--format toon` | compact tabular text — fewer tokens than JSON for LLM contexts |
+| pipe | `-q` | bare primary value only |
+
+Plus `-v` for provenance (RPC endpoint used, data source, explorer links). Errors go to stderr with exit code 1. Responses are cached briefly (30–60s) so repeated queries stay fast and under rate limits.
+
+## Install
+
+One-liner:
+
+```bash
+curl -LsSf https://raw.githubusercontent.com/Sergio-prog/chainq/main/install.sh | sh
+```
+
+Homebrew:
+
+```bash
+brew install sergio-prog/tap/chainq
+```
+
+No install at all — via npx (needs [uv](https://docs.astral.sh/uv/) or pipx on PATH):
+
+```bash
+npx chainq price eth btc
+```
+
+Or directly with uv / pipx:
+
+```bash
+uv tool install chainq
+pipx install chainq
+```
+
+From source:
+
+```bash
+git clone https://github.com/Sergio-prog/chainq && cd chainq
+uv tool install .
+```
+
+Requires Python 3.12+ (the install script bootstraps uv, which handles that for you). Update any time with `chainq update` — chainq also checks for new versions once a day and prints a reminder, homebrew/pnpm style. Shell tab-completion: `chainq --install-completion`.
+
+## Commands
+
+### Market data (CoinGecko)
+
+```bash
+chainq price eth btc sol         # spot price, 24h change, market cap
+chainq price 0xTokenAddress      # any token by contract address (DexScreener fallback for long-tail)
+chainq trending                  # trending assets right now
+chainq stables                   # stablecoins by mcap: peg price, supply changes, mechanism
+chainq asset ethena              # full profile: price, mcap/FDV, supply, ATH, links
+chainq search "sky protocol"     # resolve fuzzy names to asset ids
+```
+
+### Onchain (EVM)
+
+```bash
+chainq networks                                       # supported networks and aliases
+chainq balance vitalik.eth                            # native balance, ENS supported
+chainq balance 0x... --coin usdt -n arbitrum          # ERC-20 by symbol or contract address
+chainq portfolio vitalik.eth                          # all networks: native + known tokens, USD total
+chainq gas -n base                                    # gas price, base fee, transfer cost in USD
+chainq tx 0xHASH -n ethereum                          # status, parties, value, fee, block
+chainq rpc eth_blockNumber -n optimism                # raw JSON-RPC escape hatch
+```
+
+25 networks: **ethereum, arbitrum, base, optimism, polygon, bsc, avalanche, gnosis, unichain, linea, scroll, zksync, mantle, blast, sonic, berachain, worldchain, ink, soneium, celo, sei, hyperevm, monad, plasma, katana** — by key, alias (`eth`, `arb`, `op`, ...), or chain id. Multiple public RPCs per network are tried in order; override with `CHAINQ_RPC_<NETWORK>`.
+
+### Protocols
+
+Aave v3:
+
+```bash
+chainq protocols aave markets -n ethereum         # reserves: supply/borrow APY, size, utilization
+chainq protocols aave markets -c usdc -n base     # one asset across markets
+chainq protocols aave markets -s borrow-apy       # sort: supplied | supply-apy | borrow-apy | utilization
+```
+
+Uniswap and Pendle:
+
+```bash
+chainq protocols uniswap pool weth usdc           # onchain pool state: v2+v3+v4, price + reserves per fee tier
+chainq protocols uniswap pool eth usdc -V v4      # native-currency v4 pools; -V v2|v3|v4|all
+chainq protocols uniswap pool 0xPoolAddress       # one pool by address, v2/v3 auto-detected
+chainq protocols uniswap pools "weth usdc"        # pool discovery: price, 24h volume, liquidity, v2/v3/v4
+chainq protocols uniswap stats                    # protocol TVL + volumes
+chainq protocols pendle markets -s implied-apy    # yield markets: implied APY, LP APY, expiry
+```
+
+Sky and Ethena:
+
+```bash
+chainq protocols sky rate                         # Sky Savings Rate (sUSDS) + legacy DSR, onchain
+chainq protocols ethena yield                     # sUSDe APY, protocol yield, USDe supply/peg
+```
+
+Hyperliquid (public data, incl. HIP-3 builder dexs and HIP-4 outcome markets):
+
+```bash
+chainq protocols hl price BTC ETH                 # perps: mark price, 24h change, volume, OI, funding
+chainq protocols hl markets -s oi                 # top perp markets by volume | oi | funding | change
+chainq protocols hl funding                       # most extreme funding rates (hourly + APR)
+chainq protocols hl positions 0xADDRESS           # perp account: value, margin, positions with PnL
+chainq protocols hl dexs                          # HIP-3 builder-deployed perp dexs
+chainq protocols hl markets --dex xyz             # markets on a builder dex (tokenized stocks etc.)
+chainq protocols hl outcomes "world cup"          # HIP-4 prediction markets with live Yes/No prices
+chainq protocols hl spot price HYPE               # spot pairs: price, 24h change, volume, mcap
+chainq protocols hl spot markets                  # top spot markets by volume
+chainq protocols hl spot balances 0xADDRESS       # spot token balances with USD values
+```
+
+Morpho and DefiLlama:
+
+```bash
+chainq protocols morpho markets -c usdc -n base   # Morpho lending markets: APYs, lltv, utilization
+chainq protocols morpho vaults -c usdc            # Morpho vaults: APY, TVL
+chainq protocols llama protocol lido              # any protocol's TVL/fees/volume via DefiLlama
+chainq protocols llama top -c Lending             # top protocols by TVL
+chainq protocols llama chains                     # chains ranked by DeFi TVL
+```
+
+NFTs (OpenSea):
+
+```bash
+chainq nft floor pudgypenguins azuki              # floor price (native + USD), 24h volume, owners
+chainq nft collection pudgypenguins               # profile: floor, supply, volumes, contract, links
+chainq nft top -s volume                          # top collections (requires OpenSea API key)
+```
+
+Lighter (public data):
+
+```bash
+chainq protocols lighter markets -s oi            # perp markets: last price, volume, OI, funding
+chainq protocols lighter price BTC ETH            # single markets
+chainq protocols lighter funding                  # funding rates (hourly + APR)
+chainq protocols lighter positions 0xADDRESS      # account value, collateral, open positions
+```
+
+## Configuration
+
+Everything works without configuration. To persist settings, use `chainq config`:
+
+```bash
+chainq config set coingecko-api-key CG-xxxx
+chainq config set chainq-rpc-ethereum https://my-node.example.com
+chainq config list        # secrets masked; --show-secrets to reveal
+```
+
+Values live in `~/.config/chainq/.env`; plain env vars and a `.env` in cwd work too:
+
+| Variable | Purpose |
+|---|---|
+| `COINGECKO_API_KEY` | raises CoinGecko rate limits (free demo key works) |
+| `CHAINQ_RPC_<NETWORK>` | custom RPC endpoint, tried first (e.g. `CHAINQ_RPC_ETHEREUM`) |
+| `CHAINQ_HTTP_TIMEOUT` / `CHAINQ_RPC_TIMEOUT` | timeouts in seconds |
+| `CHAINQ_NO_UPDATE_CHECK` | disable the daily update check |
+| `OPENSEA_API_KEY` | unlocks `nft top` and long-tail collection slugs |
+
+## For AI agents
+
+chainq ships a [skill](skills/chainq/SKILL.md) that teaches agents when and how to use it:
+
+```bash
+npx skills add Sergio-prog/chainq
+```
+
+No skill installed? Agents can self-discover everything via `chainq -h` and `chainq <command> -h`.
+
+## Roadmap
+
+NFT floors, Uniswap pools, stablecoin protocols (Sky, Ethena), portfolio sweep, Solana, and more — see [ROADMAP.md](ROADMAP.md).
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+[MIT](LICENSE)

chainq-0.11.0/README.md

@@ -0,0 +1,216 @@
+# chainq
+
+**One CLI for the crypto world — built for AI agents, pleasant for humans.**
+
+Query asset prices, wallet balances, gas, transactions, raw EVM RPC, Aave markets, and Hyperliquid perps from a single tool. Zero setup: curated public RPC endpoints with automatic fallback are built in, and no command below needs an API key.
+
+```console
+$ chainq price eth btc hype
+ETH (Ethereum): $1,691.88  24h +4.82%  mcap $204.11B
+BTC (Bitcoin): $61,302.00  24h +1.85%  mcap $1.23T
+HYPE (Hyperliquid): $65.79  24h +4.38%  mcap $14.63B
+
+$ chainq balance vitalik.eth
+vitalik.eth (0xd8dA…6045) on Ethereum: 5.6955 ETH (~$9,635.87)
+
+$ chainq protocols aave markets -n base --format table -l 3
+network: base
+market  symbol  supply_apy_pct  borrow_apy_pct    supplied_usd  utilization_pct
+------  ------  --------------  --------------  --------------  ---------------
+Base    USDC            3.1684          4.2507  176,010,037.57          83.2569
+Base    WETH            1.5411          2.2608  160,504,459.31          80.4814
+Base    cbBTC           0.0149          0.7126  144,452,332.80           4.2015
+```
+
+## Why
+
+Agents are terrible at juggling five different APIs, auth schemes, and SDKs — and great at running one predictable CLI. chainq gives every command three output modes:
+
+| Mode | Flag | Output |
+|---|---|---|
+| human | *(default)* | one readable line per result |
+| machine | `--json` | structured JSON for parsing |
+| table | `--format table` | aligned columns for humans scanning lists |
+| toon | `--format toon` | compact tabular text — fewer tokens than JSON for LLM contexts |
+| pipe | `-q` | bare primary value only |
+
+Plus `-v` for provenance (RPC endpoint used, data source, explorer links). Errors go to stderr with exit code 1. Responses are cached briefly (30–60s) so repeated queries stay fast and under rate limits.
+
+## Install
+
+One-liner:
+
+```bash
+curl -LsSf https://raw.githubusercontent.com/Sergio-prog/chainq/main/install.sh | sh
+```
+
+Homebrew:
+
+```bash
+brew install sergio-prog/tap/chainq
+```
+
+No install at all — via npx (needs [uv](https://docs.astral.sh/uv/) or pipx on PATH):
+
+```bash
+npx chainq price eth btc
+```
+
+Or directly with uv / pipx:
+
+```bash
+uv tool install chainq
+pipx install chainq
+```
+
+From source:
+
+```bash
+git clone https://github.com/Sergio-prog/chainq && cd chainq
+uv tool install .
+```
+
+Requires Python 3.12+ (the install script bootstraps uv, which handles that for you). Update any time with `chainq update` — chainq also checks for new versions once a day and prints a reminder, homebrew/pnpm style. Shell tab-completion: `chainq --install-completion`.
+
+## Commands
+
+### Market data (CoinGecko)
+
+```bash
+chainq price eth btc sol         # spot price, 24h change, market cap
+chainq price 0xTokenAddress      # any token by contract address (DexScreener fallback for long-tail)
+chainq trending                  # trending assets right now
+chainq stables                   # stablecoins by mcap: peg price, supply changes, mechanism
+chainq asset ethena              # full profile: price, mcap/FDV, supply, ATH, links
+chainq search "sky protocol"     # resolve fuzzy names to asset ids
+```
+
+### Onchain (EVM)
+
+```bash
+chainq networks                                       # supported networks and aliases
+chainq balance vitalik.eth                            # native balance, ENS supported
+chainq balance 0x... --coin usdt -n arbitrum          # ERC-20 by symbol or contract address
+chainq portfolio vitalik.eth                          # all networks: native + known tokens, USD total
+chainq gas -n base                                    # gas price, base fee, transfer cost in USD
+chainq tx 0xHASH -n ethereum                          # status, parties, value, fee, block
+chainq rpc eth_blockNumber -n optimism                # raw JSON-RPC escape hatch
+```
+
+25 networks: **ethereum, arbitrum, base, optimism, polygon, bsc, avalanche, gnosis, unichain, linea, scroll, zksync, mantle, blast, sonic, berachain, worldchain, ink, soneium, celo, sei, hyperevm, monad, plasma, katana** — by key, alias (`eth`, `arb`, `op`, ...), or chain id. Multiple public RPCs per network are tried in order; override with `CHAINQ_RPC_<NETWORK>`.
+
+### Protocols
+
+Aave v3:
+
+```bash
+chainq protocols aave markets -n ethereum         # reserves: supply/borrow APY, size, utilization
+chainq protocols aave markets -c usdc -n base     # one asset across markets
+chainq protocols aave markets -s borrow-apy       # sort: supplied | supply-apy | borrow-apy | utilization
+```
+
+Uniswap and Pendle:
+
+```bash
+chainq protocols uniswap pool weth usdc           # onchain pool state: v2+v3+v4, price + reserves per fee tier
+chainq protocols uniswap pool eth usdc -V v4      # native-currency v4 pools; -V v2|v3|v4|all
+chainq protocols uniswap pool 0xPoolAddress       # one pool by address, v2/v3 auto-detected
+chainq protocols uniswap pools "weth usdc"        # pool discovery: price, 24h volume, liquidity, v2/v3/v4
+chainq protocols uniswap stats                    # protocol TVL + volumes
+chainq protocols pendle markets -s implied-apy    # yield markets: implied APY, LP APY, expiry
+```
+
+Sky and Ethena:
+
+```bash
+chainq protocols sky rate                         # Sky Savings Rate (sUSDS) + legacy DSR, onchain
+chainq protocols ethena yield                     # sUSDe APY, protocol yield, USDe supply/peg
+```
+
+Hyperliquid (public data, incl. HIP-3 builder dexs and HIP-4 outcome markets):
+
+```bash
+chainq protocols hl price BTC ETH                 # perps: mark price, 24h change, volume, OI, funding
+chainq protocols hl markets -s oi                 # top perp markets by volume | oi | funding | change
+chainq protocols hl funding                       # most extreme funding rates (hourly + APR)
+chainq protocols hl positions 0xADDRESS           # perp account: value, margin, positions with PnL
+chainq protocols hl dexs                          # HIP-3 builder-deployed perp dexs
+chainq protocols hl markets --dex xyz             # markets on a builder dex (tokenized stocks etc.)
+chainq protocols hl outcomes "world cup"          # HIP-4 prediction markets with live Yes/No prices
+chainq protocols hl spot price HYPE               # spot pairs: price, 24h change, volume, mcap
+chainq protocols hl spot markets                  # top spot markets by volume
+chainq protocols hl spot balances 0xADDRESS       # spot token balances with USD values
+```
+
+Morpho and DefiLlama:
+
+```bash
+chainq protocols morpho markets -c usdc -n base   # Morpho lending markets: APYs, lltv, utilization
+chainq protocols morpho vaults -c usdc            # Morpho vaults: APY, TVL
+chainq protocols llama protocol lido              # any protocol's TVL/fees/volume via DefiLlama
+chainq protocols llama top -c Lending             # top protocols by TVL
+chainq protocols llama chains                     # chains ranked by DeFi TVL
+```
+
+NFTs (OpenSea):
+
+```bash
+chainq nft floor pudgypenguins azuki              # floor price (native + USD), 24h volume, owners
+chainq nft collection pudgypenguins               # profile: floor, supply, volumes, contract, links
+chainq nft top -s volume                          # top collections (requires OpenSea API key)
+```
+
+Lighter (public data):
+
+```bash
+chainq protocols lighter markets -s oi            # perp markets: last price, volume, OI, funding
+chainq protocols lighter price BTC ETH            # single markets
+chainq protocols lighter funding                  # funding rates (hourly + APR)
+chainq protocols lighter positions 0xADDRESS      # account value, collateral, open positions
+```
+
+## Configuration
+
+Everything works without configuration. To persist settings, use `chainq config`:
+
+```bash
+chainq config set coingecko-api-key CG-xxxx
+chainq config set chainq-rpc-ethereum https://my-node.example.com
+chainq config list        # secrets masked; --show-secrets to reveal
+```
+
+Values live in `~/.config/chainq/.env`; plain env vars and a `.env` in cwd work too:
+
+| Variable | Purpose |
+|---|---|
+| `COINGECKO_API_KEY` | raises CoinGecko rate limits (free demo key works) |
+| `CHAINQ_RPC_<NETWORK>` | custom RPC endpoint, tried first (e.g. `CHAINQ_RPC_ETHEREUM`) |
+| `CHAINQ_HTTP_TIMEOUT` / `CHAINQ_RPC_TIMEOUT` | timeouts in seconds |
+| `CHAINQ_NO_UPDATE_CHECK` | disable the daily update check |
+| `OPENSEA_API_KEY` | unlocks `nft top` and long-tail collection slugs |
+
+## For AI agents
+
+chainq ships a [skill](skills/chainq/SKILL.md) that teaches agents when and how to use it:
+
+```bash
+npx skills add Sergio-prog/chainq
+```
+
+No skill installed? Agents can self-discover everything via `chainq -h` and `chainq <command> -h`.
+
+## Roadmap
+
+NFT floors, Uniswap pools, stablecoin protocols (Sky, Ethena), portfolio sweep, Solana, and more — see [ROADMAP.md](ROADMAP.md).
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+[MIT](LICENSE)

chainq-0.11.0/ROADMAP.md

@@ -0,0 +1,45 @@
+# Roadmap
+
+## Vision
+
+Software for agents, not just people. chainq is one universal CLI where any agent (or human) can query the crypto world: RPC state on popular networks with good predefined endpoints, asset prices and metadata, and aggregated data from major protocols — with zero setup, one-line human output, and `--json` everywhere. Distribution is skill-first: a Claude Code skill instead of an MCP server, because a CLI is self-documenting, composable, costs no context until used, and works in any agent with a shell.
+
+## Shipped
+
+- **v0.1** — 9 EVM networks with curated fallback RPCs; `balance` (native + ERC-20, ENS), `gas`, `tx`, raw `rpc`; CoinGecko `price`/`asset`/`search`; Hyperliquid perps (`hl price/markets/funding/positions`); `--json` / `-q` / `-v` output contract; agent skill.
+- **v0.2** — Aave v3 markets (official GraphQL API); TTL cache; `chainq update` + daily new-version reminder; `install.sh`.
+- **v0.3** — `protocols` command group (aave, hl); Hyperliquid spot (prices, markets, balances); `trending`; `--format table|toon` output formats; AGENTS.md; banner installer.
+- **v0.4** — Uniswap (pools via DexScreener, protocol stats via DefiLlama) and Pendle (active markets, implied/LP APY) under `protocols`.
+- **v0.5** — 25 networks (added linea, scroll, zksync, mantle, blast, sonic, berachain, worldchain, ink, soneium, celo, sei, hyperevm, monad, plasma, katana); onchain Uniswap v3 `pool` command (factory + slot0); Lighter perps (markets, price, funding, positions); Hyperliquid HIP-3 builder dexs (`hl dexs`, `--dex`) and HIP-4 outcome markets (`hl outcomes`); skill install via `npx skills add`.
+- **v0.6** — onchain Uniswap `pool` covers v2 + v3 + v4 (v2 pairs via getReserves, v4 via StateView + computed poolId, native-currency support with `eth`).
+- **v0.7** — address-based discovery: `price`/`asset` accept token contract addresses (DexScreener locates the chain → CoinGecko contract lookup → DexScreener price fallback for long-tail tokens); `uniswap pool` accepts a bare pool address with v2/v3 auto-detection.
+- **v0.8** — Morpho (markets + vaults via official GraphQL API); DefiLlama adapter (`llama protocol/top/chains` for any protocol); `chainq config` command; HTTP retry with backoff on all providers; parallel RPC endpoint racing; shell completions.
+- **v0.9** — NFTs via OpenSea (`nft floor/collection/top`): floors with USD conversion, volumes, owners, supply; keyless for well-known collections, API key unlocks `top` and long-tail slugs.
+- **v0.10** — stablecoins: `stables` overview (mcap ranking, peg price, supply changes via DefiLlama stablecoins API), `sky rate` (SSR + legacy DSR read onchain), `ethena yield` (sUSDe APY via official API, USDe supply/peg).
+- **v0.11** — `portfolio`: parallel sweep of native + registry tokens across all 25 networks with one batched CoinGecko pricing call, sorted by USD value; `--min-usd` dust filter, `-n` repeatable network filter.
+
+## Next
+
+- **Release channels** — tag-triggered release workflow publishes to PyPI (trusted publishing), npm (`npx chainq` launcher running the pinned Python CLI via uvx), and bumps the Homebrew formula in [Sergio-prog/homebrew-tap](https://github.com/Sergio-prog/homebrew-tap) (needs `TAP_GITHUB_TOKEN` secret). One-time owner setup: PyPI pending trusted publisher, first `npm publish`, tap PAT.
+- **Historical data** — `candles <asset> --days 30` (CoinGecko OHLC), `price <asset> --at 2025-01-01`, Hyperliquid funding history (`fundingHistory` info endpoint). Agents constantly want "price N days ago" and can't get it today.
+- **Portfolio depth** — fold Hyperliquid perp/spot balances (providers already exist) and Aave/Morpho supplied positions into `portfolio` behind a `--defi` flag; auto token lists per network from CoinGecko (top ~50 by mcap, cached daily) so the sweep catches far more than the curated registry.
+- **Gas across all networks** — `gas --all`: one parallel sweep (reuse the portfolio executor) answering "where is it cheapest to transact right now".
+- **Solana** — read-only first pass: SOL balance, SPL token accounts with USD values, prices already work via CoinGecko. Biggest missing chain; needs its own RPC pool (no web3.py).
+
+## Later
+
+- Address intelligence: `chainq address 0x...` — contract vs EOA, deploy date, tx count, verified source, token/NFT holdings summary.
+- Generic ERC-4626 inspector: `chainq vault 0xADDR -n base` — asset, share price, APY from share-price delta, TVL; covers thousands of yield vaults with zero per-protocol work.
+- NFT: wallet holdings and collection-by-contract-address lookup (both need a valid OpenSea key), floor cross-check via a second marketplace.
+- CEX spot prices via ccxt as a CoinGecko alternative/cross-check.
+- More protocols: Lido/staking yields (stETH APR), Curve pools, bridge status.
+- Watch/stream mode (`chainq gas --watch`) and threshold alerts (reuse PriceAlerts bot).
+- Thin MCP wrapper over the CLI if demand appears from non-shell agents.
+
+## Engineering improvements
+
+- Structured error output in `--json` mode (`{"error": ...}` on stdout) so agents can branch on failures without parsing stderr.
+- Multicall3 batching for `portfolio` and `uniswap pool` — one `eth_call` per network instead of one per token/tier; Multicall3 is deployed at the same address on all 25 networks.
+- Versioned CHANGELOG generated from conventional commits.
+- Live smoke-test suite behind a pytest marker (`-m live`) exercising one command per provider, run on a weekly scheduled CI job to catch upstream API drift.
+- Cross-platform check: Windows terminal output (the banner and `…` glyphs) and CI matrix entry.