chainq 0.11.0__py3-none-any.whl

chainq/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("chainq")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

chainq/cache.py

@@ -0,0 +1,42 @@
+import hashlib
+import json
+import time
+from pathlib import Path
+
+CACHE_DIR = Path.home() / ".cache" / "chainq"
+CACHE_FILE = CACHE_DIR / "http-cache.json"
+
+
+def key_for(*parts: object) -> str:
+    return hashlib.sha256(json.dumps(parts, sort_keys=True, default=str).encode()).hexdigest()[:24]
+
+
+def _load() -> dict:
+    try:
+        return json.loads(CACHE_FILE.read_text())
+    except Exception:
+        return {}
+
+
+def _store(data: dict) -> None:
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = CACHE_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(data, default=str))
+    tmp.replace(CACHE_FILE)
+
+
+def get(key: str) -> object | None:
+    entry = _load().get(key)
+    if entry and entry.get("expires_at", 0) > time.time():
+        return entry["value"]
+    return None
+
+
+def put(key: str, value: object, ttl: float) -> None:
+    now = time.time()
+    data = {k: v for k, v in _load().items() if v.get("expires_at", 0) > now}
+    data[key] = {"expires_at": now + ttl, "value": value}
+    try:
+        _store(data)
+    except OSError:
+        pass

chainq/cli.py

@@ -0,0 +1,50 @@
+import sys
+
+import httpx
+import typer
+
+from chainq import __version__, update
+from chainq.commands import chain, config, market, nft, portfolio, protocols, stables
+from chainq.errors import ChainqError
+
+app = typer.Typer(
+    add_completion=True,
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help="Agent-friendly CLI for onchain and crypto market data. Every command supports --json, -q, -v.",
+)
+
+app.command()(chain.networks)
+app.command()(chain.balance)
+app.command()(chain.gas)
+app.command()(chain.tx)
+app.command()(chain.rpc)
+app.command()(portfolio.portfolio)
+app.command()(market.price)
+app.command()(market.asset)
+app.command()(market.search)
+app.command()(market.trending)
+app.command()(stables.stables)
+app.command()(update.update)
+app.add_typer(protocols.app, name="protocols")
+app.add_typer(nft.app, name="nft")
+app.add_typer(config.app, name="config")
+
+
+@app.command()
+def version():
+    """Print chainq version."""
+    print(__version__)
+
+
+def run():
+    try:
+        update.maybe_remind()
+        app()
+    except ChainqError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)
+    except httpx.HTTPError as exc:
+        print(f"error: http request failed: {exc}", file=sys.stderr)
+        sys.exit(1)

chainq/commands/aave.py

@@ -0,0 +1,97 @@
+from typing import Annotated
+
+import typer
+
+from chainq.errors import ChainqError
+from chainq.fmt import fmt_pct, humanize_usd
+from chainq.networks import resolve_network
+from chainq.output import FormatOpt, JsonOpt, Out, QuietOpt, VerboseOpt
+from chainq.providers import aave
+
+app = typer.Typer(no_args_is_help=True, help="Aave v3 protocol data (lending markets).")
+
+SORT_KEYS = {
+    "supplied": lambda r: r["supplied_usd"] or 0,
+    "supply-apy": lambda r: r["supply_apy_pct"] or 0,
+    "borrow-apy": lambda r: r["borrow_apy_pct"] or 0,
+    "utilization": lambda r: r["utilization_pct"] or 0,
+}
+
+
+def _market_label(name: str) -> str:
+    return name.removeprefix("AaveV3") or name
+
+
+def _reserve_row(market: dict, reserve: dict) -> dict:
+    supply = reserve.get("supplyInfo") or {}
+    borrow = reserve.get("borrowInfo") or {}
+    return {
+        "market": _market_label(market["name"]),
+        "symbol": (reserve.get("underlyingToken") or {}).get("symbol"),
+        "supply_apy_pct": float(supply["apy"]["value"]) * 100 if supply.get("apy") else None,
+        "borrow_apy_pct": float(borrow["apy"]["value"]) * 100 if borrow.get("apy") else None,
+        "supplied_usd": float(reserve["size"]["usd"]) if reserve.get("size") else None,
+        "borrowed_usd": float(borrow["total"]["usd"]) if borrow.get("total") else None,
+        "available_usd": float(borrow["availableLiquidity"]["usd"]) if borrow.get("availableLiquidity") else None,
+        "utilization_pct": float(borrow["utilizationRate"]["value"]) * 100 if borrow.get("utilizationRate") else None,
+        "collateral": supply.get("canBeCollateral"),
+        "frozen": reserve.get("isFrozen"),
+    }
+
+
+def _row_line(r: dict) -> str:
+    borrow = f"borrow {fmt_pct(r['borrow_apy_pct'], signed=False)}" if r["borrow_apy_pct"] is not None else "not borrowable"
+    util = f"  util {fmt_pct(r['utilization_pct'], signed=False)}" if r["utilization_pct"] is not None else ""
+    return (
+        f"{r['symbol']} [{r['market']}]: supply {fmt_pct(r['supply_apy_pct'], signed=False)}  {borrow}  "
+        f"supplied {humanize_usd(r['supplied_usd'] or 0)}{util}"
+    )
+
+
+@app.command()
+def markets(
+    network: Annotated[str, typer.Option("--network", "-n", help="network key, alias, or chain id")] = "ethereum",
+    coin: Annotated[str | None, typer.Option("--coin", "-c", help="filter by underlying token symbol")] = None,
+    sort: Annotated[str, typer.Option("--sort", "-s", help="supplied | supply-apy | borrow-apy | utilization")] = "supplied",
+    limit: Annotated[int, typer.Option("--limit", "-l")] = 15,
+    json_out: JsonOpt = False,
+    quiet: QuietOpt = False,
+    verbose: VerboseOpt = False,
+    format: FormatOpt = "text",
+):
+    """Aave v3 reserves on a network: supply/borrow APY, size, utilization."""
+    out = Out(json_out, quiet, verbose, format)
+    if sort not in SORT_KEYS:
+        raise ChainqError(f"unknown sort '{sort}' (use: {', '.join(SORT_KEYS)})")
+    net = resolve_network(network)
+    aave_markets = aave.markets(net.chain_id)
+    if not aave_markets:
+        raise ChainqError(f"no Aave v3 market on {net.name}")
+    rows = [
+        _reserve_row(market, reserve)
+        for market in aave_markets
+        for reserve in market.get("reserves") or []
+        if not reserve.get("isPaused")
+    ]
+    if coin:
+        rows = [r for r in rows if (r["symbol"] or "").lower() == coin.lower()]
+        if not rows:
+            raise ChainqError(f"no Aave reserve for '{coin}' on {net.name}")
+    else:
+        rows = sorted(rows, key=SORT_KEYS[sort], reverse=True)[:limit]
+    total = sum(float(m["totalMarketSize"]) for m in aave_markets)
+    header = (
+        f"Aave v3 on {net.name}: {humanize_usd(total)} total market size, "
+        f"{len(aave_markets)} market{'s' if len(aave_markets) != 1 else ''} "
+        f"({', '.join(_market_label(m['name']) for m in aave_markets)})"
+    )
+    out.emit(
+        {"network": net.key, "total_market_size_usd": total, "reserves": rows},
+        [header, *(_row_line(r) for r in rows)],
+        quiet_value="\n".join(f"{r['symbol']}" for r in rows),
+        verbose_lines=[
+            f"{r['symbol']} [{r['market']}]: borrowed {humanize_usd(r['borrowed_usd'] or 0)}, "
+            f"available {humanize_usd(r['available_usd'] or 0)}, collateral {r['collateral']}, frozen {r['frozen']}"
+            for r in rows
+        ],
+    )

chainq/commands/chain.py

@@ -0,0 +1,239 @@
+import json
+from datetime import UTC, datetime
+from decimal import Decimal
+from typing import Annotated
+
+import typer
+from web3.exceptions import TransactionNotFound
+from web3.types import RPCEndpoint
+
+from chainq.errors import ChainqError
+from chainq.fmt import fmt_amount, fmt_gwei, fmt_usd, short_addr
+from chainq.networks import NETWORKS, resolve_network
+from chainq.output import FormatOpt, JsonOpt, Out, QuietOpt, VerboseOpt
+from chainq.providers import coingecko
+from chainq.rpc import connect, erc20, resolve_address
+from chainq.tokens import resolve_token
+
+NetworkOpt = Annotated[str, typer.Option("--network", "-n", help="network key, alias, or chain id")]
+
+
+def networks(
+    json_out: JsonOpt = False, quiet: QuietOpt = False, verbose: VerboseOpt = False, format: FormatOpt = "text"
+):
+    """List supported networks with chain ids and aliases."""
+    out = Out(json_out, quiet, verbose, format)
+    data = [
+        {
+            "key": net.key,
+            "name": net.name,
+            "chain_id": net.chain_id,
+            "native_symbol": net.native_symbol,
+            "aliases": list(net.aliases),
+            "rpc_urls": list(net.rpc_urls),
+            "explorer": net.explorer,
+        }
+        for net in NETWORKS.values()
+    ]
+    lines = [
+        f"{net.key}  (chain id {net.chain_id}, native {net.native_symbol})"
+        + (f"  aliases: {', '.join(net.aliases)}" if net.aliases else "")
+        for net in NETWORKS.values()
+    ]
+    verbose_lines = [f"{net.key}: {', '.join(net.rpc_urls)}" for net in NETWORKS.values()]
+    out.emit(data, lines, quiet_value="\n".join(NETWORKS), verbose_lines=verbose_lines)
+
+
+def balance(
+    address: Annotated[str, typer.Argument(help="wallet address or ENS name")],
+    coin: Annotated[str | None, typer.Option("--coin", "-c", help="token symbol or ERC-20 address; omit for native")] = None,
+    network: NetworkOpt = "ethereum",
+    json_out: JsonOpt = False,
+    quiet: QuietOpt = False,
+    verbose: VerboseOpt = False,
+    format: FormatOpt = "text",
+):
+    """Get native or ERC-20 token balance of an address."""
+    out = Out(json_out, quiet, verbose, format)
+    net = resolve_network(network)
+    addr = resolve_address(address)
+    client = connect(net)
+    if coin is None:
+        wei = client.w3.eth.get_balance(addr)
+        amount = Decimal(wei) / Decimal(10**18)
+        symbol = net.native_symbol
+        price = coingecko.try_price_usd(net.native_coingecko_id)
+        token_address = None
+    else:
+        token_address = resolve_token(coin, net)
+        contract = erc20(client, token_address)
+        decimals = contract.functions.decimals().call()
+        symbol = contract.functions.symbol().call()
+        raw = contract.functions.balanceOf(addr).call()
+        amount = Decimal(raw) / Decimal(10**decimals)
+        cg_id = coingecko.SYMBOL_TO_ID.get(coin.lower()) if not coin.startswith("0x") else None
+        price = coingecko.try_price_usd(cg_id)
+    usd_value = float(amount) * price if price is not None else None
+    data = {
+        "address": addr,
+        "input": address,
+        "network": net.key,
+        "symbol": symbol,
+        "token_address": token_address,
+        "amount": str(amount),
+        "price_usd": price,
+        "value_usd": usd_value,
+    }
+    label = f"{address} ({short_addr(addr)})" if address != addr else short_addr(addr)
+    text = f"{label} on {net.name}: {fmt_amount(amount)} {symbol}"
+    if usd_value is not None:
+        text += f" (~{fmt_usd(usd_value)})"
+    out.emit(
+        data,
+        text,
+        quiet_value=amount,
+        verbose_lines=[
+            f"rpc: {client.url}",
+            f"address: {addr}",
+            *([f"token: {token_address}"] if token_address else []),
+            *([f"price used: {fmt_usd(price)} [coingecko]"] if price is not None else []),
+        ],
+    )
+
+
+def gas(
+    network: NetworkOpt = "ethereum",
+    json_out: JsonOpt = False,
+    quiet: QuietOpt = False,
+    verbose: VerboseOpt = False,
+    format: FormatOpt = "text",
+):
+    """Current gas price, base fee, and estimated native-transfer cost in USD."""
+    out = Out(json_out, quiet, verbose, format)
+    net = resolve_network(network)
+    client = connect(net)
+    gas_price = client.w3.eth.gas_price
+    base_fee = None
+    priority_p50 = None
+    try:
+        hist = client.w3.eth.fee_history(1, "latest", [25, 50, 90])
+        base_fee = hist["baseFeePerGas"][-1]
+        rewards = hist.get("reward") or []
+        if rewards:
+            priority_p50 = rewards[0][1]
+    except Exception:
+        pass
+    price = coingecko.try_price_usd(net.native_coingecko_id)
+    transfer_cost_usd = (21000 * gas_price / 1e18) * price if price is not None else None
+    data = {
+        "network": net.key,
+        "gas_price_wei": gas_price,
+        "gas_price_gwei": gas_price / 1e9,
+        "base_fee_gwei": base_fee / 1e9 if base_fee is not None else None,
+        "priority_fee_p50_gwei": priority_p50 / 1e9 if priority_p50 is not None else None,
+        "native_price_usd": price,
+        "transfer_cost_usd": transfer_cost_usd,
+    }
+    text = f"{net.name} gas: {fmt_gwei(gas_price)}"
+    if base_fee is not None:
+        text += f" (base {fmt_gwei(base_fee)}"
+        text += f", priority p50 {fmt_gwei(priority_p50)})" if priority_p50 is not None else ")"
+    if transfer_cost_usd is not None:
+        text += f" — native transfer ≈ {fmt_usd(transfer_cost_usd)}"
+    out.emit(data, text, quiet_value=gas_price / 1e9, verbose_lines=[f"rpc: {client.url}"])
+
+
+def tx(
+    tx_hash: Annotated[str, typer.Argument(help="transaction hash")],
+    network: NetworkOpt = "ethereum",
+    json_out: JsonOpt = False,
+    quiet: QuietOpt = False,
+    verbose: VerboseOpt = False,
+    format: FormatOpt = "text",
+):
+    """Look up a transaction: status, parties, value, fee, block."""
+    out = Out(json_out, quiet, verbose, format)
+    net = resolve_network(network)
+    client = connect(net)
+    try:
+        transaction = client.w3.eth.get_transaction(tx_hash)
+    except TransactionNotFound:
+        raise ChainqError(f"transaction {tx_hash} not found on {net.name} (check the hash and --network)") from None
+    receipt = None
+    if transaction.get("blockNumber") is not None:
+        try:
+            receipt = client.w3.eth.get_transaction_receipt(tx_hash)
+        except TransactionNotFound:
+            receipt = None
+    if receipt is None:
+        status = "pending"
+    else:
+        status = "success" if receipt["status"] == 1 else "failed"
+    value = Decimal(transaction["value"]) / Decimal(10**18)
+    fee = None
+    if receipt is not None:
+        fee = Decimal(receipt["gasUsed"] * receipt.get("effectiveGasPrice", transaction.get("gasPrice", 0))) / Decimal(10**18)
+    timestamp = None
+    if transaction.get("blockNumber") is not None:
+        block = client.w3.eth.get_block(transaction["blockNumber"])
+        timestamp = datetime.fromtimestamp(block["timestamp"], tz=UTC)
+    price = coingecko.try_price_usd(net.native_coingecko_id)
+    to_address = transaction.get("to")
+    data = {
+        "hash": transaction["hash"].hex(),
+        "network": net.key,
+        "status": status,
+        "from": transaction["from"],
+        "to": to_address,
+        "value": str(value),
+        "value_usd": float(value) * price if price is not None else None,
+        "fee": str(fee) if fee is not None else None,
+        "fee_usd": float(fee) * price if fee is not None and price is not None else None,
+        "block": transaction.get("blockNumber"),
+        "timestamp": timestamp.isoformat() if timestamp else None,
+        "nonce": transaction["nonce"],
+        "gas_used": receipt["gasUsed"] if receipt else None,
+        "gas_limit": transaction["gas"],
+        "explorer": f"{net.explorer}/tx/0x{transaction['hash'].hex().removeprefix('0x')}",
+    }
+    lines = [
+        f"Tx {short_addr(tx_hash)} on {net.name}: {status}",
+        f"  {transaction['from']} → {to_address or 'contract creation'}",
+        f"  value {fmt_amount(value)} {net.native_symbol}"
+        + (f" (~{fmt_usd(data['value_usd'])})" if data["value_usd"] else "")
+        + (f", fee {fmt_amount(fee)} {net.native_symbol}" if fee is not None else "")
+        + (f" (~{fmt_usd(data['fee_usd'])})" if data["fee_usd"] else ""),
+    ]
+    if data["block"] is not None:
+        when = f" at {timestamp.strftime('%Y-%m-%d %H:%M UTC')}" if timestamp else ""
+        lines.append(f"  block {data['block']}{when}")
+    out.emit(
+        data,
+        lines,
+        quiet_value=status,
+        verbose_lines=[
+            f"nonce: {data['nonce']}, gas used: {data['gas_used']}/{data['gas_limit']}",
+            f"explorer: {data['explorer']}",
+            f"rpc: {client.url}",
+        ],
+    )
+
+
+def rpc(
+    method: Annotated[str, typer.Argument(help="JSON-RPC method, e.g. eth_blockNumber")],
+    params: Annotated[list[str] | None, typer.Argument(help="params; JSON literals are parsed, rest stay strings")] = None,
+    network: NetworkOpt = "ethereum",
+):
+    """Raw JSON-RPC escape hatch; prints the JSON result."""
+    net = resolve_network(network)
+    client = connect(net)
+    parsed = []
+    for param in params or []:
+        try:
+            parsed.append(json.loads(param))
+        except json.JSONDecodeError:
+            parsed.append(param)
+    response = client.w3.provider.make_request(RPCEndpoint(method), parsed)
+    if "error" in response:
+        raise ChainqError(f"rpc error from {client.url}: {response['error']}")
+    print(json.dumps(response.get("result"), indent=2, default=str))

chainq/commands/config.py

@@ -0,0 +1,105 @@
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from chainq.errors import ChainqError
+
+app = typer.Typer(no_args_is_help=True, help="Manage chainq configuration (stored in ~/.config/chainq/.env).")
+
+CONFIG_PATH = Path.home() / ".config" / "chainq" / ".env"
+
+KNOWN_KEYS = (
+    "COINGECKO_API_KEY",
+    "OPENSEA_API_KEY",
+    "CHAINQ_HTTP_TIMEOUT",
+    "CHAINQ_RPC_TIMEOUT",
+    "CHAINQ_NO_UPDATE_CHECK",
+    "CHAINQ_RPC_<NETWORK>",
+)
+
+SECRET_MARKERS = ("KEY", "SECRET", "TOKEN", "PASSWORD")
+
+
+def _normalize(key: str) -> str:
+    return key.strip().upper().replace("-", "_")
+
+
+def _read() -> dict[str, str]:
+    values: dict[str, str] = {}
+    if not CONFIG_PATH.exists():
+        return values
+    for line in CONFIG_PATH.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        values[key.strip()] = value.strip()
+    return values
+
+
+def _write(values: dict[str, str]) -> None:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text("".join(f"{k}={v}\n" for k, v in values.items()))
+    CONFIG_PATH.chmod(0o600)
+
+
+def _mask(key: str, value: str) -> str:
+    if not any(marker in key for marker in SECRET_MARKERS) or key == "CHAINQ_NO_UPDATE_CHECK":
+        return value
+    if len(value) > 8:
+        return f"{value[:4]}…{value[-4:]}"
+    return "****"
+
+
+@app.command(name="set")
+def set_(
+    key: Annotated[str, typer.Argument(help="e.g. coingecko-api-key, CHAINQ_RPC_ETHEREUM")],
+    value: Annotated[str, typer.Argument()],
+):
+    """Set a config value (applies to every future chainq run)."""
+    values = _read()
+    normalized = _normalize(key)
+    values[normalized] = value
+    _write(values)
+    print(f"{normalized}={_mask(normalized, value)}  ({CONFIG_PATH})")
+
+
+@app.command()
+def get(key: Annotated[str, typer.Argument()]):
+    """Print one config value."""
+    values = _read()
+    normalized = _normalize(key)
+    if normalized not in values:
+        raise ChainqError(f"{normalized} is not set (see `chainq config list`)")
+    print(values[normalized])
+
+
+@app.command()
+def unset(key: Annotated[str, typer.Argument()]):
+    """Remove a config value."""
+    values = _read()
+    normalized = _normalize(key)
+    if normalized not in values:
+        raise ChainqError(f"{normalized} is not set")
+    del values[normalized]
+    _write(values)
+    print(f"removed {normalized}")
+
+
+@app.command(name="list")
+def list_(show_secrets: Annotated[bool, typer.Option("--show-secrets", help="print secret values in full")] = False):
+    """List configured values (secrets masked by default)."""
+    values = _read()
+    if not values:
+        print(f"no config set ({CONFIG_PATH})")
+        print(f"known keys: {', '.join(KNOWN_KEYS)}")
+        return
+    for key, value in values.items():
+        print(f"{key}={value if show_secrets else _mask(key, value)}")
+
+
+@app.command()
+def path():
+    """Print the config file path."""
+    print(CONFIG_PATH)

chainq/commands/ethena.py

@@ -0,0 +1,40 @@
+import typer
+
+from chainq.fmt import fmt_pct, fmt_usd, humanize_usd
+from chainq.output import FormatOpt, JsonOpt, Out, QuietOpt, VerboseOpt
+from chainq.providers import defillama, ethena
+
+app = typer.Typer(no_args_is_help=True, help="Ethena: sUSDe yield and USDe supply.")
+
+
+def _pct(value: float | None) -> str:
+    return fmt_pct(value, signed=False)
+
+
+@app.command(name="yield")
+def yield_(
+    json_out: JsonOpt = False,
+    quiet: QuietOpt = False,
+    verbose: VerboseOpt = False,
+    format: FormatOpt = "text",
+):
+    """sUSDe staking APY, protocol yield, and USDe supply/peg."""
+    out = Out(json_out, quiet, verbose, format)
+    data = dict(ethena.yields())
+    usde = next((s for s in defillama.stablecoins() if s["symbol"] == "USDe"), None)
+    if usde:
+        data["usde_mcap_usd"] = usde["mcap_usd"]
+        data["usde_price_usd"] = usde["price_usd"]
+    lines = [
+        f"sUSDe yield: {_pct(data['susde_apy_pct'])} APY "
+        f"(30d avg {_pct(data['susde_apy_30d_pct'])}, 90d avg {_pct(data['susde_apy_90d_pct'])})",
+        f"protocol yield: {_pct(data['protocol_yield_pct'])} (30d avg {_pct(data['protocol_yield_30d_pct'])})",
+    ]
+    if usde:
+        lines.append(f"USDe supply: {humanize_usd(data['usde_mcap_usd'] or 0)}, price {fmt_usd(data['usde_price_usd'] or 0)}")
+    out.emit(
+        data,
+        lines,
+        quiet_value=data["susde_apy_pct"],
+        verbose_lines=[f"yield data updated: {data.get('updated')}", f"source: {ethena.YIELD_URL}"],
+    )