Description

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...

README (SKILL.md)

DeFi Scout

Name: Defi Scout
Author: old-greggyboy

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/\x3Cname>.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 \x3C0x-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 \x3C 1.2 (liquidation risk). 8-second timeout per RPC call.

swap-quote.js

node scripts/swap-quote.js \x3Ctoken_in> \x3Ctoken_out> \x3Camount_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 \x3Caddress> → 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 \x3Camount_eth> [from_chain=10] [to_chain=8453] → returns fee, fill time, output amount.

Price check: Run token-price.js \x3Ccoingecko_id> → price, 24h change.

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

Swap estimate: Run swap-quote.js \x3CtokenIn> \x3CtokenOut> \x3Camount> → 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 \x3C $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

Usage Guidance

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.

Capability Analysis

Type: OpenClaw Skill Name: defi-scout Version: 1.0.3 The 'defi-scout' skill bundle provides read-only DeFi intelligence for the Optimism and Base networks, including wallet balances, token prices, and yield opportunities. The scripts use standard Node.js built-in modules (https, fs) to interact with legitimate public APIs such as CoinGecko, DeFiLlama, and official blockchain RPC endpoints. No evidence of data exfiltration, malicious command execution, or harmful prompt injection was found; the use of an environment variable for the CoinMarketCap API key in 'cmc-sentiment.js' is consistent with its stated purpose.

Capability Assessment

⚠ 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.

Version History

v1.0.3

- Clarified that most scripts require no API keys; only `cmc-sentiment.js` needs a `CMC_API_KEY` - Updated documentation in SKILL.md to reflect this requirement - No changes to functionality or scripts, documentation update only

v1.0.2

- Added new script `cmc-sentiment.js` for BTC/ETH dominance and Fear & Greed index using CoinMarketCap (requires `CMC_API_KEY`). - Updated workflow section with `Market sentiment` step. - Expanded error handling documentation for all core scripts. - Documented `yields.js` new filtering and flags options.

v1.0.1

- Removed 110 analysis and backtest-related files. - Reduced codebase to only core operational scripts and documentation. - No changes to documentation or workflows in SKILL.md. - Streamlined project to focus on on-chain data and API integrations; all historical backtesting code has been removed.

v1.0.0

Initial release of defi-scout: on-chain DeFi intelligence for Optimism and Base. - Provides wallet balance checks, live token prices, swap and bridge fee estimates, top yield pools, protocol TVL, and gas prices using free public APIs. - Scripts cover Aerodrome, Velodrome, Aave, Optimism, Base, and airdrop farming use cases. - No API keys required; all endpoints and output formats documented for transparency. - Includes risk guidelines: TVL minimum, APY caution, gas cost awareness, and risk notes for stable/volatile pools.

Metadata

Slug defi-scout

Version 1.0.3

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 4

Frequently Asked Questions

What is 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... It is an AI Agent Skill for Claude Code / OpenClaw, with 148 downloads so far.

How do I install Defi Scout?

Run "/install defi-scout" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Defi Scout free?

Yes, Defi Scout is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Defi Scout support?

Defi Scout is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Defi Scout?

It is built and maintained by old-greggyboy (@old-greggyboy); the current version is v1.0.3.

More Skills

Defi Scout