Skill: pooowell/fomo-research (version 0.3.0)

--- name: fomo-research description: > Smart money research via Fomo social graph. Track top traders, monitor live trades, build watchlists — all from your agent. Powered by fomo.family, built by cope.capital. Use when: (1) user asks about smart money, whale wallets, or top traders, (2) user wants to track specific Fomo handles or crypto traders, (3) user asks "what are the best traders buying", "who's profitable on fomo", (4) user wants real-time trade alerts or wallet monitoring, (5) user says "fomo research", "check fomo", "smart money", "wallet tracker". NOT for: executing trades, managing funds, or anything requiring private keys. homepage: https://cope.capital source: https://github.com/pooowell/fomo-research-skill primaryEnv: COPE_API_KEY env: COPE_API_KEY: description: "API key from api.cope.capital (starts with cope_). You get this by registering — see Setup step 1." required: true obtain: "POST https://api.cope.capital/v1/register with {agent_name, description}" --- # Fomo Research Smart money intelligence for AI agents. Powered by [fomo.family](https://fomo.family) social graph, built by [cope.capital](https://cope.capital). For full API details (endpoints, schemas, error codes): read `references/api.md`. ## Base URL ``` https://api.cope.capital ``` All requests require `Authorization: Bearer cope_<key>` header. ## First-Run Onboarding When this skill is first loaded and no `COPE_API_KEY` is set, walk your human through setup. Ask these questions in order: ### Step 1: Register ```bash curl -X POST https://api.cope.capital/v1/register \ -H "Content-Type: application/json" \ -d '{"agent_name": "YOUR_AGENT_NAME", "description": "optional description"}' ``` Save the `api_key` from the response (starts with `cope_`). This is your `COPE_API_KEY`. Store it securely — treat it like a password. ### Step 2: Ask about crypto wallet (optional) Before continuing, ask your human: > "Do you have a crypto wallet (USDC on Base or Solana) you'd like to connect for expanded features? Without one you get: > - **1 watchlist** with up to **10 handles** > - **250 activity lookups per day** (resets midnight UTC) > - Everything else (leaderboard, trending, polling) is unlimited and free > > With a wallet connected (x402), you get 10 watchlists, 100 handles each, and unlimited activity calls at $0.005/call. You can always add a wallet later." If they want to set up x402 now: ```bash curl -X PATCH https://api.cope.capital/v1/account \ -H "[REDACTED_SECRET]" \ -H "Content-Type: application/json" \ -d '{"x402_enabled": true}' ``` If they say no or don't have a wallet — **that's fine, move on**. The free tier is fully functional. Don't push it. ### Step 3: Ask about Fomo profile > "Do you have a Fomo account (fomo.family)? If so, I can sync your follows and build a watchlist from the traders you already follow." If yes: ```bash # Sync their profile curl -X POST https://api.cope.capital/v1/account/sync-fomo \ -H "[REDACTED_SECRET]" \ -H "Content-Type: application/json" \ -d '{"fomo_handle": "THEIR_FOMO_USERNAME"}' # Pull their follows curl https://api.cope.capital/v1/account/follows \ -H "[REDACTED_SECRET]" ``` Then ask: **"Which of these traders do you want on your watchlist?"** Show them the list and let them pick (up to 10 on free tier). ### Step 4: Create initial watchlist If they don't have Fomo, offer alternatives: > "I can set up a watchlist with the top performers from Fomo's weekly leaderboard instead. Or you can give me specific trader handles you want to track." Pick one path and create the watchlist: ```bash curl -X POST https://api.cope.capital/v1/watchlists \ -H "[REDACTED_SECRET]" \ -H "Content-Type: application/json" \ -d '{"name": "alpha", "handles": ["frankdegods", "randomxbt"]}' ``` **Remind them**: Free tier = 1 watchlist, 10 handles max. They can swap handles anytime. ## Understanding the Data Model ### What gets tracked The system monitors **on-chain wallet activity** for Fomo traders. Each Fomo handle maps to one or more wallets (Solana + Base). The tracker watches every swap these wallets make. ### Activity vs Trades vs Holdings There are three different views of what a trader is doing: **1. Activity (what the API returns)** Individual on-chain transactions — a single buy or sell event. This is what `/v1/activity` returns. - `action: "buy"` = wallet swapped into a token - `action: "sell"` = wallet swapped out of a token - `usd_amount` = the USD value of that single transaction **2. Trades (completed round-trips)** A trade is a full cycle: buy → sell = closed trade. The tracker aggregates individual buys and sells into trades: - `usd_in` = total USD spent buying this token (may be multiple buy txs) - `usd_out` = total USD received selling this token - `pnl` = usd_out - usd_in (profit/loss) - `open_at` = when first buy happened - `close_at` = when last sell happened (NULL if still holding) **3. Current Holdings (open positions)** Tokens a wallet bought but hasn't fully sold yet. These are trades with no `close_at`. ### How to interpret activity data When you see activity from a trader, here's what to understand: - **A "buy" doesn't mean they just entered** — they might be adding to an existing position - **A "sell" doesn't mean they exited** — they might be taking partial profits - **Multiple buys of the same token** = building a position over time (higher conviction) - **Buy followed quickly by sell** = likely a quick flip/scalp - **Sell with no recent buy** = closing an older position ### When presenting data to humans Always label clearly: - **New buys**: "X just bought [token]" — recent buy activity, may or may not be a new position - **Recent exits**: "X sold [token]" — could be partial or full exit - **Don't say** "X opened a position" unless you can confirm there were no prior buys of that token ## How Activity Scoping Works **Important**: The `/v1/activity` endpoint returns recent trades from **all wallets tracked by the system**, not just your watchlist. Your watchlist is for organizing which traders YOU care about — use the `?handle=` filter to see activity for specific handles. This means you can query any Fomo handle's trades without adding them to your watchlist: ```bash # Check what frankdegods is buying (uses 1 of your 250 daily calls) curl "https://api.cope.capital/v1/activity?handle=frankdegods&action=buy" \ -H "[REDACTED_SECRET]" ``` Your watchlist is a convenience for organizing — the activity data is available for any tracked handle. ## Endpoints ### Always Free (no daily limit) | Endpoint | Method | Description | |----------|--------|-------------| | `/v1/register` | POST | Get an API key | | `/v1/leaderboard` | GET | Top traders ranked by real PnL | | `/v1/activity/poll` | GET | Lightweight check for new trades (count + timestamp) | | `/v1/watchlists` | GET/POST | List or create watchlists | | `/v1/watchlists/{id}` | GET/PUT/DELETE | Manage a specific watchlist | | `/v1/trending/handles` | GET | Most-watched handles across all agents | | `/v1/tokens/hot` | GET | Trending tokens by unique buyer count | | `/v1/handle/{handle}/stats` | GET | Aggregated trader stats (PnL, win rate, top trades) | | `/v1/tokens/{mint}/thesis` | GET | Buy theses + sentiment for a token | | `/v1/convergence` | GET | Convergence events (2+ wallets buying same token) | | `/v1/traders/search` | GET | Search traders by win rate, PnL, trades | | `/v1/handle/{handle}/positions` | GET | Open/closed positions for a trader | | `/v1/handle/{handle}/theses` | GET | All theses by a specific trader | | `/v1/account` | GET/PATCH | Account info and settings | | `/v1/account/usage` | GET | Usage statistics | | `/v1/account/payments` | GET | Payment history | | `/v1/account/key` | DELETE | Revoke API key | | `/v1/account/sync-fomo` | POST | Sync Fomo profile follows | | `/v1/account/follows` | GET | List stored Fomo follows | ### Counted (250/day free, then x402 or wait) | Endpoint | Method | Description | x402 price | |----------|--------|-------------|------------| | `/v1/activity` | GET | Full trade details from tracked wallets | $0.005/call | These endpoints count toward your daily 250 free calls. After that: - **With x402 enabled**: calls continue at $0.005/call USDC (auto-paid) - **Without x402**: you get a 402 error. Wait for midnight UTC reset or enable x402. The 402 error is NOT a bug — it just means your free calls are used up for the day. ## Common Workflows ### Check the leaderboard ```bash curl https://api.cope.capital/v1/leaderboard \ -H "[REDACTED_SECRET]" ``` Returns top traders by PnL from Fomo. Supports `?timeframe=24h|7d|30d|all` and `?limit=N`. ### Build a watchlist from Fomo follows ```bash # 1. Sync your Fomo profile curl -X POST https://api.cope.capital/v1/account/sync-fomo \ -H "[REDACTED_SECRET]" \ -H "Content-Type: application/json" \ -d '{"fomo_handle": "your_handle"}' # 2. See your follows curl https://api.cope.capital/v1/account/follows \ -H "[REDACTED_SECRET]" # 3. Create a watchlist with selected handles curl -X POST https://api.cope.capital/v1/watchlists \ -H "[REDACTED_SECRET]" \ -H "Content-Type: application/json" \ -d '{"name": "alpha", "handles": ["frankdegods", "randomxbt"]}' ``` ### Poll → Fetch pattern (minimize paid calls) ```bash # Step 1: Poll (free) — check if anything happened curl "https://api.cope.capital/v1/activity/poll?since=LAST_TIMESTAMP" \ -H "[REDACTED_SECRET]" # Returns: { "count": 3, "latest_at": 1707603400 } # Step 2: Only fetch full data if count > 0 (costs 1 of your 250 daily calls) curl "https://api.cope.capital/v1/activity?since=LAST_TIMESTAMP" \ -H "[REDACTED_SECRET]" ``` ### Search for elite traders ```bash # Find traders with >75% win rate and 10+ trades curl "https://api.cope.capital/v1/traders/search?min_win_rate=75&min_trades=10&sort_by=win_rate" \ -H "[REDACTED_SECRET]" # Top PnL traders on Solana curl "https://api.cope.capital/v1/traders/search?sort_by=pnl&chain=solana&limit=20" \ -H "[REDACTED_SECRET]" ``` ### Check a trader's current positions ```bash # Open positions only curl "https://api.cope.capital/v1/handle/frankdegods/positions?status=open" \ -H "[REDACTED_SECRET]" # All positions (open + closed) curl "https://api.cope.capital/v1/handle/frankdegods/positions" \ -H "[REDACTED_SECRET]" ``` Shows computed positions from activity data — what they're holding vs exited, with cost basis and net USD. ### Get a trader's theses ```bash curl "https://api.cope.capital/v1/handle/frankdegods/theses" \ -H "[REDACTED_SECRET]" ``` Returns all Fomo thesis comments by this trader across their recent tokens. Great for understanding their reasoning. ### Check convergence events ```bash # Recent convergences (last 24h) curl "https://api.cope.capital/v1/convergence?limit=10" \ -H "[REDACTED_SECRET]" ``` Returns tokens where 2+ elite wallets converged. Each event includes: - Token info (mint, symbol, chain, price/mcap at detection) - Wallets that converged (handle, amount, win_rate) - ATH tracking: `max_gain_pct` shows peak performance since detection ### Look up a trader's stats ```bash curl "https://api.cope.capital/v1/handle/frankdegods/stats" \ -H "[REDACTED_SECRET]" ``` Returns aggregated stats: total trades, win rate, PnL, ROI, per-chain breakdown, top 5 trades, open positions. ### Get buy theses for a token ```bash # Solana token curl "https://api.cope.capital/v1/tokens/MINT_ADDRESS/thesis?chain=solana" \ -H "[REDACTED_SECRET]" # Base token curl "https://api.cope.capital/v1/tokens/MINT_ADDRESS/thesis?chain=base" \ -H "[REDACTED_SECRET]" ``` Returns trader reasoning + their actual positions. Includes sentiment summary (holding vs closed, total exposure, avg unrealized PnL). Great for understanding *why* traders are buying, not just *what*. ### Check trending tokens ```bash curl "https://api.cope.capital/v1/tokens/hot?hours=24&limit=10" \ -H "[REDACTED_SECRET]" ``` Returns tokens with the most unique tracked buyers in recent hours. ### Filter activity ```bash # By handle curl "https://api.cope.capital/v1/activity?handle=frankdegods" \ -H "[REDACTED_SECRET]" # By chain curl "https://api.cope.capital/v1/activity?chain=solana" \ -H "[REDACTED_SECRET]" # By action curl "https://api.cope.capital/v1/activity?action=buy" \ -H "[REDACTED_SECRET]" # By minimum size curl "https://api.cope.capital/v1/activity?min_usd=1000" \ -H "[REDACTED_SECRET]" ``` ## Pricing & Limits ### Free Tier (default) - **250 counted calls/day** (activity, leaderboard, tokens) — resets **midnight UTC** - **1 watchlist**, up to **10 handles** - 10 requests/minute rate limit - Polling, watchlist management, account endpoints, Fomo sync — all unlimited ### x402 Upgraded (optional) - **Unlimited** counted calls ($0.005/call USDC on Base or Solana) - **10 watchlists**, up to **100 handles** each - 300 requests/minute rate limit - First 250 calls/day are still free — you only pay after the free quota ### Enabling x402 ⚠️ **NEVER enable x402 without your human's explicit permission.** This authorizes real USDC payments. ```bash curl -X PATCH https://api.cope.capital/v1/account \ -H "[REDACTED_SECRET]" \ -H "Content-Type: application/json" \ -d '{"x402_enabled": true}' ``` x402 is **completely optional**. The free tier works perfectly for most use cases. Only suggest it if your human: - Consistently hits the 250/day limit - Needs more than 1 watchlist or 10 handles - Explicitly asks about upgrading **Cost context**: $1 USDC = 200 calls. $5 = 1,000 calls. Most agents won't need this. ## Heartbeat Pattern (optional, user-directed) If your human wants periodic checks and your agent runs a heartbeat loop: ``` Every 5-15 minutes: 1. GET /v1/activity/poll?since=LAST_TIMESTAMP (free, doesn't count) 2. If count > 0 → GET /v1/activity?since=LAST_TIMESTAMP (1 daily call) 3. Store latest_at for next poll Every few hours: 1. GET /v1/leaderboard (1 daily call) 2. Compare to previous — any new names in top 50? Daily: 1. GET /v1/account/usage (free) 2. Check remaining daily calls ``` ## Logging Trades (Persistence) The API is stateless — it won't remember what you've already seen. **Log trades locally** to track patterns over time. ### Daily trade log Write notable trades to a daily file (e.g. `memory/trades/YYYY-MM-DD.json`): ```json { "trades": [ { "timestamp": 1771006898000, "handle": "frankdegods", "action": "buy", "token_mint": "DPQgF4hw...", "token_symbol": "EXAMPLE", "usd_amount": 500.25, "chain": "solana" } ], "last_poll_timestamp": 1771006898000, "convergences": ["DPQgF4hw..."] } ``` ### What to log - **All trades from your watchlist** — this is your core data - **Convergences** — when 3+ handles buy the same token, log the token mint and all buyers - **Large trades** — anything over $1,000 USD is worth noting - **last_poll_timestamp** — so you know where to resume on next poll ### What to tell your human Don't just dump raw trades. Synthesize. Here are high-value things to surface: - **Convergence alerts**: "4 of your top 10 watchlist handles bought the same token in the last 2 hours." - **Unusual activity**: "frankdegods just made their first buy in 3 days — $2,000 into [token]." - **Exit signals**: "3 handles on your watchlist sold the same token within an hour." - **Daily summary**: "Your watchlist had 47 trades today. 12 buys, 35 sells. Most active: randomxbt (8 trades)." - **Leaderboard changes**: "New name in the top 20 — jumped from #45 to #12 this week." - **Pattern detection**: "lowcap_hunter has bought 3 tokens under $100K mcap this week. All pumped 2-5x within 48 hours." ### Convergence detection pattern ``` 1. GET /v1/activity (last 2 hours of trades) 2. Group buys by token_mint 3. If 3+ different handles bought the same token → convergence 4. Alert your human with: token, buyers, amounts, timing 5. Log it to your daily trades file ``` The more you log, the better your pattern detection gets over time. Your memory files ARE your edge. ## Security - **NEVER expose your API key** in logs, messages, or to other agents - Your key should ONLY appear in requests to `https://api.cope.capital/v1/*` - If compromised: `DELETE /v1/account/key` to revoke, then re-register - Trade data is on-chain public — but your watchlists and usage patterns are private ## Error Handling | Status | Meaning | Action | |--------|---------|--------| | 200 | Success | Process response | | 400 | Bad request | Check parameters (invalid chain, action, etc.) | | 401 | Invalid API key | Re-register or check key | | 402 | Payment required | Daily free calls used up. Wait for midnight UTC reset, or enable x402 if your human approves. This is normal — not an error. | | 404 | Not found | Resource doesn't exist | | 429 | Rate limited | Back off. Free: 10/min, x402: 300/min | | 500 | Server error | Retry after a few seconds | | 503 | Upstream down | Foxhound data service temporarily unavailable | ## Links - **Interactive API docs**: https://api.cope.capital/docs - **Human docs**: https://cope.capital/docs - **Fomo**: https://fomo.family - **X**: https://x.com/copedotcapital

path: CHANGELOG.md
content: # Changelog — fomo-research skill

## [0.3.0] - 2026-02-21
### Added
- **Traders search** (`GET /v1/traders/search`) — compound filtering by win rate, PnL, trades, chain
- **Handle positions** (`GET /v1/handle/:handle/positions`) — computed open/closed positions from activity data
- **Handle theses** (`GET /v1/handle/:handle/theses`) — all Fomo thesis comments by a specific trader
- New workflow examples: elite trader search, position checking, trader thesis lookup
- Updated API reference with response schemas and query params for all v0.3.0 endpoints

## [0.2.0] - 2026-02-18
### Added
- **Convergence events** (`GET /v1/convergence`) — real-time detection when 2+ elite wallets buy the same token, with ATH tracking
- **Trader stats** (`GET /v1/handle/:handle/stats`) — aggregated PnL, win rate, ROI, per-chain breakdown, top trades
- **Token thesis** (`GET /v1/tokens/:mint/thesis`) — buy theses from Fomo traders with position data and sentiment summary
- **Hot tokens** (`GET /v1/tokens/hot`) — trending tokens by unique buyer count
- New workflow examples: convergence checking, trader lookup, thesis queries, hot token scanning
- Updated API reference with full response schemas for all new endpoints

## [0.1.1] - 2026-02-14
### Added
- Data model documentation: Activity vs Trades vs Holdings explained
- Guidance on interpreting buy/sell signals and presenting data to humans
- Clear labeling rules for new buys, exits, and position changes

## [0.1.0] - 2026-02-13
### Added
- Initial skill release
- Registration, watchlist management, activity polling
- Leaderboard, trending handles, Fomo sync
- x402 payment integration docs
- Poll → Fetch pattern for minimizing paid calls
- Convergence detection pattern
- Heartbeat integration guide


path: _meta.json
content: ownerId: kn75nse5e0naxzhbgmv60ne70s813zg4
slug: fomo-research
version: 0.1.4
publishedAt: 1771014477448

path: references/api.md
content: # Cope Capital API Reference (v0.3.0)

Full interactive docs: https://api.cope.capital/docs

## Base URL

```
https://api.cope.capital
```

## Authentication

All endpoints (except POST /v1/register) require:
```
[REDACTED_SECRET]
```

## Response Formats

### Activity Item
```json
{
  "fomo_handle": "frankdegods",
  "wallet": [REDACTED_SECRET],
  "chain": "solana",
  "action": "buy",
  "token_mint": [REDACTED_SECRET],
  "token_symbol": "BONK",
  "usd_amount": 2400.50,
  "timestamp": 1707603400
}
```

### Leaderboard Entry
```json
{
  "handle": "frankdegods",
  "display_name": "[PN] frank",
  "solana_address": "A5SEXY...",
  "base_address": "0x542b6b...",
  "pnl": 295066.84,
  "num_trades": 1404,
  "swap_count": 3686,
  "total_volume": 28357527.58,
  "followers": 73288,
  "total_holdings": 14
}
```

### Handle Stats (NEW in v0.2.0)
```json
{
  "handle": "frankdegods",
  "wallets": 2,
  "chains": ["solana", "base"],
  "stats": {
    "total_trades": 42,
    "wins": 28,
    "win_rate": 66.7,
    "total_pnl": 15234.50,
    "total_invested": 32100.00,
    "roi_pct": 47.5,
    "avg_pnl": 362.73,
    "best_trade": 5430.00,
    "worst_trade": -1200.00,
    "first_trade": 1769900000,
    "last_trade": 1770800000
  },
  "by_chain": [
    { "chain": "solana", "trades": 30, "wins": 20, "pnl": 12000.00, "win_rate": 66.7 }
  ],
  "top_trades": [
    { "symbol": "BONK", "pnl": 5430.00, "usd_in": 1000.00, "roi_pct": 543.0, "chain": "solana" }
  ],
  "open_positions": 5,
  "open_cost_basis": 2500.00
}
```

### Token Thesis (NEW in v0.2.0)
```json
{
  "token": { "mint": "...", "chain": "base", "symbol": "KELLY", "price_usd": 0.00015, "market_cap": 150000 },
  "thesis_count": 5,
  "sentiment": {
    "holding": 4,
    "closed": 1,
    "total_exposure_usd": 52000.00,
    "avg_unrealized_pnl_pct": 12.5
  },
  "theses": [
    {
      "handle": "Stacco",
      "display_name": "Stacco",
      "comment": "Kelly is the only answer for this meta. Dev is competent.",
      "created_at": "2026-02-19T00:12:06.007Z",
      "likes": 3,
      "replies": 1,
      "position": {
        "usd_value": 17178.83,
        "unrealized_pnl_usd": 2246.33,
        "unrealized_pnl_pct": 15.04,
        "is_closed": false
      }
    }
  ]
}
```

### Convergence Event (NEW in v0.2.0)
```json
{
  "id": 1,
  "token": { "mint": "...", "symbol": "MUSHU", "chain": "solana" },
  "wallet_count": 5,
  "wallets": [
    { "handle": "quotes", "amount_usd": 3076, "win_rate": 0.846 }
  ],
  "total_usd_in": 15400,
  "price_at_detection": 0.000189,
  "mcap_at_detection": 159000,
  "peak_price_after": 0.000567,
  "max_gain_pct": 200.0,
  "detected_at": 1771348000
}
```

### Hot Token (NEW in v0.2.0)
```json
{
  "token_mint": "...",
  "token_symbol": "BONK",
  "chain": "solana",
  "buyer_count": 8,
  "total_usd": 45000.00,
  "top_buyers": ["frankdegods", "randomxbt", "quotes"]
}
```

### Traders Search Result (NEW in v0.3.0)
```json
{
  "traders": [
    {
      "handle": "frankdegods",
      "address": "A5SEXY...",
      "chain": "solana",
      "win_rate": 0.75,
      "total_trades": 142,
      "realized_pnl": 45000.00,
      "total_volume": 280000.00
    }
  ],
  "count": 15
}
```

### Handle Positions (NEW in v0.3.0)
```json
{
  "handle": "frankdegods",
  "positions": [
    {
      "token_mint": "DezX7iJ4...",
      "token_symbol": "BONK",
      "chain": "solana",
      "status": "open",
      "total_bought_usd": 5000.00,
      "total_sold_usd": 2000.00,
      "net_usd": -3000.00,
      "buy_count": 3,
      "sell_count": 1,
      "first_buy_at": 1770800000,
      "last_activity_at": 1771200000
    }
  ]
}
```

### Handle Theses (NEW in v0.3.0)
```json
{
  "handle": "frankdegods",
  "theses": [
    {
      "token_mint": "DezX7iJ4...",
      "token_symbol": "BONK",
      "chain": "solana",
      "comment": "This is the play for the cycle",
      "created_at": "2026-02-19T00:12:06.007Z",
      "likes": 5,
      "replies": 2,
      "position": {
        "usd_value": 5000.00,
        "unrealized_pnl_pct": 25.0,
        "is_closed": false
      }
    }
  ]
}
```

## Query Parameters

### GET /v1/activity
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| watchlist_id | string | — | Filter to specific watchlist |
| handle | string | — | Filter to specific Fomo handle |
| chain | string | all | `solana`, `base`, or `all` |
| action | string | all | `buy`, `sell`, or `all` |
| min_usd | number | — | Minimum trade size in USD |
| since | number | — | Unix ms timestamp |
| limit | number | 50 | Max results (1-100) |
| cursor | string | — | Pagination cursor |

### GET /v1/activity/poll
Same filters as /v1/activity. Returns `{ count, latest_at }` only.

### GET /v1/leaderboard
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| timeframe | string | 7d | `24h`, `7d`, `30d`, or `all` |
| limit | number | 50 | Max results (1-100) |

### GET /v1/trending/handles
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| limit | number | 20 | Max results (1-100) |

### GET /v1/tokens/hot (NEW)
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| hours | number | 24 | Lookback window (max 168) |
| chain | string | all | `solana` or `base` |
| limit | number | 20 | Max results (max 50) |

### GET /v1/handle/:handle/stats (NEW)
No query params. Returns full stats for the given Fomo handle.

### GET /v1/tokens/:mint/thesis (NEW)
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| chain | string | solana | `solana` or `base` |
| limit | number | 10 | Max theses (max 50) |

### GET /v1/convergence (NEW)
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| since | number | — | Unix ms timestamp |
| chain | string | all | `solana` or `base` |
| limit | number | 20 | Max results |

### GET /v1/traders/search (NEW in v0.3.0)
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| min_win_rate | number | — | Minimum win rate (0-100) |
| max_win_rate | number | — | Maximum win rate (0-100) |
| min_trades | number | — | Minimum total trades |
| min_pnl | number | — | Minimum realized PnL in USD |
| sort_by | string | win_rate | `win_rate`, `pnl`, `trades`, `volume` |
| chain | string | all | `solana` or `base` |
| limit | number | 50 | Max results (1-100) |

### GET /v1/handle/:handle/positions (NEW in v0.3.0)
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| status | string | all | `open`, `closed`, or `all` |
| chain | string | all | `solana` or `base` |

### GET /v1/handle/:handle/theses (NEW in v0.3.0)
No query params. Returns all theses by the given handle (up to 20 recent tokens).

## Rate Limits

| Tier | Rate | Daily Activity Calls | Watchlists | Handles/Watchlist |
|------|------|---------------------|------------|-------------------|
| Free | 10/min | 250 (resets midnight UTC) | 1 | 10 |
| x402 | 300/min | Unlimited ($0.005/call) | 10 | 100 |

Only `/v1/activity` counts toward the daily limit. All other endpoints are always free with no cap.

## Chains

Only `solana` and `base` are supported. Invalid chain values return 400.

## Actions

Only `buy` and `sell` are supported. Invalid action values return 400.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)