alloc-context 0.2.4__tar.gz → 0.2.6__tar.gz

{alloc_context-0.2.4 → alloc_context-0.2.6}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: alloc-context
-Version: 0.2.4
-Summary: Portfolio-aware crypto context for agents — holdings-scoped market, sentiment, optional allocation analysis
+Version: 0.2.6
+Summary: Portfolio-aware crypto context — CEX or wallet holdings, holdings-scoped market, optional allocation analysis
 License: Elastic-2.0
 Project-URL: Homepage, https://mcp.alloc-context.com/llms.txt
 Project-URL: Documentation, https://github.com/AllocContext/alloc-context/blob/main/docs/agent-integration.md
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/AllocContext/alloc-context
 Project-URL: Issues, https://github.com/AllocContext/alloc-context/issues
 Project-URL: Changelog, https://github.com/AllocContext/alloc-context/releases
 Project-URL: MCP Server, https://mcp.alloc-context.com/mcp
-Keywords: mcp,x402,holdings,portfolio,crypto,cryptocurrency,bitcoin,ethereum,agents,allocation,rebalance,coinbase,kraken
+Keywords: mcp,x402,holdings,portfolio,crypto,cryptocurrency,bitcoin,ethereum,agents,allocation,rebalance,coinbase,kraken,wallet,defi
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -73,9 +73,10 @@ pip install "alloc-context[mcp,hosted]"
 **2. User config**
 
 Copy [config/user.example.yaml](config/user.example.yaml) to
-`~/.config/alloc-context/user.yaml`. Add read-only exchange keys for portfolio
-discovery (optional) and an x402 payer for hosted market context. See
-[user-config.md](docs/user-config.md).
+`~/.config/alloc-context/user.yaml`. For portfolio discovery (optional): read-only
+CEX keys (e.g. Coinbase, Kraken) in user config, or call hosted
+`get_portfolio_state` with `exchange=wallet` and a public EVM address. Add an x402
+payer for hosted market context. See [user-config.md](docs/user-config.md).
 
 **3. MCP config**
 
@@ -101,9 +102,9 @@ Use an absolute path for `--user-config`. Example:
 
 **4. Ask your agent**
 
-Call `get_context_bundle` for a full snapshot (holdings when keys are set,
-market/sentiment/macro via hosted upstream). Pure math tools
-(`check_allocation_band`, `get_rebalance_plan`) work without exchange keys.
+Call `get_context_bundle` for a full snapshot (holdings when a portfolio source
+is configured, market/sentiment/macro via hosted upstream). Pure math tools
+(`check_allocation_band`, `get_rebalance_plan`) work without portfolio credentials.
 
 Full setup guide: [cursor-mcp.md](docs/cursor-mcp.md). Sample responses:
 [examples.md](docs/examples.md).
@@ -135,7 +136,7 @@ combines local portfolio reads with this upstream for market context.
 | `get_rebalance_plan` | USD rebalance moves from allocation, target, and NAV |
 | `check_allocation_band` | Drift vs target and whether allocation is outside the band |
 | `check_allocation_bands` | Batch band checks for multiple target scenarios |
-| `get_portfolio_state` | Live NAV and holdings (e.g. Coinbase, Kraken read-only keys) |
+| `get_portfolio_state` | Live NAV and holdings (CEX keys or public EVM wallet address) |
 
 Market context is **holdings-scoped**: band assets (BTC/ETH) use OHLC bars; alt
 holdings (e.g. HYPE) use quote snapshots when cached. The bridge auto-scopes

{alloc_context-0.2.4 → alloc_context-0.2.6}/README.md

@@ -28,9 +28,10 @@ pip install "alloc-context[mcp,hosted]"
 **2. User config**
 
 Copy [config/user.example.yaml](config/user.example.yaml) to
-`~/.config/alloc-context/user.yaml`. Add read-only exchange keys for portfolio
-discovery (optional) and an x402 payer for hosted market context. See
-[user-config.md](docs/user-config.md).
+`~/.config/alloc-context/user.yaml`. For portfolio discovery (optional): read-only
+CEX keys (e.g. Coinbase, Kraken) in user config, or call hosted
+`get_portfolio_state` with `exchange=wallet` and a public EVM address. Add an x402
+payer for hosted market context. See [user-config.md](docs/user-config.md).
 
 **3. MCP config**
 
@@ -56,9 +57,9 @@ Use an absolute path for `--user-config`. Example:
 
 **4. Ask your agent**
 
-Call `get_context_bundle` for a full snapshot (holdings when keys are set,
-market/sentiment/macro via hosted upstream). Pure math tools
-(`check_allocation_band`, `get_rebalance_plan`) work without exchange keys.
+Call `get_context_bundle` for a full snapshot (holdings when a portfolio source
+is configured, market/sentiment/macro via hosted upstream). Pure math tools
+(`check_allocation_band`, `get_rebalance_plan`) work without portfolio credentials.
 
 Full setup guide: [cursor-mcp.md](docs/cursor-mcp.md). Sample responses:
 [examples.md](docs/examples.md).
@@ -90,7 +91,7 @@ combines local portfolio reads with this upstream for market context.
 | `get_rebalance_plan` | USD rebalance moves from allocation, target, and NAV |
 | `check_allocation_band` | Drift vs target and whether allocation is outside the band |
 | `check_allocation_bands` | Batch band checks for multiple target scenarios |
-| `get_portfolio_state` | Live NAV and holdings (e.g. Coinbase, Kraken read-only keys) |
+| `get_portfolio_state` | Live NAV and holdings (CEX keys or public EVM wallet address) |
 
 Market context is **holdings-scoped**: band assets (BTC/ETH) use OHLC bars; alt
 holdings (e.g. HYPE) use quote snapshots when cached. The bridge auto-scopes

{alloc_context-0.2.4 → alloc_context-0.2.6}/alloc_context.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: alloc-context
-Version: 0.2.4
-Summary: Portfolio-aware crypto context for agents — holdings-scoped market, sentiment, optional allocation analysis
+Version: 0.2.6
+Summary: Portfolio-aware crypto context — CEX or wallet holdings, holdings-scoped market, optional allocation analysis
 License: Elastic-2.0
 Project-URL: Homepage, https://mcp.alloc-context.com/llms.txt
 Project-URL: Documentation, https://github.com/AllocContext/alloc-context/blob/main/docs/agent-integration.md
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/AllocContext/alloc-context
 Project-URL: Issues, https://github.com/AllocContext/alloc-context/issues
 Project-URL: Changelog, https://github.com/AllocContext/alloc-context/releases
 Project-URL: MCP Server, https://mcp.alloc-context.com/mcp
-Keywords: mcp,x402,holdings,portfolio,crypto,cryptocurrency,bitcoin,ethereum,agents,allocation,rebalance,coinbase,kraken
+Keywords: mcp,x402,holdings,portfolio,crypto,cryptocurrency,bitcoin,ethereum,agents,allocation,rebalance,coinbase,kraken,wallet,defi
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -73,9 +73,10 @@ pip install "alloc-context[mcp,hosted]"
 **2. User config**
 
 Copy [config/user.example.yaml](config/user.example.yaml) to
-`~/.config/alloc-context/user.yaml`. Add read-only exchange keys for portfolio
-discovery (optional) and an x402 payer for hosted market context. See
-[user-config.md](docs/user-config.md).
+`~/.config/alloc-context/user.yaml`. For portfolio discovery (optional): read-only
+CEX keys (e.g. Coinbase, Kraken) in user config, or call hosted
+`get_portfolio_state` with `exchange=wallet` and a public EVM address. Add an x402
+payer for hosted market context. See [user-config.md](docs/user-config.md).
 
 **3. MCP config**
 
@@ -101,9 +102,9 @@ Use an absolute path for `--user-config`. Example:
 
 **4. Ask your agent**
 
-Call `get_context_bundle` for a full snapshot (holdings when keys are set,
-market/sentiment/macro via hosted upstream). Pure math tools
-(`check_allocation_band`, `get_rebalance_plan`) work without exchange keys.
+Call `get_context_bundle` for a full snapshot (holdings when a portfolio source
+is configured, market/sentiment/macro via hosted upstream). Pure math tools
+(`check_allocation_band`, `get_rebalance_plan`) work without portfolio credentials.
 
 Full setup guide: [cursor-mcp.md](docs/cursor-mcp.md). Sample responses:
 [examples.md](docs/examples.md).
@@ -135,7 +136,7 @@ combines local portfolio reads with this upstream for market context.
 | `get_rebalance_plan` | USD rebalance moves from allocation, target, and NAV |
 | `check_allocation_band` | Drift vs target and whether allocation is outside the band |
 | `check_allocation_bands` | Batch band checks for multiple target scenarios |
-| `get_portfolio_state` | Live NAV and holdings (e.g. Coinbase, Kraken read-only keys) |
+| `get_portfolio_state` | Live NAV and holdings (CEX keys or public EVM wallet address) |
 
 Market context is **holdings-scoped**: band assets (BTC/ETH) use OHLC bars; alt
 holdings (e.g. HYPE) use quote snapshots when cached. The bridge auto-scopes

{alloc_context-0.2.4 → alloc_context-0.2.6}/alloc_context.egg-info/SOURCES.txt

@@ -56,6 +56,12 @@ alloccontext/ingest/exchange/live.py
 alloccontext/ingest/exchange/portfolio.py
 alloccontext/ingest/exchange/registry.py
 alloccontext/ingest/exchange/types.py
+alloccontext/ingest/wallet/__init__.py
+alloccontext/ingest/wallet/alchemy.py
+alloccontext/ingest/wallet/chains.py
+alloccontext/ingest/wallet/curated_tokens.py
+alloccontext/ingest/wallet/etherscan.py
+alloccontext/ingest/wallet/portfolio.py
 alloccontext/integrations/__init__.py
 alloccontext/integrations/langchain.py
 alloccontext/mcp/__init__.py
@@ -163,6 +169,9 @@ tests/test_snapshots_and_delta.py
 tests/test_status_report.py
 tests/test_tool_catalog.py
 tests/test_user_config.py
+tests/test_wallet_alchemy.py
+tests/test_wallet_etherscan.py
+tests/test_wallet_portfolio.py
 tests/test_workflows.py
 tests/test_x402_bazaar_dynamic.py
 tests/test_x402_production_check.py

{alloc_context-0.2.4 → alloc_context-0.2.6}/alloccontext/__init__.py

@@ -1,3 +1,3 @@
 """AllocContext — portfolio-aware crypto context for agents (MCP)."""
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"

{alloc_context-0.2.4 → alloc_context-0.2.6}/alloccontext/config.py

@@ -8,6 +8,7 @@ from urllib.parse import urlparse
 
 import yaml
 
+from alloccontext.ingest.wallet.chains import DEFAULT_WALLET_CHAIN_IDS
 from alloccontext.rollup.cluster_config import RollupConfig, load_rollup_config
 
 
@@ -101,6 +102,17 @@ class ExchangesConfig:
         raise ValueError(f"unsupported primary exchange: {self.primary}")
 
 
+@dataclass(frozen=True)
+class WalletConfig:
+    enabled: bool
+    provider: str
+    chain_ids: tuple[int, ...]
+    min_value_usd: float
+    timeout_seconds: float
+    max_retries: int
+    retry_backoff_seconds: float
+
+
 @dataclass(frozen=True)
 class KalshiSeriesConfig:
     asset: str
@@ -175,6 +187,7 @@ class AppConfig:
     ingest: IngestConfig
     kraken: KrakenConfig
     exchanges: ExchangesConfig
+    wallet: WalletConfig
     kalshi: KalshiConfig
     rollup: RollupConfig
     macro: MacroConfig
@@ -240,6 +253,27 @@ def _kraken_config_from_spot(spot: SpotExchangeConfig) -> KrakenConfig:
     )
 
 
+def _load_wallet_config(raw: dict[str, Any]) -> WalletConfig:
+    wallet_raw = raw.get("wallet") or {}
+    chain_ids_raw = wallet_raw.get("chain_ids")
+    if chain_ids_raw:
+        chain_ids = tuple(int(chain_id) for chain_id in chain_ids_raw)
+    else:
+        chain_ids = DEFAULT_WALLET_CHAIN_IDS
+    provider = str(wallet_raw.get("provider") or "alchemy").strip().lower()
+    if provider not in {"alchemy", "etherscan"}:
+        raise ValueError(f"unsupported wallet.provider: {provider}")
+    return WalletConfig(
+        enabled=bool(wallet_raw.get("enabled", True)),
+        provider=provider,
+        chain_ids=chain_ids,
+        min_value_usd=float(wallet_raw.get("min_value_usd") or 1.0),
+        timeout_seconds=float(wallet_raw.get("timeout_seconds") or 20.0),
+        max_retries=int(wallet_raw.get("max_retries") or 3),
+        retry_backoff_seconds=float(wallet_raw.get("retry_backoff_seconds") or 2.0),
+    )
+
+
 def _load_exchanges_config(
     raw: dict[str, Any],
     *,
@@ -319,6 +353,7 @@ def load_config(path: str | Path | None = None) -> AppConfig:
         ingest_sources=ingest_sources,
     )
     kraken = _kraken_config_from_spot(exchanges.kraken)
+    wallet = _load_wallet_config(raw)
 
     return AppConfig(
         paths=PathsConfig(
@@ -340,6 +375,7 @@ def load_config(path: str | Path | None = None) -> AppConfig:
         ),
         kraken=kraken,
         exchanges=exchanges,
+        wallet=wallet,
         kalshi=KalshiConfig(
             use_api=bool(kalshi_raw.get("use_api", True)),
             base_url=_validate_kalshi_base_url(

{alloc_context-0.2.4 → alloc_context-0.2.6}/alloccontext/ingest/asset_registry.py

@@ -13,6 +13,8 @@ COINGECKO_ID_BY_SYMBOL: dict[str, str] = {
     "BTC": "bitcoin",
     "ETH": "ethereum",
     "HYPE": "hyperliquid",
+    "POL": "polygon-ecosystem-token",
+    "MATIC": "polygon-ecosystem-token",
 }
 
 KRAKEN_ASSET_TO_SYMBOL = {

{alloc_context-0.2.4 → alloc_context-0.2.6}/alloccontext/ingest/exchange/live.py

@@ -15,7 +15,8 @@ from alloccontext.mcp.validation import validate_band, validate_target_pct
 from alloccontext.rollup.allocation_analysis import build_allocation_analysis
 from alloccontext.rollup.portfolio_payload import portfolio_dict_from_snapshot
 
-SUPPORTED_EXCHANGES = frozenset({"kraken", "coinbase"})
+SUPPORTED_EXCHANGES = frozenset({"kraken", "coinbase", "wallet"})
+CEX_EXCHANGES = frozenset({"kraken", "coinbase"})
 
 
 class LivePortfolioError(Exception):
@@ -29,6 +30,13 @@ def validate_exchange_id(exchange: str) -> ExchangeId:
     return key  # type: ignore[return-value]
 
 
+def validate_cex_exchange_id(exchange: str) -> ExchangeId:
+    key = exchange.strip().lower()
+    if key not in CEX_EXCHANGES:
+        raise ValueError(f"unsupported exchange: {exchange}")
+    return key  # type: ignore[return-value]
+
+
 def _spot_config(config, exchange_id: ExchangeId):
     if exchange_id == "kraken":
         return config.exchanges.kraken
@@ -40,7 +48,24 @@ def fetch_live_portfolio_snapshot(
     api_key: str,
     api_secret: str,
     config,
+    *,
+    wallet_address: str | None = None,
 ) -> PortfolioSnapshot:
+    if exchange_id == "wallet":
+        from alloccontext.ingest.wallet.portfolio import (
+            WalletPortfolioError,
+            fetch_wallet_portfolio_snapshot,
+        )
+
+        if not wallet_address or not wallet_address.strip():
+            raise LivePortfolioError("wallet_address is required")
+        try:
+            return fetch_wallet_portfolio_snapshot(wallet_address, config)
+        except WalletPortfolioError as exc:
+            raise LivePortfolioError(str(exc)) from exc
+        except ValueError as exc:
+            raise LivePortfolioError(str(exc)) from exc
+
     spot = _spot_config(config, exchange_id)
     resolver_config = quote_resolver_config_from_app(config)
     key = api_key.strip()

{alloc_context-0.2.4 → alloc_context-0.2.6}/alloccontext/ingest/exchange/types.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 from typing import Literal
 
-ExchangeId = Literal["kraken", "coinbase"]
+ExchangeId = Literal["kraken", "coinbase", "wallet"]

alloc_context-0.2.6/alloccontext/ingest/wallet/__init__.py

@@ -0,0 +1,6 @@
+from alloccontext.ingest.wallet.portfolio import (
+    fetch_wallet_portfolio_snapshot,
+    validate_wallet_address,
+)
+
+__all__ = ["fetch_wallet_portfolio_snapshot", "validate_wallet_address"]

alloc_context-0.2.6/alloccontext/ingest/wallet/alchemy.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import requests
+
+from alloccontext.ingest.exchange_http import should_retry_exchange_attempt
+from alloccontext.ingest.wallet.chains import alchemy_networks_for_chain_ids
+
+ALCHEMY_DATA_BASE = "https://api.g.alchemy.com/data/v1"
+
+# Native token metadata is often null; map network slug → band symbol.
+NATIVE_SYMBOL_BY_NETWORK: dict[str, str] = {
+    "eth-mainnet": "ETH",
+    "arb-mainnet": "ETH",
+    "base-mainnet": "ETH",
+    "opt-mainnet": "ETH",
+    "polygon-mainnet": "POL",
+    "matic-mainnet": "POL",
+}
+
+
+class AlchemyError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class AlchemyTokenRow:
+    symbol: str
+    quantity: float
+    price_usd: float | None = None
+    is_native: bool = False
+    token_address: str | None = None
+
+
+class AlchemyClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        timeout_seconds: float = 20.0,
+        max_retries: int = 3,
+        retry_backoff_seconds: float = 2.0,
+    ) -> None:
+        key = api_key.strip()
+        if not key:
+            raise AlchemyError("alchemy_api_key_required")
+        self._api_key = key
+        self._timeout = timeout_seconds
+        self._max_retries = max_retries
+        self._retry_backoff = retry_backoff_seconds
+
+    def token_balances(
+        self,
+        address: str,
+        chain_ids: tuple[int, ...],
+    ) -> list[AlchemyTokenRow]:
+        networks = alchemy_networks_for_chain_ids(chain_ids)
+        url = f"{ALCHEMY_DATA_BASE}/{self._api_key}/assets/tokens/by-address"
+        rows: list[AlchemyTokenRow] = []
+        page_key: str | None = None
+        while True:
+            payload = self._post(
+                url,
+                {
+                    "addresses": [{"address": address, "networks": list(networks)}],
+                    "includeNativeTokens": True,
+                    "includeErc20Tokens": True,
+                    "withMetadata": True,
+                    "withPrices": True,
+                    **({"pageKey": page_key} if page_key else {}),
+                },
+            )
+            data = payload.get("data") or {}
+            tokens = data.get("tokens") or []
+            if not isinstance(tokens, list):
+                break
+            for token in tokens:
+                parsed = _parse_token_row(token)
+                if parsed is not None:
+                    rows.append(parsed)
+            page_key = data.get("pageKey")
+            if not page_key:
+                break
+        return rows
+
+    def _post(self, url: str, body: dict[str, Any]) -> dict[str, Any]:
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = requests.post(
+                    url,
+                    json=body,
+                    headers={"Content-Type": "application/json"},
+                    timeout=self._timeout,
+                )
+                if response.status_code == 429:
+                    raise AlchemyError("alchemy_rate_limit")
+                response.raise_for_status()
+                payload = response.json()
+                if not isinstance(payload, dict):
+                    raise AlchemyError("invalid_alchemy_response")
+                if payload.get("error"):
+                    message = str((payload.get("error") or {}).get("message") or payload)
+                    raise AlchemyError(message)
+                return payload
+            except Exception as exc:  # noqa: BLE001
+                last_exc = exc
+                if attempt >= self._max_retries or not _should_retry_alchemy(exc):
+                    break
+                time.sleep(self._retry_backoff * (attempt + 1))
+        if isinstance(last_exc, AlchemyError):
+            raise last_exc
+        if last_exc is not None:
+            raise AlchemyError(str(last_exc)) from last_exc
+        raise AlchemyError("alchemy_request_failed")
+
+
+def _should_retry_alchemy(exc: Exception) -> bool:
+    if isinstance(exc, AlchemyError):
+        detail = str(exc).lower()
+        if "rate limit" in detail or "rate_limit" in detail:
+            return True
+    return should_retry_exchange_attempt(exc)
+
+
+def _parse_token_row(token: dict[str, Any]) -> AlchemyTokenRow | None:
+    if not isinstance(token, dict):
+        return None
+    network = str(token.get("network") or "")
+    token_address = token.get("tokenAddress")
+    is_native = not token_address
+    metadata = token.get("tokenMetadata") or {}
+    symbol = str(metadata.get("symbol") or "").strip()
+    if not symbol:
+        symbol = NATIVE_SYMBOL_BY_NETWORK.get(network, "")
+    if not symbol or len(symbol) > 20:
+        return None
+    decimals = metadata.get("decimals")
+    if is_native:
+        decimals_int = 18
+    else:
+        if decimals is None:
+            return None
+        try:
+            decimals_int = int(decimals)
+        except (TypeError, ValueError):
+            return None
+    quantity = _parse_hex_balance(str(token.get("tokenBalance") or "0x0"), decimals_int)
+    if quantity <= 0:
+        return None
+    price_usd = _price_usd_per_unit(token.get("tokenPrices"))
+    contract = str(token_address).lower() if token_address else None
+    return AlchemyTokenRow(
+        symbol=symbol,
+        quantity=quantity,
+        price_usd=price_usd,
+        is_native=is_native,
+        token_address=contract,
+    )
+
+
+def _parse_hex_balance(raw: str, decimals: int) -> float:
+    if not raw or raw in {"0x", "0x0"}:
+        return 0.0
+    try:
+        amount = int(raw, 16)
+    except ValueError:
+        return 0.0
+    if amount <= 0:
+        return 0.0
+    return amount / (10**decimals)
+
+
+def _price_usd_per_unit(token_prices: Any) -> float | None:
+    if not isinstance(token_prices, list):
+        return None
+    for row in token_prices:
+        if not isinstance(row, dict):
+            continue
+        if str(row.get("currency") or "").lower() != "usd":
+            continue
+        try:
+            value = float(row.get("value"))
+        except (TypeError, ValueError):
+            continue
+        if value > 0:
+            return value
+    return None

alloc_context-0.2.6/alloccontext/ingest/wallet/chains.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# ADR-012 D1: EVM mainnet + major L2s (deterministic, bounded set).
+DEFAULT_WALLET_CHAIN_IDS: tuple[int, ...] = (1, 42161, 8453, 10, 137)
+
+
+@dataclass(frozen=True)
+class EvmChain:
+    chain_id: int
+    label: str
+    native_symbol: str
+
+
+EVM_CHAINS: dict[int, EvmChain] = {
+    1: EvmChain(chain_id=1, label="ethereum", native_symbol="ETH"),
+    42161: EvmChain(chain_id=42161, label="arbitrum", native_symbol="ETH"),
+    8453: EvmChain(chain_id=8453, label="base", native_symbol="ETH"),
+    10: EvmChain(chain_id=10, label="optimism", native_symbol="ETH"),
+    137: EvmChain(chain_id=137, label="polygon", native_symbol="POL"),
+}
+
+
+# Alchemy Portfolio API network slugs (see dashboard.alchemy.com/chains).
+ALCHEMY_NETWORK_BY_CHAIN_ID: dict[int, str] = {
+    1: "eth-mainnet",
+    42161: "arb-mainnet",
+    8453: "base-mainnet",
+    10: "opt-mainnet",
+    137: "polygon-mainnet",
+}
+
+
+def resolve_wallet_chains(chain_ids: tuple[int, ...]) -> tuple[EvmChain, ...]:
+    unknown = [chain_id for chain_id in chain_ids if chain_id not in EVM_CHAINS]
+    if unknown:
+        raise ValueError(f"unsupported wallet chain_ids: {unknown}")
+    return tuple(EVM_CHAINS[chain_id] for chain_id in chain_ids)
+
+
+def alchemy_networks_for_chain_ids(chain_ids: tuple[int, ...]) -> tuple[str, ...]:
+    unknown = [chain_id for chain_id in chain_ids if chain_id not in ALCHEMY_NETWORK_BY_CHAIN_ID]
+    if unknown:
+        raise ValueError(f"unsupported wallet chain_ids for alchemy: {unknown}")
+    return tuple(ALCHEMY_NETWORK_BY_CHAIN_ID[chain_id] for chain_id in chain_ids)

alloc_context-0.2.6/alloccontext/ingest/wallet/curated_tokens.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from alloccontext.ingest.wallet.chains import DEFAULT_WALLET_CHAIN_IDS
+
+
+@dataclass(frozen=True)
+class CuratedToken:
+    contract: str
+    symbol: str
+    decimals: int
+
+
+# Free-tier Etherscan tokenbalance lookups (addresstokenbalance is API Pro).
+_CURATED_BY_CHAIN: dict[int, tuple[CuratedToken, ...]] = {
+    1: (
+        CuratedToken("0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "USDC", 6),
+        CuratedToken("0xdac17f958d2ee523a2206206994597c13d831ec7", "USDT", 6),
+        CuratedToken("0x6b175474e89094c44da98b954eedeac495271d0f", "DAI", 18),
+        CuratedToken("0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", "WBTC", 8),
+        CuratedToken("0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "WETH", 18),
+    ),
+    42161: (
+        CuratedToken("0xaf88d065e77c8cc2239327c5edb3a432268e5831", "USDC", 6),
+        CuratedToken("0xff970a61a04b1ca14834a43f5de4533ebddb5cc8", "USDC", 6),
+        CuratedToken("0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9", "USDT", 6),
+        CuratedToken("0xda10009cbd5d07dd0cecc66161fc93d7c9000da1", "DAI", 18),
+        CuratedToken("0x2f2a2543b76a4166549f7aab2e75bef0aefc5b0f", "WBTC", 8),
+        CuratedToken("0x82af49447d8a07e3bd95bd0d56f35241523fbab1", "WETH", 18),
+    ),
+    8453: (
+        CuratedToken("0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6),
+        CuratedToken("0xd9aaec86b65d6f9524af1fdb8ae83789d97377ce", "USDC", 6),
+        CuratedToken("0x4200000000000000000000000000000000000006", "WETH", 18),
+        CuratedToken("0x2ae3f1ec7f1f5012cfeab0185bfc2aacee711e6", "CBETH", 18),
+    ),
+    10: (
+        CuratedToken("0x0b2c639c533813c4aa6d0577d8ec5024ba0262b2", "USDC", 6),
+        CuratedToken("0x7f5c764cbc14f9669b88837ca1490cca17c31607", "USDC", 6),
+        CuratedToken("0x94b008aa00543c1307b0b1d40c0e6cbfc7971044", "USDT", 6),
+        CuratedToken("0xda10009cbd5d07dd0cecc66161fc93d7c9000da1", "DAI", 18),
+        CuratedToken("0x68f180fcce6831688e6282403cb1d48dc36a3d3", "WBTC", 8),
+        CuratedToken("0x4200000000000000000000000000000000000006", "WETH", 18),
+    ),
+    137: (
+        CuratedToken("0x3c499c542cef5e3811e1192ce70d8cc03d5c3359", "USDC", 6),
+        CuratedToken("0x2791bca1f2de4661ed88a30c99a7a9449aa84174", "USDC", 6),
+        CuratedToken("0xc2132d05d31c914a87c6611c10748aeb04b58e8f", "USDT", 6),
+        CuratedToken("0x8f3cf7ad23cd3cadbd9735aff958023239c6a063", "DAI", 18),
+        CuratedToken("0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6", "WBTC", 8),
+        CuratedToken("0x7ceb23fd6bc0add59e62ac25578270cff1b9f619", "WETH", 18),
+    ),
+}
+
+
+def curated_tokens_for_chain(chain_id: int) -> tuple[CuratedToken, ...]:
+    return _CURATED_BY_CHAIN.get(chain_id, ())
+
+
+def curated_tokens_for_chains(chain_ids: tuple[int, ...]) -> dict[int, tuple[CuratedToken, ...]]:
+    return {chain_id: curated_tokens_for_chain(chain_id) for chain_id in chain_ids}
+
+
+def default_curated_chain_ids() -> tuple[int, ...]:
+    return DEFAULT_WALLET_CHAIN_IDS