scout

On-chain wallet & protocol intelligence primitives. Registry, fit scoring, activity tracking.

scout is a small Python library for systematic on-chain research. Three composable parts:

• Registry — a curated, queryable database of protocols (Targets) with chain, category, confidence, criteria, contracts, notes, priority. Loaded from YAML so you can edit, fork, and contribute without code changes.
• FitScorer — scores any wallet against any target's criteria (0–100, with met / missing / recommendations). Works for airdrop eligibility, allowlist gating, lending risk, KYC-lite reputation — anywhere you ask "does this wallet match these requirements?"
• WalletTracker — follows wallets across chains and aggregates protocol signals. Etherscan v2 backend by default, pluggable for Alchemy / Covalent / your own indexer.

Install

pip install scout-onchain
# or, with the WalletTracker activity backend:
pip install scout-onchain[activity]

Quick Start

from scout import Registry, FitScorer, WalletTracker

# 1. Load the curated protocol registry
reg = Registry.load()
print(f"{len(reg)} targets across {len(reg.categories())} categories")

# 2. Filter
l2_targets = reg.filter(category="l2", confidence="high")

# 3. Score a wallet against a target
scorer = FitScorer()
linea = reg.get("Linea")
score = scorer.score(my_wallet, linea)
print(f"{score.target}: {score.score}/100 ({score.grade})")

# 4. Follow alpha wallets across chains
import asyncio
tracker = WalletTracker.load_alpha()
asyncio.run(tracker.refresh(chains=["ethereum", "arbitrum", "base"]))
print(tracker.protocol_signals())

Registry

The Registry is a queryable collection of Target objects, sorted by priority. Targets have a chain, category, confidence level, optional contract addresses, criteria, tags, and notes. The bundled registry ships with curated entries; you can also load your own YAML file.

reg = Registry.load()                 # bundled curated registry
reg = Registry.load(path="my.yaml")   # custom YAML

reg.get("Linea")                      # case-insensitive lookup
reg.filter(category="l2")             # filter by category
reg.filter(chain="ethereum")          # chain="multi" matches any
reg.filter(confidence="high")         # minimum confidence
reg.filter(tag="zkevm")               # filter by tag

reg.categories()                      # all categories
reg.chains()                          # all chains
reg.add(Target(...))                  # add programmatically
reg.mark("Linea", Confidence.CLAIMED) # update confidence

FitScorer

FitScorer scores any wallet (anything implementing the WalletLike protocol) against any target's criteria dict. Returns a FitScore with the numeric score, met/missing criteria, and actionable recommendations.

scorer = FitScorer()
score = scorer.score(wallet, target)

print(score.score)            # 0-100
print(score.grade)            # A/B/C/D/F
print(score.met)              # ["Bridge activity (5 txns)", ...]
print(score.missing)          # ["DEX swaps (have 2, need 5+)", ...]
print(score.recommendations)  # ["Swap on native DEXes on linea", ...]

# Score against many targets at once
scores = scorer.score_all(wallet, reg.filter(category="l2"))

Recognized criteria keys: bridge_volume, bridge_usage, cross_chain_messages, dex_swaps, dex_interaction, swap_volume, unique_months, restake_eth, bgt_staking, testnet_activity, lp_provision. Universal heuristics (chain diversity, gas spend, long-term activity) always apply.

WalletTracker

Follow wallets across chains and aggregate protocol signals. Useful for smart-money following, treasury monitoring, governance intel, ecosystem mapping.

import asyncio
from scout import WalletTracker

# Load the bundled alpha-wallet list
tracker = WalletTracker.load_alpha()

# Refresh activity across chains (requires ETHERSCAN_API_KEY)
asyncio.run(tracker.refresh(chains=["ethereum", "arbitrum", "base"]))

# Aggregate signals
tracker.protocol_signals()  # {"uniswap_v3": 12, "aerodrome": 7, ...}
tracker.chain_signals()     # {"arbitrum": 18, "base": 11, ...}

The default backend is Etherscan v2 (multichain unified API, requires API key). You can plug in your own backend by subclassing ActivityBackend — it's a 3-line interface.

Beyond airdrops

The primitives are deliberately decoupled from any single use case:

CLI

# List targets
python -m scout targets
python -m scout targets --category l2 --confidence high
python -m scout targets --chain ethereum

# Inspect one target
python -m scout get Linea

# Available categories
python -m scout categories

# Refresh alpha wallets and dump signals
ETHERSCAN_API_KEY=YOUR_KEY python -m scout follow

Data files

Curated assets live in scout/data/ as YAML so they can be edited and contributed to without touching code:

• targets.yaml — protocol registry
• alpha_wallets.yaml — wallets worth following
• known_contracts.yaml — address → protocol mapping

PRs adding entries are welcome. Keep them factual; cite a source in notes when possible.