DeFi Scout#

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#

SourceWhatEndpointCoinGeckoToken pricesapi.coingecko.com/api/v3/simple/priceDeFiLlamaProtocol TVL, yieldsapi.llama.fiOptimism RPCBalances, gasmainnet.optimism.ioBase RPCBalances, gasmainnet.base.orgAcross APIBridge quotesapp.across.to/api/suggested-fees

Core Scripts#

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

ScriptPurposewallet-balances.jsETH + ERC-20 balances on OP + Basetoken-price.jsCoinGecko price for any tokenyields.jsTop yield pools on OP + Base from DeFiLlamagas.jsCurrent gas on Optimism and Basebridge-quote.jsAcross Protocol bridge fee quote (no deps, 10s timeout)aave-position.jsAave V3 health factor + collateral/debt on OP + Baseswap-quote.jsPrice-based swap estimate via CoinGecko (price math only — not a protocol-routed quote)cmc-sentiment.jsBTC dominance, ETH dominance, Fear & Greed index (CoinMarketCap)

Script Details#

aave-position.js#

bash

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#

bash

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:

bash

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