better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/blockchain/blockchain-evm.md

@@ -0,0 +1,227 @@
+---
+title: "Evm — Read-only EVM client: wallets, tokens, gas across 8 chains"
+sidebar_label: "Evm"
+description: "Read-only EVM client: wallets, tokens, gas across 8 chains"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Evm
+
+Read-only EVM client: wallets, tokens, gas across 8 chains.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/blockchain/evm` |
+| Path | `optional-skills/blockchain\evm` |
+| Version | `1.0.0` |
+| Author | Mibayy (@Mibayy), youssefea (@youssefea), ethernet8023 (@ethernet8023), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `EVM`, `Ethereum`, `BNB`, `BSC`, `Base`, `Arbitrum`, `Polygon`, `Optimism`, `Avalanche`, `zkSync`, `Blockchain`, `Crypto`, `Web3`, `DeFi`, `NFT`, `ENS`, `Whale`, `Security` |
+| Related skills | [`solana`](/docs/user-guide/skills/optional/blockchain/blockchain-solana) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# EVM Blockchain Skill
+
+Query EVM-compatible blockchain data across 8 chains with USD pricing.
+14 commands: wallet portfolio, token info, transactions, activity, gas tracker,
+network stats, price lookup, multi-chain scan, whale detection, ENS resolution,
+allowance checker, contract inspector, and transaction decoder.
+
+Supports 8 chains: Ethereum, BNB Chain (BSC), Base, Arbitrum One, Polygon,
+Optimism, Avalanche (C-Chain), zkSync Era.
+
+No API key needed. Zero external dependencies — Python standard library only
+(urllib, json, argparse, threading).
+
+> **Supersedes the standalone `base` skill.** Base-specific tokens (AERO, DEGEN,
+> TOSHI, BRETT, WELL, cbETH, cbBTC, wstETH, rETH) and all Base RPC functionality
+> previously living under `optional-skills/blockchain/base/` have been folded
+> into this skill. Pass `--chain base` to any command for Base coverage.
+
+---
+
+## When to Use
+- User asks for a wallet balance or portfolio on any EVM chain
+- User wants to check the same wallet across ALL chains at once
+- User wants to inspect a transaction by hash (or decode what it did)
+- User wants ERC-20 token metadata, price, supply, or market cap
+- User wants recent transaction history for an address
+- User wants current gas prices or to compare fees across chains
+- User wants to find large whale transfers in recent blocks
+- User asks to resolve an ENS name (vitalik.eth) or reverse-lookup an address
+- User wants to check if a contract has dangerous token approvals
+- User wants to inspect a smart contract (proxy? ERC-20? ERC-721? bytecode size?)
+- User wants to compare gas costs across chains before a transaction
+
+---
+
+## Prerequisites
+Python 3.8+ standard library only. No pip installs required.
+Pricing: CoinGecko free API (rate-limited, ~10-30 req/min).
+ENS: ensideas.com public API.
+Tx decoding: 4byte.directory public API.
+
+Override RPC endpoint: `export EVM_RPC_URL=https://your-rpc.com`
+
+Helper script path: `~/.hermes/skills/blockchain/evm/scripts/evm_client.py`
+
+---
+
+## Quick Reference
+
+```
+SCRIPT=~/.hermes/skills/blockchain/evm/scripts/evm_client.py
+
+# Network & prices
+python $SCRIPT stats                            # Ethereum stats
+python $SCRIPT stats --chain arbitrum           # Arbitrum stats
+python $SCRIPT compare                          # Gas + prices ALL 8 chains
+
+# Wallet
+python $SCRIPT wallet 0xd8dA...96045            # Portfolio (ETH + ERC-20)
+python $SCRIPT wallet 0xd8dA...96045 --chain bsc
+python $SCRIPT multichain 0xd8dA...96045        # Same wallet on ALL chains
+
+# Tokens & prices
+python $SCRIPT price ETH
+python $SCRIPT price 0xdAC1...1ec7              # By contract address
+python $SCRIPT token 0xdAC1...1ec7              # ERC-20 metadata + market cap
+
+# Transactions
+python $SCRIPT tx 0x5c50...f060                 # Transaction details
+python $SCRIPT decode 0x5c50...f060             # Decode input data (4byte.directory)
+python $SCRIPT activity 0xd8dA...96045          # Recent transactions
+
+# Gas
+python $SCRIPT gas                              # Gas prices + cost estimates
+python $SCRIPT gas --chain optimism
+
+# Security
+python $SCRIPT allowance 0xd8dA...96045         # Dangerous ERC-20 approvals
+python $SCRIPT contract 0xdAC1...1ec7           # Contract inspection (proxy? standards?)
+
+# ENS
+python $SCRIPT ens vitalik.eth                  # Name -> address + profile
+python $SCRIPT ens 0xd8dA...96045               # Address -> ENS name
+
+# Whale detection
+python $SCRIPT whale                            # Large transfers (last 20 blocks, >$10k)
+python $SCRIPT whale --blocks 50 --min-usd 100000 --chain arbitrum
+```
+
+---
+
+## Procedure
+
+### 0. Setup Check
+```bash
+python --version   # 3.8+ required
+python ~/.hermes/skills/blockchain/evm/scripts/evm_client.py stats
+```
+
+### 1. Wallet Portfolio
+Native balance + known ERC-20 tokens, sorted by USD value.
+```bash
+python $SCRIPT wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+python $SCRIPT wallet 0xd8dA... --chain bsc --no-prices   # faster
+```
+
+### 2. Multi-Chain Scan
+Scans all 8 chains simultaneously for the same address using threads.
+```bash
+python $SCRIPT multichain 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+```
+Output: per-chain native balance + token holdings + grand total USD.
+
+### 3. Compare (Gas + Prices)
+All 8 chains queried in parallel. Shows cheapest/most expensive chain.
+```bash
+python $SCRIPT compare
+```
+
+### 4. Transaction Details & Decode
+```bash
+python $SCRIPT tx 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060
+python $SCRIPT decode 0x5c504ed...   # Shows human-readable function signature
+```
+Decode uses 4byte.directory to translate 0xa9059cbb -> transfer(address,uint256).
+
+### 5. ENS Resolution
+```bash
+python $SCRIPT ens vitalik.eth          # -> 0xd8dA... + avatar + social links
+python $SCRIPT ens 0xd8dA...96045       # -> vitalik.eth
+```
+
+### 6. Allowance Checker (Security)
+Checks ERC-20 approvals granted to known DEX/bridge contracts.
+```bash
+python $SCRIPT allowance 0xYourWallet
+```
+Flags UNLIMITED approvals as HIGH risk.
+
+### 7. Contract Inspector
+```bash
+python $SCRIPT contract 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48   # USDC (proxy)
+python $SCRIPT contract 0xdAC17F958D2ee523a2206206994597C13D831ec7   # USDT (ERC-20)
+```
+Detects: proxy (EIP-1967/EIP-1167), ERC-20, ERC-721, ERC-165. Shows bytecode size and implementation address for proxies.
+
+### 8. Whale Detection
+```bash
+python $SCRIPT whale                                    # ETH, last 20 blocks, >$10k
+python $SCRIPT whale --blocks 50 --min-usd 50000 --chain bsc
+```
+
+### 9. Gas Tracker
+```bash
+python $SCRIPT gas
+python $SCRIPT gas --chain polygon
+```
+Shows gwei price + USD cost for: transfer, ERC-20 transfer, approve, swap, NFT mint, NFT transfer.
+
+---
+
+## Supported Chains
+| Key       | Name           | Native | Chain ID |
+|-----------|----------------|--------|----------|
+| ethereum  | Ethereum       | ETH    | 1        |
+| bsc       | BNB Chain      | BNB    | 56       |
+| base      | Base           | ETH    | 8453     |
+| arbitrum  | Arbitrum One   | ETH    | 42161    |
+| polygon   | Polygon        | POL    | 137      |
+| optimism  | Optimism       | ETH    | 10       |
+| avalanche | Avalanche C    | AVAX   | 43114    |
+| zksync    | zkSync Era     | ETH    | 324      |
+
+---
+
+## Pitfalls
+- CoinGecko free tier: ~10-30 req/min. Use `--no-prices` for faster wallet scans.
+- Public RPCs may throttle. Set EVM_RPC_URL to a private endpoint for production.
+- `wallet` and `allowance` only check known token list (~30 tokens per chain). Use a block explorer for complete token discovery.
+- `activity` scans recent blocks only (max 200). For full history, use Etherscan API.
+- `multichain` runs 8 parallel threads — can trigger rate limits on public RPCs.
+- ENS resolution depends on a single public endpoint (ensideas.com / ens.vitalik.ca) with no fallback. If that endpoint is down, `ens` will fail — re-run later or use a block explorer.
+- Tx decoding depends on a single public endpoint (4byte.directory) with no fallback. Selectors not in their database show up as `unknown`.
+- **L2 gas estimates are L2-execution only.** On rollups like Base, Arbitrum, Optimism, and zkSync, the actual transaction cost also includes an L1 data-posting fee that depends on calldata size and current L1 gas prices. The `gas` command does not estimate that L1 component. For Base specifically, see the network's L1 fee oracle (contract `0x420000000000000000000000000000000000000F`).
+- Address / tx-hash inputs are validated for 0x-prefix + correct length + hex, but EIP-55 checksum casing is **not** enforced (RPC endpoints accept any-case hex).
+
+---
+
+## Verification
+```bash
+# Should print current block, gas price, ETH price
+python ~/.hermes/skills/blockchain/evm/scripts/evm_client.py stats
+
+# Should resolve vitalik.eth to 0xd8dA...
+python ~/.hermes/skills/blockchain/evm/scripts/evm_client.py ens vitalik.eth
+```

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/blockchain/blockchain-hyperliquid.md

@@ -0,0 +1,228 @@
+---
+title: "Hyperliquid — Hyperliquid market data, account history, trade review"
+sidebar_label: "Hyperliquid"
+description: "Hyperliquid market data, account history, trade review"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Hyperliquid
+
+Hyperliquid market data, account history, trade review.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/blockchain/hyperliquid` |
+| Path | `optional-skills/blockchain\hyperliquid` |
+| Version | `0.1.0` |
+| Author | Hugo Sequier (Hugo-SEQUIER), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Hyperliquid`, `Blockchain`, `Crypto`, `Trading`, `Perpetuals`, `Spot`, `DeFi` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Hyperliquid Skill
+
+Query Hyperliquid market and account data through the public `/info` endpoint.
+Read-only — no API key, no signing, no order placement.
+
+12 commands: `dexs`, `markets`, `spots`, `candles`, `funding`, `l2`, `state`,
+`spot-balances`, `fills`, `orders`, `review`, `export`. Stdlib only
+(`urllib`, `json`, `argparse`).
+
+---
+
+## When to Use
+
+- User asks for Hyperliquid perp or spot market data, candles, funding, or L2 book
+- User wants to inspect a wallet's perp positions, spot balances, fills, or orders
+- User wants a post-trade review combining recent fills with market context
+- User wants to inspect builder-deployed perp dexs or HIP-3 markets
+- User wants a normalized JSON export of candles + funding for backtesting prep
+
+---
+
+## Prerequisites
+
+Stdlib only — no external packages, no API key.
+
+The script reads `${HERMES_HOME:-~/.hermes}/.env` for two optional defaults:
+
+- `HYPERLIQUID_API_URL` — defaults to `https://api.hyperliquid.xyz`. Set to
+  `https://api.hyperliquid-testnet.xyz` for testnet.
+- `HYPERLIQUID_USER_ADDRESS` — default address for `state`, `spot-balances`,
+  `fills`, `orders`, and `review`. If unset, pass the address as the first
+  positional argument.
+
+A project `.env` in the current working directory is honored as a dev fallback.
+
+Helper script: `~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py`
+
+---
+
+## How to Run
+
+Invoke through the `terminal` tool:
+
+```bash
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py <command> [args]
+```
+
+Add `--json` to any command for machine-readable output.
+
+---
+
+## Quick Reference
+
+```bash
+hyperliquid_client.py dexs
+hyperliquid_client.py markets [--dex DEX] [--limit N] [--sort volume|oi|funding_abs|change_abs|name]
+hyperliquid_client.py spots [--limit N]
+hyperliquid_client.py candles <coin> [--interval 1h] [--hours 24] [--limit N]
+hyperliquid_client.py funding <coin> [--hours 72] [--limit N]
+hyperliquid_client.py l2 <coin> [--levels N]
+hyperliquid_client.py state [address] [--dex DEX]
+hyperliquid_client.py spot-balances [address] [--limit N]
+hyperliquid_client.py fills [address] [--hours N] [--limit N] [--aggregate-by-time]
+hyperliquid_client.py orders [address] [--limit N]
+hyperliquid_client.py review [address] [--coin COIN] [--hours N] [--fills N]
+hyperliquid_client.py export <coin> [--interval 1h] [--hours N] [--output PATH]
+```
+
+For `state`, `spot-balances`, `fills`, `orders`, and `review`, the address is
+optional when `HYPERLIQUID_USER_ADDRESS` is set in `${HERMES_HOME:-~/.hermes}/.env`.
+
+---
+
+## Procedure
+
+### 1. Discover DEXs and Markets
+
+```bash
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py dexs
+
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  markets --limit 15 --sort volume
+
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  spots --limit 15
+```
+
+- `--dex` only applies to perp endpoints; omit for the first perp dex.
+- Spot pairs may show as `PURR/USDC` or aliases like `@107`.
+- HIP-3 markets prefix the coin with the dex, e.g. `mydex:BTC`.
+
+### 2. Pull Historical Market Data
+
+```bash
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  candles BTC --interval 1h --hours 72 --limit 48
+
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  funding BTC --hours 168 --limit 30
+```
+
+Time-range endpoints paginate. For larger windows, repeat with a later
+`startTime` or use `export` (below).
+
+### 3. Inspect Live Order Book
+
+```bash
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  l2 BTC --levels 10
+```
+
+Use when asked about book depth, near-term liquidity, or potential market
+impact of a large order.
+
+### 4. Review an Account
+
+```bash
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  state 0xabc...
+
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  spot-balances
+```
+
+`state` returns perp positions; `spot-balances` returns spot inventory.
+Use these for "how are my positions?", "what am I holding?", "how much is
+withdrawable?".
+
+### 5. Review Fills and Orders
+
+```bash
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  fills 0xabc... --hours 72 --limit 25
+
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  orders --limit 25
+```
+
+### 6. Generate a Trade Review
+
+```bash
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  review 0xabc... --hours 72 --fills 50
+
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  review --coin BTC --hours 168
+```
+
+Reports realized PnL, fees, win/loss counts, coin breakdowns, market trend
+and average funding for each traded perp, plus heuristics (fee drag,
+concentration, counter-trend losses).
+
+For deeper post-trade analysis: start with `review` to find problem coins
+or windows → pull `fills` and `orders` for that period → pull `candles`
+and `funding` for each traded coin → judge decision quality separately
+from outcome quality.
+
+### 7. Export a Reusable Dataset
+
+```bash
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  export BTC --interval 1h --hours 168 --output ./btc-1h-7d.json
+
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  export BTC --interval 15m --hours 72 --end-time-ms 1760000000000
+```
+
+Output JSON contains: schema version, source metadata, exact time window,
+normalized candle rows, normalized funding rows, summary stats. Use
+`--end-time-ms` for reproducible windows.
+
+---
+
+## Pitfalls
+
+- Public info endpoints are rate-limited. Large historical queries may
+  return capped windows; iterate with later `startTime` values.
+- `fills --hours ...` uses `userFillsByTime`, which only exposes a
+  recent rolling window — not full archive history.
+- `historicalOrders` returns recent orders only; not a full export.
+- The `review` command is heuristic. It cannot reconstruct intent,
+  order placement quality, or true slippage from fills alone.
+- The `export` command writes a normalized dataset, not a backtest
+  engine. You still need your own slippage/fill model.
+- Spot aliases like `@107` are valid identifiers even when the UI shows
+  a friendlier name.
+- `l2` is a point-in-time snapshot, not a time series.
+
+---
+
+## Verification
+
+```bash
+python ~/.hermes/skills/blockchain/hyperliquid/scripts/hyperliquid_client.py \
+  markets --limit 5
+```
+
+Should print the top Hyperliquid perp markets by 24h notional volume.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/blockchain/blockchain-solana.md

@@ -0,0 +1,225 @@
+---
+title: "Solana — Query Solana wallets, tokens, txs, and NFTs in USD"
+sidebar_label: "Solana"
+description: "Query Solana wallets, tokens, txs, and NFTs in USD"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Solana
+
+Query Solana wallets, tokens, txs, and NFTs in USD.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/blockchain/solana` |
+| Path | `optional-skills/blockchain\solana` |
+| Version | `0.2.0` |
+| Author | Deniz Alagoz (gizdusum), enhanced by Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Solana`, `Blockchain`, `Crypto`, `Web3`, `RPC`, `DeFi`, `NFT` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Solana Blockchain Skill
+
+Query Solana on-chain data enriched with USD pricing via CoinGecko.
+8 commands: wallet portfolio, token info, transactions, activity, NFTs,
+whale detection, network stats, and price lookup.
+
+No API key needed. Uses only Python standard library (urllib, json, argparse).
+
+---
+
+## When to Use
+
+- User asks for a Solana wallet balance, token holdings, or portfolio value
+- User wants to inspect a specific transaction by signature
+- User wants SPL token metadata, price, supply, or top holders
+- User wants recent transaction history for an address
+- User wants NFTs owned by a wallet
+- User wants to find large SOL transfers (whale detection)
+- User wants Solana network health, TPS, epoch, or SOL price
+- User asks "what's the price of BONK/JUP/SOL?"
+
+---
+
+## Prerequisites
+
+The helper script uses only Python standard library (urllib, json, argparse).
+No external packages required.
+
+Pricing data comes from CoinGecko's free API (no key needed, rate-limited
+to ~10-30 requests/minute). For faster lookups, use `--no-prices` flag.
+
+---
+
+## Quick Reference
+
+RPC endpoint (default): https://api.mainnet-beta.solana.com
+Override: export SOLANA_RPC_URL=https://your-private-rpc.com
+
+Helper script path: ~/.hermes/skills/blockchain/solana/scripts/solana_client.py
+
+```
+python solana_client.py wallet   <address> [--limit N] [--all] [--no-prices]
+python solana_client.py tx       <signature>
+python solana_client.py token    <mint_address>
+python solana_client.py activity <address> [--limit N]
+python solana_client.py nft      <address>
+python solana_client.py whales   [--min-sol N]
+python solana_client.py stats
+python solana_client.py price    <mint_or_symbol>
+```
+
+---
+
+## Procedure
+
+### 0. Setup Check
+
+```bash
+python --version
+
+# Optional: set a private RPC for better rate limits
+export SOLANA_RPC_URL="https://api.mainnet-beta.solana.com"
+
+# Confirm connectivity
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats
+```
+
+### 1. Wallet Portfolio
+
+Get SOL balance, SPL token holdings with USD values, NFT count, and
+portfolio total. Tokens sorted by value, dust filtered, known tokens
+labeled by name (BONK, JUP, USDC, etc.).
+
+```bash
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
+  wallet 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
+```
+
+Flags:
+- `--limit N` — show top N tokens (default: 20)
+- `--all` — show all tokens, no dust filter, no limit
+- `--no-prices` — skip CoinGecko price lookups (faster, RPC-only)
+
+Output includes: SOL balance + USD value, token list with prices sorted
+by value, dust count, NFT summary, total portfolio value in USD.
+
+### 2. Transaction Details
+
+Inspect a full transaction by its base58 signature. Shows balance changes
+in both SOL and USD.
+
+```bash
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
+  tx 5j7s8K...your_signature_here
+```
+
+Output: slot, timestamp, fee, status, balance changes (SOL + USD),
+program invocations.
+
+### 3. Token Info
+
+Get SPL token metadata, current price, market cap, supply, decimals,
+mint/freeze authorities, and top 5 holders.
+
+```bash
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
+  token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
+```
+
+Output: name, symbol, decimals, supply, price, market cap, top 5
+holders with percentages.
+
+### 4. Recent Activity
+
+List recent transactions for an address (default: last 10, max: 25).
+
+```bash
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
+  activity 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM --limit 25
+```
+
+### 5. NFT Portfolio
+
+List NFTs owned by a wallet (heuristic: SPL tokens with amount=1, decimals=0).
+
+```bash
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
+  nft 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
+```
+
+Note: Compressed NFTs (cNFTs) are not detected by this heuristic.
+
+### 6. Whale Detector
+
+Scan the most recent block for large SOL transfers with USD values.
+
+```bash
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
+  whales --min-sol 500
+```
+
+Note: scans the latest block only — point-in-time snapshot, not historical.
+
+### 7. Network Stats
+
+Live Solana network health: current slot, epoch, TPS, supply, validator
+version, SOL price, and market cap.
+
+```bash
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats
+```
+
+### 8. Price Lookup
+
+Quick price check for any token by mint address or known symbol.
+
+```bash
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price BONK
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price JUP
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price SOL
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
+```
+
+Known symbols: SOL, USDC, USDT, BONK, JUP, WETH, JTO, mSOL, stSOL,
+PYTH, HNT, RNDR, WEN, W, TNSR, DRIFT, bSOL, JLP, WIF, MEW, BOME, PENGU.
+
+---
+
+## Pitfalls
+
+- **CoinGecko rate-limits** — free tier allows ~10-30 requests/minute.
+  Price lookups use 1 request per token. Wallets with many tokens may
+  not get prices for all of them. Use `--no-prices` for speed.
+- **Public RPC rate-limits** — Solana mainnet public RPC limits requests.
+  For production use, set SOLANA_RPC_URL to a private endpoint
+  (Helius, QuickNode, Triton).
+- **NFT detection is heuristic** — amount=1 + decimals=0. Compressed
+  NFTs (cNFTs) and Token-2022 NFTs won't appear.
+- **Whale detector scans latest block only** — not historical. Results
+  vary by the moment you query.
+- **Transaction history** — public RPC keeps ~2 days. Older transactions
+  may not be available.
+- **Token names** — ~25 well-known tokens are labeled by name. Others
+  show abbreviated mint addresses. Use the `token` command for full info.
+- **Retry on 429** — both RPC and CoinGecko calls retry up to 2 times
+  with exponential backoff on rate-limit errors.
+
+---
+
+## Verification
+
+```bash
+# Should print current Solana slot, TPS, and SOL price
+python ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats
+```