nft-market-analyzer – Solana NFT Collection Risk Analysis Skill

[nftpoetrist]

Overview

This PR introduces nft-market-analyzer, a production-grade Hermes Skill that performs
read-only risk analysis on Solana NFT collections by combining Magic Eden marketplace data
with Helius on-chain data. All seven risk metrics are computed deterministically in shell
(jq + bc) before being passed to the Hermes LLM for narrative interpretation — the LLM
never fetches data or calculates numbers.

---

What This Skill Does

• Fetches floor price, 7d/30d volume, and recent sales from Magic Eden v2 API
• Fetches holder distribution and on-chain ownership data from Helius DAS API
• Computes 7 deterministic risk metrics entirely in shell:
  • floor_price_sol — current floor price in SOL
  • volume_7d_sol / volume_30d_sol — trading volume
  • top10_holder_percentage — whale concentration risk
  • wash_trading_ratio — suspicious buy/sell loop detection
  • volume_volatility_ratio — volume stability vs 30-day average
  • final_risk_score — weighted composite score clamped to [0–100]
• Emits structured JSON consumed by Hermes for plain-language risk narrative

---

Architecture

Layer	Responsibility
scripts/analyze.sh	Fetch → Compute → Validate → Emit JSON
prompts/interpret_analysis.md	LLM interprets JSON into narrative
docs/output_schema.json	JSON Schema Draft-07 for output validation
tests/test_metrics.sh	30 unit assertions, no API keys required

Core design principle: Shell computes all numbers. LLM writes only the narrative.

---

Security

• ✅ No private keys, no transaction signing, no wallet manipulation
• ✅ No automated offers or bids — read-only API usage only
• ✅ API keys injected exclusively via environment variables
• ✅ Input sanitized against ^[a-z0-9_-]{1,64}$ to prevent shell injection
• ✅ Rate limit backoff: 429 → sleep attempt × 10s
• ✅ stdout = JSON only · stderr = structured logs (clean separation)
• ✅ Temp files purged on exit via trap

---

Testing

# Unit tests — no API keys required
bash tests/test_metrics.sh
# Expected: PASSED: 30  FAILED: 0

# Live integration test
export MAGICEDEN_API_KEY=<your_key>
export HELIUS_API_KEY=<your_key>
bash scripts/analyze.sh okay_bears | jq .risk_metrics

# Hermes CLI test
hermes --toolsets skills \
  -q "Analyze the okay_bears NFT collection for wash trading and holder concentration risk"

# Error path test
unset MAGICEDEN_API_KEY
bash scripts/analyze.sh okay_bears | jq .error
# Expected: { "message": "MAGICEDEN_API_KEY is not set", "code": "MISSING_ENV_VAR" }

---

Files Added

File	Description
skill.yaml	Hermes skill manifest with typed I/O schema and discovery metadata
SKILL.md	LLM-facing documentation: procedure, pitfalls, verification steps
scripts/analyze.sh	Main execution script (270 lines, fully commented)
prompts/interpret_analysis.md	Hermes LLM prompt template for narrative generation
docs/output_schema.json	JSON Schema Draft-07 for output validation
docs/api_reference.md	Complete curl examples and jq calculation formulas
tests/test_metrics.sh	30-assertion unit test suite, Linux/macOS compatible
README.md	Operator guide with Hermes CLI usage examples

---

Platforms Tested

Platform	Shell	jq	Status
Linux (Ubuntu 22.04)	bash 5.1	1.6	✅ Passing
macOS (Ventura 13.x)	bash 3.2	1.7.1	✅ Passing
Windows (WSL2 Ubuntu)	bash 5.1	1.6	✅ Passing

---

Breaking Changes

None. New skill addition.