debridge-analytics

DeFi Analytics

PREREQUISITE: Read ../common/SKILL.md for environment detection, auth, and chain configuration.

Third-party MCP servers provide analytics data useful before, during, and after deBridge operations: token prices, wallet balances, protocol TVL, DEX liquidity, and on-chain transaction details. All analytics MCPs listed here are free and require no API key.

Quick Reference

Installing Analytics MCPs

npx vs npm install

Use npx for one-shot exploration — the package is fetched, executed once, and not retained:

npx -y @coingecko/coingecko-mcp         # try CoinGecko MCP
npx -y @nic0xflamel/defillama-mcp-server # try DefiLlama MCP
npx dexpaprika-mcp                       # try DexPaprika MCP
npx -y mcp-crypto-price                  # try mcp-crypto-price MCP

Use npm install -g (or add to devDependencies) when building a persistent agent harness, a recurring script, or a long-lived process:

npm install -g @coingecko/coingecko-mcp  # always available, faster startup

Adding to Claude Desktop

All analytics MCPs use the same config pattern. Add to the Claude Desktop config file (see ../common/mcp-setup.md for file location):

For hosted MCPs (CoinGecko, Blockscout) that expose a remote endpoint:

{
  "mcpServers": {
    "<mcp-name>": {
      "type": "streamable-http",
      "url": "<hosted-endpoint>"
    }
  }
}

Adding to Claude Code (CLI)

Stdio (local):

claude mcp add <name> -- npx -y <package-name>

Streaming (hosted):

claude mcp add --transport http <name> <hosted-url>

API Key Requirements

All analytics MCPs are free and require no API key:

Use Case Routing

Before a Bridge or Swap

1. Check token price → token-prices.md — verify the token is priced as expected before committing.
2. Check destination pool liquidity → dex-pools.md — ensure the destination chain has sufficient liquidity.
3. Check wallet balances → Direct Balance Queries below, or Blockscout get_tokens_by_address per chain.

After a Bridge or Swap

4. Verify transaction on-chain → onchain-explorer.md — confirm the tx landed on the destination chain.
5. Check received balance → Blockscout get_tokens_by_address or Direct Balance Queries below.

Research and Analysis

6. Protocol TVL and yields → defi-tvl.md — compare protocols, check yield opportunities on destination chains.

Direct Balance Queries (No MCP Required)

When no analytics MCP is connected, query balances directly using the signer/runtime detected during WALLET_DISCOVERY in ../common/SKILL.md. Route based on available tool:

Auto-Discovery Balance Flow

⚠️ STOP — Do NOT ask the user for an address or chain. When the user says “check my balance”, “what’s my balance”, “show balances”, or anything balance-related, skip all clarifying questions and immediately run discovery. This is the #1 anti-pattern: asking “which chain?” or “what address?” when the skill requires auto-discovery.

The agent MUST:

1. Discover wallets FIRST — run ALL applicable discovery methods and collect addresses:
   • OWS: ows wallet list → parse EVM (eip155: lines) and Solana (solana: lines) addresses.
   • env-keys: node ../common/scripts/env-keys.mjs --json → collect addresses from environment variables and .env files. This replaces ad-hoc shell commands like test -n "$PRIVATE_KEY" — always use the script.
   • Cast: cast wallet list if Foundry is available.
   • Do NOT ask the user for an address — discover it.
2. Query native balances across ALL chains (both EVM and Solana if addresses exist for both). “All” is the default — never ask which chain.
   • EVM: node scripts/balance-evm.mjs <address> --all
   • Solana: node scripts/balance-solana.mjs <address> --tokens
3. Query ERC-20 token balances — native balance scripts only report native tokens. For ERC-20/SPL discovery the agent MUST also use analytics MCPs. Try each in order until one succeeds:
   • Blockscout MCP (preferred): call mcp__blockscout__get_tokens_by_address with address and chain_id (as string) for each major EVM chain (at minimum: "1", "56", "137", "42161", "10", "8453"). Hosted at https://mcp.blockscout.com/mcp — no API key.
   • Hive Intelligence (fallback): call mcp__hive_portfolio__get_wallet_token_balances with id = address and is_all = true. Hosted at https://mcp.hiveintelligence.xyz/hive_portfolio_wallet/mcp — no API key.
   • ethers.js balanceOf (last resort): only if you already know specific token contract addresses from context. Cannot enumerate unknown tokens — skip if no addresses known.
   • Do NOT report only native balances and stop. ERC-20 discovery is required when analytics MCPs are available.
4. Report results for every wallet, every chain, both native and token balances. Group by chain for readability.

Bundled Scripts

Scripts accept only standard addresses — never wallet names.

# EVM — pass a 0x address, query all deBridge EVM chains
node scripts/balance-evm.mjs 0x000A5539cD9505b44575c56f929C657c73899c30 --all

# EVM — pass a 0x address, query specific chains only
node scripts/balance-evm.mjs 0x000A5539cD9505b44575c56f929C657c73899c30 --chains 1,137,42161

# EVM — query a specific ERC-20 token balance (e.g., USDC on Polygon)
node scripts/balance-evm.mjs 0x000A5539cD9505b44575c56f929C657c73899c30 --chains 137 --token 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359

# Solana — pass a base58 address, query native SOL + SPL tokens
node scripts/balance-solana.mjs B7Z1whe4TX3tVXwb93Nsd9U4f4QZfnuzm5DyUnKxVSUr --tokens

# JSON output for piping
node scripts/balance-evm.mjs 0x000A5539cD9505b44575c56f929C657c73899c30 --all --json
node scripts/balance-solana.mjs B7Z1whe4TX3tVXwb93Nsd9U4f4QZfnuzm5DyUnKxVSUr --tokens --json

Arguments:

• First argument: a standard blockchain address (EVM 0x hex, 42 chars; or Solana base58, 32-44 chars). Required.
• --all: (EVM only) query all deBridge-supported EVM chains.
• --chains <ids>: (EVM only) comma-separated chain IDs.
• --token <addr>: (EVM only) query a specific ERC-20 token balance instead of native balance. Reads decimals and symbol on-chain.
• --tokens: (Solana only) also list non-zero SPL token balances.
• --json: output as JSON.

Do NOT pass OWS wallet names, ENS names, or any non-address string. Resolve addresses first via WALLET_DISCOVERY, then pass the resolved address to the script.

All direct query methods require an RPC endpoint. Resolve RPCs in this order:

1. Environment variable ($RPC_URL, $ETH_RPC_URL).
2. User-provided URL.
3. Discover from Chainlist — read ../common/rpc-discovery.md.

When to Use Direct Queries vs MCP

When No Analytics MCP Is Available

If no analytics MCPs are installed, you can still gather basic data:

For a quick start with zero setup, CoinGecko (hosted, no API key), Crypto.com (hosted, no API key), and Blockscout (hosted, no API key) cover most pre-swap research needs.

Common Errors