token-research

Original source / Raw SKILL.md

---
name: token-research
description: Comprehensive token research for EVM chains (Base, ETH, Arbitrum) and Solana. Use this skill when you want to research crypto tokens, deep-dive projects or monitor tokens.
---

This skill is a comprehensive token research for EVM chains (Base, ETH, Arbitrum) and Solana. Two modes: **deep_research** and **shallow_dive**.

## MANDATORY: CALL Owner FOR WATCH OR APE TOKENS

**ANY token rated WATCH 🟡 or APE 🟢 → IMMEDIATELY call your owner + send Telegram/discord/whatsapp DM. NO EXCEPTIONS.**

1. Run `~/workspace/scripts/ape-call.sh "WATCH/APE alert: $TICKER at $MCAPk mcap, $VOLk volume. [1-line reason]"` ( or call normally if there's no script )
2. Send a DM to your owner with full analysis
3. Do BOTH — call AND message. Every time.

**DO NOT:** say "if owner were awake", filter out tokens because "pure meme" or "no narrative", or process alerts without calling.

## MANDATORY: ALWAYS RESEARCH ON X/TWITTER — SKIP PURE MEMES

**For EVERY token, before giving a verdict, check X/Twitter:**
1. Search `$TICKER` and project name (Latest + Top)
2. Check the project's Twitter account: tweets, bio, what they're building
3. Look for a PRODUCT (website, GitHub, app, protocol)

**IMPORTANT:** use the 'x-research' skill to search on X.

**If the product is real, CALL your owner regardless of chart action.** Bad charts on real products = buying opportunity, not a skip.

**Pure memes = AVOID by default.** Only exception: volume 10x+ the batch average.

## Reports & Watchlist

**Reports:** `reports/YYYY-MM-DD/[report-name].md`
**Watchlist:** `watchlists/YYYY-MM/watchlist.md`

### Watchlist Rules
- After any research, if token has real product/team or unique narrative → append to watchlist
- Tiers: **Tier 1** (strongest), **Tier 2** (good signal, higher risk), **Tier 3** (speculative)
- Each entry: token, chain, CA, entry MC, current MC, catalyst, status (🟢🟡🔴)
- APPEND only — never overwrite. Update status when new data comes in.

---

## DEEP RESEARCH

### Phase 1: Token Fundamentals
```bash
curl -s "https://api.dexscreener.com/latest/dex/tokens/CHAIN/TOKEN_ADDRESS"
curl -s "https://api.gopluslabs.io/api/v1/token_security/CHAIN_ID?contract_addresses=TOKEN_ADDRESS"
```

### Phase 2: X/Twitter Research (most important phase)

```bash
# Search by ticker, CA, and project name
curl -s "https://api.twitterapi.io/twitter/tweet/advanced_search?query=\$TICKER&queryType=Latest" -H "X-API-Key: $TWITTERAPI_KEY"
curl -s "https://api.twitterapi.io/twitter/tweet/advanced_search?query=TOKEN_ADDRESS&queryType=Latest" -H "X-API-Key: $TWITTERAPI_KEY"

# Project account info + tweets
curl -s "https://api.twitterapi.io/twitter/user/info?userName=PROJECT_HANDLE" -H "X-API-Key: $TWITTERAPI_KEY"
curl -s "https://api.twitterapi.io/twitter/user/last_tweets?userName=PROJECT_HANDLE" -H "X-API-Key: $TWITTERAPI_KEY"

# KOL mentions
curl -s "https://api.twitterapi.io/twitter/tweet/advanced_search?query=\$TICKER%20min_faves:50&queryType=Top" -H "X-API-Key: $TWITTERAPI_KEY"

# Founder research (if found)
curl -s "https://api.twitterapi.io/twitter/user/info?userName=FOUNDER_HANDLE" -H "X-API-Key: $TWITTERAPI_KEY"
```

⚠️ **VERIFY dev claims from THEIR OWN ACCOUNT.** Never trust holder/community claims about dev endorsement. Search `from:DEV_HANDLE` for mentions of the token. If dev hasn't posted about it → flag as unconfirmed.

### Phase 3: Web Research
Search for: project website, team/founder background, news/partnerships, Reddit sentiment.

### Phase 4: Narrative Assessment

**Narrative Score (add to every report):**
- 🔥 **Strong** — Novel concept, viral potential, clear catalyst
- 🟡 **Moderate** — Decent angle but not unique, or good concept with weak execution
- 🧊 **Weak/None** — Generic, repetitive, no story → likely dumps to zero

Key questions: Is it novel? Would someone share it unprompted? Is the market tired of this category? Why hold beyond a flip?

Smart money wallet count + narrative quality are better predictors than contract safety.

### Phase 5: Risk Synthesis
Combine: narrative quality, smart money interest, contract security, holder concentration, team transparency, social proof (organic vs bots), liquidity depth, buy/sell ratio.

---

## SHALLOW DIVE

Run only: DexScreener + GoPlus + one Twitter search + basic web search.

---

## Batch Research (5+ Tokens)

1. Spawn parallel sub-agents for concurrent research
2. After filtering, **auto deep dive top 1-3 tokens** without waiting for user to ask
3. Save report to `reports/YYYY-MM-DD/[N]-token-analysis.md`
4. Auto-add top picks to monthly watchlist


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# 🔍 Token Research Skill

A comprehensive cryptocurrency token research framework supporting both quick assessments and deep analysis across multiple blockchains.

## Files Overview

- **`SKILL.md`** - Complete skill documentation with research templates
- **`fetch_token_data.sh`** - Automated data collection script  
- **`api_reference.md`** - Quick API commands and examples
- **`example_usage.md`** - Step-by-step usage examples
- **`README.md`** - This overview file

## Quick Start

### 1. Shallow Dive (5 minutes)
```bash
./fetch_token_data.sh shallow 0x6982508145454ce325ddbe47a25d4ec3d2311933 ethereum
```

### 2. Deep Research (15-20 minutes)
```bash
./fetch_token_data.sh deep 0x6982508145454ce325ddbe47a25d4ec3d2311933 ethereum
```

### 3. Manual Analysis
Follow the templates in `SKILL.md` for social sentiment and community research using web_search.

## Supported Chains

| Chain | ID | Example Address |
|-------|----| ---------------|
| Ethereum | 1 | 0x6982508145454ce325ddbe47a25d4ec3d2311933 |
| Base | 8453 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| BSC | 56 | 0x... |
| Arbitrum | 42161 | 0x... |
| Solana | solana | So11111111111111111111111111111111111111112 |

## APIs Used

- **DexScreener** - Price, liquidity, volume data
- **GoPlus Security** - Token security analysis
- **Etherscan/Basescan** - On-chain data and holder analysis
- **Web Search** - Social sentiment and project research

## Research Modes

### Shallow Dive
Perfect for quick screening:
- ✅ Token basics & price
- ✅ Security check
- ✅ Top 3 holders
- ✅ Social narrative search

### Deep Research  
Comprehensive analysis:
- ✅ Complete fundamentals
- ✅ Holder distribution analysis
- ✅ Team/founder research
- ✅ Community sentiment analysis
- ✅ Risk assessment
- ✅ Market analysis

## Research Output

Both modes generate structured reports with:
- Token fundamentals
- Price and market data
- Security assessment
- Holder analysis
- Risk evaluation
- Investment thesis

## Important Notes

- **Always verify contract addresses** before research
- **Respect API rate limits** (see api_reference.md)
- **Cross-reference multiple sources** for accuracy
- **Use web_search for social analysis** not covered by APIs
- **Consider this as research assistance, not financial advice**

## 💡 Usage Tips

1. **Start with shallow dive** for initial screening
2. **Use deep research** for serious investment consideration  
3. **Combine automated data** with manual social research
4. **Check recent news** and community sentiment
5. **Verify team credentials** and project legitimacy
6. **Monitor holder concentration** and whale activity

## 🔗 Getting Started

1. Read `SKILL.md` for complete documentation
2. Check `example_usage.md` for step-by-step workflows
3. Use `api_reference.md` for quick command lookup
4. Run the automated script: `./fetch_token_data.sh`

## 📞 Support

This skill is designed to be used by AI agents following the templates and workflows. All necessary commands, APIs, and procedures are documented in the skill files.

---

**⚠️ Disclaimer**: This tool is for research purposes only. Always do your own research and consult with financial advisors before making investment decisions.
```

### _meta.json

```json
{
  "owner": "0xartex",
  "slug": "token-research",
  "displayName": "Token Research",
  "latest": {
    "version": "1.0.0",
    "publishedAt": 1773101759204,
    "commit": "https://github.com/openclaw/skills/commit/cbb21be78fb680766c8f7cd8d081c9050637b510"
  },
  "history": []
}

```

### example_usage.md

```markdown
# Token Research Skill - Usage Examples

## Quick Start

### Example 1: Shallow Dive on PEPE (Ethereum)
```bash
# Use the helper script
./fetch_token_data.sh shallow 0x6982508145454ce325ddbe47a25d4ec3d2311933 ethereum

# Manual research for social sentiment
web_search("PEPE meme token narrative crypto twitter")
web_search("PEPE holders whale wallets movement")
```

**Expected Output:**
- Price, volume, liquidity from DexScreener
- Security analysis from GoPlus 
- Top 3 token holders from Etherscan
- Social narrative from web search

### Example 2: Deep Research on a Base Token
```bash
# Use helper script for data collection
./fetch_token_data.sh deep 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 base

# Additional manual research
web_search("Base USDC official Circle announcement")
web_search("Base chain adoption USDC usage statistics")
web_search("Circle team founders background USDC")
```

## Complete Research Workflow

### Step 1: Data Collection
```bash
# Set variables
TOKEN_ADDRESS="0x6982508145454ce325ddbe47a25d4ec3d2311933"
CHAIN="ethereum"

# Run automated data fetch
./fetch_token_data.sh deep $TOKEN_ADDRESS $CHAIN
```

### Step 2: Data Analysis
```bash
# Navigate to results folder
cd research_*_69825081

# Check data quality
cat research_summary.txt

# Analyze key files
cat dexscreener.json | jq '.pairs[0] | {price: .priceUsd, volume: .volume.h24, liquidity: .liquidity.usd}'
cat security.json | jq '.result | to_entries[0].value | {honeypot: .is_honeypot, mintable: .is_mintable, buy_tax: .buy_tax}'
cat holders.json | jq '.result[:3] | .[] | {address: .TokenHolderAddress, balance: .TokenHolderQuantity}'
```

### Step 3: Social Research
```bash
# Project fundamentals
web_search("PEPE official website social media")
web_search("PEPE meme token what is purpose utility")

# Team research
web_search("PEPE founder team anonymous doxxed")
web_search("PEPE development team background")

# Community sentiment
web_search("PEPE crypto twitter bullish bearish sentiment")
web_search("PEPE telegram discord community size")
web_search("PEPE KOL influencer mentions analysis")

# Recent activity
web_search("PEPE news announcement partnership 2024")
web_search("PEPE price pump dump reason why")
```

### Step 4: Risk Assessment
```bash
# Security deep dive
web_search("PEPE contract audit security report")
web_search("PEPE rug pull scam honeypot warning")
web_search("PEPE liquidity locked team tokens")

# Market risks
web_search("PEPE meme token risks volatility")
web_search("PEPE whale wallets large holders")
```

## Advanced Research Techniques

### Holder Analysis Deep Dive
```bash
# Get full holder list
curl "https://api.etherscan.io/api?module=token&action=tokenholderlist&contractaddress=$TOKEN_ADDRESS&page=1&offset=1000&sort=desc"

# Check if top holders are known entities
web_search("0x... ethereum address label who owns")

# Calculate concentration metrics
# Top 10 holders percentage
# Gini coefficient for distribution
# Number of holders vs supply
```

### Cross-Chain Analysis
```bash
# Check if token exists on multiple chains
web_search("TOKEN_NAME multi-chain ethereum polygon BSC")

# Compare liquidity across chains
curl "https://api.dexscreener.com/latest/dex/search?q=TOKEN_SYMBOL" | jq '.pairs[] | select(.chainId != null) | {chain: .chainId, liquidity: .liquidity.usd}'
```

### Time-Series Analysis
```bash
# Historical price data (if available)
web_search("TOKEN_NAME price history chart coingecko dextools")

# Launch analysis
web_search("TOKEN_NAME launch date first trade stealth fair launch")
```

## Red Flags Checklist

During research, watch for these warning signs:

### 🚨 HIGH RISK
- [ ] Honeypot detected by GoPlus
- [ ] >50% supply held by top 10 wallets
- [ ] Anonymous team with no previous projects
- [ ] No verified contract
- [ ] Unlimited mint authority
- [ ] >5% buy/sell tax

### ⚠️ MEDIUM RISK
- [ ] 20-50% top holder concentration
- [ ] High volatility without clear catalysts
- [ ] New project (<30 days)
- [ ] Limited social presence

### ✅ POSITIVE INDICATORS
- [ ] Team fully doxxed with track record
- [ ] Liquidity locked long-term
- [ ] Active development and community
- [ ] Clear utility/value proposition
- [ ] Distributed holder base

## Sample Research Reports

### Shallow Dive Output
```
🔍 SHALLOW DIVE: Pepe (PEPE)

💰 BASICS
• Price: $0.000008 (24h: +12.5%)
• Market Cap: $3.2B | Liquidity: $45M
• Age: 287 days | Chain: Ethereum
• Contract: 0x6982508145454ce325ddbe47a25d4ec3d2311933

🛡️ SECURITY
• Honeypot: ✅ | Ownership: Renounced
• Risk Level: LOW

📱 NARRATIVE
• Project: Meme token inspired by Pepe the Frog
• Narrative: Community-driven meme coin with no utility

👥 TOP HOLDERS
1. 0x41...62f - 7.2% (Binance Hot Wallet)
2. 0x28...891 - 3.8% (Unknown)
3. 0x77...123 - 2.1% (Uniswap V3 Pool)

⚠️ QUICK ASSESSMENT: Established meme token with reasonable distribution. Standard meme coin risks apply.
```

## Automation Tips

### Batch Analysis
```bash
# Research multiple tokens
TOKENS=("0x6982..." "0xA0b86..." "0xdAC17...")
for token in "${TOKENS[@]}"; do
    ./fetch_token_data.sh shallow "$token" ethereum
    sleep 30  # Respect rate limits
done
```

### Monitoring Setup
```bash
# Create monitoring script for price alerts
echo '#!/bin/bash
TOKEN="0x6982508145454ce325ddbe47a25d4ec3d2311933"
CURRENT_PRICE=$(curl -s "https://api.dexscreener.com/latest/dex/tokens/ethereum/$TOKEN" | jq -r ".pairs[0].priceUsd")
echo "PEPE: $CURRENT_PRICE"
' > monitor_price.sh
chmod +x monitor_price.sh
```

Remember: Always verify critical information through multiple sources and never rely solely on automated analysis for investment decisions.
```