feat: enhance Solana skill with USD pricing, token names, smart wallet output
Enhancements to the Solana blockchain skill (PR #212 by gizdusum): - CoinGecko price integration (free, no API key) - Wallet shows tokens with USD values, sorted by value - Token info includes price and market cap - Transaction details show USD amounts for balance changes - Whale detector shows USD alongside SOL amounts - Stats includes SOL price and market cap - New `price` command for quick lookups by symbol or mint - Smart wallet output - Tokens sorted by USD value (highest first) - Default limit of 20 tokens (--limit N to adjust) - Dust filtering (< $0.01 tokens hidden, count shown) - --all flag to see everything - --no-prices flag for fast RPC-only mode - NFT summary (count + first 10) - Portfolio total in USD - Token name resolution - 25+ well-known tokens mapped (SOL, USDC, BONK, JUP, etc.) - CoinGecko fallback for unknown tokens - Abbreviated mint addresses for unlabeled tokens - Reliability - Retry with exponential backoff on 429 rate-limit (RPC + CoinGecko) - Graceful degradation when price data unavailable - Capped API calls to respect CoinGecko free-tier limits - Updated SKILL.md with all new capabilities and flags
This commit is contained in:
teknium1
parent
2394e18729
commit
7185a66b96
2 changed files with 445 additions and 160 deletions
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
name: solana
|
||||
description: Query Solana blockchain data — wallet balances, SPL token holdings, transaction details, NFT portfolios, whale detection, and live network stats via public Solana RPC API. No API key required for basic usage.
|
||||
version: 0.1.0
|
||||
author: Deniz Alagoz (gizdusum)
|
||||
description: Query Solana blockchain data with USD pricing — wallet balances, token portfolios with values, transaction details, NFTs, whale detection, and live network stats. Uses Solana RPC + CoinGecko. No API key required.
|
||||
version: 0.2.0
|
||||
author: Deniz Alagoz (gizdusum), enhanced by Hermes Agent
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
|
|
@ -12,34 +12,34 @@ metadata:
|
|||
|
||||
# Solana Blockchain Skill
|
||||
|
||||
Query Solana on-chain data using the public Solana JSON-RPC API.
|
||||
Includes 7 intelligence tools: wallet info, transactions, token metadata,
|
||||
recent activity, NFT portfolios, whale detection, and network stats.
|
||||
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 for mainnet public endpoint.
|
||||
For high-volume use, set SOLANA_RPC_URL to a private RPC (Helius, QuickNode, etc.).
|
||||
No API key needed. Uses only Python standard library (urllib, json, argparse).
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks for a Solana wallet balance or token holdings
|
||||
- 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, supply, or top holders
|
||||
- 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 slot info
|
||||
- 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 for basic operation.
|
||||
No external packages required.
|
||||
|
||||
Optional: httpx (faster async I/O) and base58 (address validation).
|
||||
Install via your project's dependency manager before use if needed.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -50,13 +50,16 @@ Override: export SOLANA_RPC_URL=https://your-private-rpc.com
|
|||
|
||||
Helper script path: ~/.hermes/skills/blockchain/solana/scripts/solana_client.py
|
||||
|
||||
python3 solana_client.py wallet <address>
|
||||
python3 solana_client.py tx <signature>
|
||||
python3 solana_client.py token <mint_address>
|
||||
python3 solana_client.py activity <address> [--limit N]
|
||||
python3 solana_client.py nft <address>
|
||||
python3 solana_client.py whales [--min-sol N]
|
||||
python3 solana_client.py stats
|
||||
```
|
||||
python3 solana_client.py wallet <address> [--limit N] [--all] [--no-prices]
|
||||
python3 solana_client.py tx <signature>
|
||||
python3 solana_client.py token <mint_address>
|
||||
python3 solana_client.py activity <address> [--limit N]
|
||||
python3 solana_client.py nft <address>
|
||||
python3 solana_client.py whales [--min-sol N]
|
||||
python3 solana_client.py stats
|
||||
python3 solana_client.py price <mint_or_symbol>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -65,7 +68,6 @@ Helper script path: ~/.hermes/skills/blockchain/solana/scripts/solana_client.py
|
|||
### 0. Setup Check
|
||||
|
||||
```bash
|
||||
# Verify Python 3 is available
|
||||
python3 --version
|
||||
|
||||
# Optional: set a private RPC for better rate limits
|
||||
|
|
@ -75,38 +77,50 @@ export SOLANA_RPC_URL="https://api.mainnet-beta.solana.com"
|
|||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats
|
||||
```
|
||||
|
||||
### 1. Wallet Info
|
||||
### 1. Wallet Portfolio
|
||||
|
||||
Get SOL balance and all SPL token holdings for an address.
|
||||
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
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
|
||||
wallet 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
|
||||
```
|
||||
|
||||
Output: SOL balance (human readable), list of SPL tokens with mint + amount.
|
||||
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.
|
||||
Inspect a full transaction by its base58 signature. Shows balance changes
|
||||
in both SOL and USD.
|
||||
|
||||
```bash
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
|
||||
tx 5j7s8K...your_signature_here
|
||||
```
|
||||
|
||||
Output: slot, timestamp, fee, status, balance changes, program invocations.
|
||||
Output: slot, timestamp, fee, status, balance changes (SOL + USD),
|
||||
program invocations.
|
||||
|
||||
### 3. Token Info
|
||||
|
||||
Get SPL token metadata, supply, decimals, mint/freeze authorities, top holders.
|
||||
Get SPL token metadata, current price, market cap, supply, decimals,
|
||||
mint/freeze authorities, and top 5 holders.
|
||||
|
||||
```bash
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
|
||||
token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
|
||||
```
|
||||
|
||||
Output: decimals, supply (human readable), top 5 holders and their percentages.
|
||||
Output: name, symbol, decimals, supply, price, market cap, top 5
|
||||
holders with percentages.
|
||||
|
||||
### 4. Recent Activity
|
||||
|
||||
|
|
@ -117,8 +131,6 @@ python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
|
|||
activity 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM --limit 25
|
||||
```
|
||||
|
||||
Output: list of transaction signatures with slot and timestamp.
|
||||
|
||||
### 5. NFT Portfolio
|
||||
|
||||
List NFTs owned by a wallet (heuristic: SPL tokens with amount=1, decimals=0).
|
||||
|
|
@ -128,78 +140,68 @@ python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
|
|||
nft 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
|
||||
```
|
||||
|
||||
Output: list of NFT mint addresses.
|
||||
Note: Compressed NFTs (cNFTs) are not detected by this heuristic.
|
||||
|
||||
### 6. Whale Detector
|
||||
|
||||
Scan the most recent block for large SOL transfers (default threshold: 1000 SOL).
|
||||
Scan the most recent block for large SOL transfers with USD values.
|
||||
|
||||
```bash
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
|
||||
whales --min-sol 500
|
||||
```
|
||||
|
||||
Output: list of large transfers with sender, receiver, amount in SOL.
|
||||
Note: scans the latest block only — point-in-time snapshot.
|
||||
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.
|
||||
Live Solana network health: current slot, epoch, TPS, supply, validator
|
||||
version, SOL price, and market cap.
|
||||
|
||||
```bash
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
|
||||
stats
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats
|
||||
```
|
||||
|
||||
Output: slot, epoch, transactions per second, total/circulating supply, node version.
|
||||
### 8. Price Lookup
|
||||
|
||||
---
|
||||
Quick price check for any token by mint address or known symbol.
|
||||
|
||||
## Raw curl Examples (no script needed)
|
||||
|
||||
SOL balance:
|
||||
```bash
|
||||
curl -s https://api.mainnet-beta.solana.com \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc":"2.0","id":1,"method":"getBalance",
|
||||
"params":["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"]
|
||||
}' | python3 -c "
|
||||
import sys,json
|
||||
r=json.load(sys.stdin)
|
||||
lamports=r['result']['value']
|
||||
print(f'Balance: {lamports/1e9:.4f} SOL')
|
||||
"
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price BONK
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price JUP
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price SOL
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
|
||||
```
|
||||
|
||||
Network slot check:
|
||||
```bash
|
||||
curl -s https://api.mainnet-beta.solana.com \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}' \
|
||||
| python3 -c "import sys,json; print('Slot:', json.load(sys.stdin)['result'])"
|
||||
```
|
||||
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
|
||||
|
||||
- Public RPC rate-limits apply. For production use, get a private endpoint (Helius, QuickNode, Triton).
|
||||
- NFT detection is heuristic (amount=1, decimals=0). Compressed NFTs (cNFTs) won't appear.
|
||||
- Transactions older than ~2 days may not be on the public RPC history.
|
||||
- Whale detector scans only the latest block; old large transfers won't show.
|
||||
- Token supply is a raw integer — divide by 10^decimals for human-readable value.
|
||||
- Some RPC methods (e.g. getTokenLargestAccounts) may require commitment=finalized.
|
||||
- **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 number if RPC is reachable
|
||||
curl -s https://api.mainnet-beta.solana.com \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}' \
|
||||
| python3 -c "import sys,json; r=json.load(sys.stdin); print('OK, slot:', r['result'])"
|
||||
# Should print current Solana slot, TPS, and SOL price
|
||||
python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue