Defi Scout

On-chain DeFi intelligence for AI agents. Use when asked about wallet balances, token prices, DEX quotes, yield opportunities, protocol TVL, gas prices, or a...

Security Scan

The skill largely does what its description promises (on‑chain queries, prices, yields) but contains several inconsistencies and a risky behavior: one script loads a top-level .env and writes cache files outside the skill directory, and the registry metadata doesn't declare the CMC API key the code requires.

Purpose & Capability

Most scripts (RPC calls, CoinGecko, DeFiLlama, Across) match the stated DeFi intelligence purpose. However, cmc-sentiment.js requires a CoinMarketCap API key (CMC_API_KEY) and the skill registry metadata lists no required env vars — that's an explicit mismatch. Further, cmc-sentiment.js attempts to load '../../../.env' (outside the skill), which is not needed for the stated purpose and raises coherence concerns.

Instruction Scope

SKILL.md directs the agent to run node scripts and lists public endpoints; most scripts stay within scope. But cmc-sentiment.js instructs (in code) to use dotenv to load a .env file at path require('path').join(__dirname, '../../../.env') and reads/writes '../../../memory/cmc-cache.json' outside the skill directory. This expands the agent's file access beyond the skill boundary and was not documented in registry metadata or SKILL.md.

Install Mechanism

There is no install spec (no remote downloads or package installs), which is lower risk. One caveat: cmc-sentiment.js calls require('dotenv') even though no dependencies are declared — this may cause runtime errors if dotenv is absent, but it's not an install-time code‑fetch risk.

Credentials

The skill metadata declares no required env vars, yet cmc-sentiment.js expects CMC_API_KEY. More importantly, the script proactively loads an upstream .env file (../../../.env), which could expose unrelated secrets present in a project/global .env. Requesting/reading broad env content is disproportionate to the stated functionality (only CMC_API_KEY should be necessary).

Persistence & Privilege

cmc-sentiment.js writes cache data to '../../../memory/cmc-cache.json' (creates a memory directory outside the skill). That gives the skill write persistence in parent directories. The skill is not marked always:true, and it does not modify other skills, but the external cache path and cross-directory file I/O are privileges beyond what's needed to compute and return an API result.

What to consider before installing

This skill mostly implements on-chain checks and price/yield lookups as advertised, but I found multiple red flags you should consider before installing: (1) cmc-sentiment.js expects a CMC_API_KEY even though the registry lists no env requirements; (2) that same script loads a .env from two levels above the skill (../../../.env), which can expose any secrets stored in your project's global .env — this is the primary concern; (3) it writes a cache file to ../../../memory/cmc-cache.json, creating persistent files outside the skill folder; (4) the SKILL.md mentions a 6h cache but the code uses a 24h TTL — a minor mismatch; (5) the code uses the 'dotenv' module but there is no declared dependency/install step. Recommended actions: do not install in a sensitive environment without review; inspect the .env file it would load (or better, run the skill in an isolated sandbox); remove or modify the dotenv line so the script only reads an explicitly provided CMC_API_KEY (via process.env set at runtime), or configure the runtime to provide only a restricted CMC API key; restrict or remove write permissions for the parent directory so the skill cannot create ../../../memory; and verify you trust the skill source before giving it network or filesystem access.

On-chain financial intelligence across Optimism and Base. Most scripts require no API keys. Exception: cmc-sentiment.js requires CMC_API_KEY (free tier at coinmarketcap.com).

Data Sources

Source	What	Endpoint
CoinGecko	Token prices	api.coingecko.com/api/v3/simple/price
DeFiLlama	Protocol TVL, yields	api.llama.fi
Optimism RPC	Balances, gas	mainnet.optimism.io
Base RPC	Balances, gas	mainnet.base.org
Across API	Bridge quotes	app.across.to/api/suggested-fees

Core Scripts

All scripts output JSON. Run with node scripts/<name>.js.

Script	Purpose
wallet-balances.js	ETH + ERC-20 balances on OP + Base
token-price.js	CoinGecko price for any token
yields.js	Top yield pools on OP + Base from DeFiLlama
gas.js	Current gas on Optimism and Base
bridge-quote.js	Across Protocol bridge fee quote (no deps, 10s timeout)
aave-position.js	Aave V3 health factor + collateral/debt on OP + Base
swap-quote.js	Price-based swap estimate via CoinGecko (price math only — not a protocol-routed quote)
cmc-sentiment.js	BTC dominance, ETH dominance, Fear & Greed index (CoinMarketCap)

Script Details

aave-position.js

node scripts/aave-position.js <0x-address>

Queries Aave V3 Pool getUserAccountData on both Optimism and Base via direct JSON-RPC eth_call. Returns collateral, debt, available borrows, liquidation threshold, LTV, and health factor. Adds a warning field if health factor < 1.2 (liquidation risk). 8-second timeout per RPC call.

swap-quote.js

node scripts/swap-quote.js <token_in> <token_out> <amount_in> [--chain optimism|base]
# Example: node scripts/swap-quote.js ETH USDC 1.5 --chain base

Fetches live prices from CoinGecko and computes estimated output = (priceIn / priceOut) * amountIn * 0.997 (0.3% fee estimate). Supported tokens: ETH, WETH, USDC, USDT, OP, VELO, AERO, cbETH. Not a real quote — use Aerodrome/Velodrome UI for execution.

Workflow

Wallet check: Run wallet-balances.js <address> → summarise balances + USD value.

Opportunity scan: Run yields.js → filter by chain, TVL >$1M, sort by APY. Flag stable pairs (no IL) and volatile pairs separately. Cross-reference gas cost vs position size before recommending entry.

Bridge quote: Run bridge-quote.js <amount_eth> [from_chain=10] [to_chain=8453] → returns fee, fill time, output amount.

Price check: Run token-price.js <coingecko_id> → price, 24h change.

Aave health check: Run aave-position.js <address> → health factor on both chains. Act immediately if < 1.2.

Swap estimate: Run swap-quote.js <tokenIn> <tokenOut> <amount> → rough output estimate for planning. Never use for execution.

Market sentiment: Run cmc-sentiment.js → BTC dom, ETH dom, Fear & Greed. Requires CMC_API_KEY env var. Caches results for 6h.

yields.js flags:

node scripts/yields.js                                 # OP + Base, TVL >$1M, top 20
node scripts/yields.js --chain optimism                # OP only
node scripts/yields.js --chain base                    # Base only
node scripts/yields.js --chain all --min-tvl 5000000   # both chains, TVL >$5M
node scripts/yields.js --top 5                         # top 5 results only

Error Handling

• Bad address (wallet-balances.js, aave-position.js): returns { error: "invalid address" } — always validate 0x format before passing
• Unknown token (swap-quote.js): returns { error: "Unsupported token: XYZ" } — supported list is in script header
• RPC timeout: 8s timeout per call; on failure returns { error: "RPC timeout" } — retry once before surfacing to user
• DeFiLlama offline: yields.js returns empty array [] — surface as "yield data temporarily unavailable"

Key Addresses (verified)

See references/addresses.md for verified contract addresses on Optimism and Base.

Risk Rules

• Never recommend pools with TVL < $1M
• Flag APY > 100% as high-risk / likely temporary incentive
• Always show gas cost as % of position before recommending entry
• Stable pairs (USDC-USDT, USDC-msUSD) = lower risk, note explicitly