Fomo Research

Fomo Research

Smart money intelligence for AI agents. Powered by fomo.family social graph, built by 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

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:

curl -X PATCH https://api.cope.capital/v1/account \
  -H "Authorization: Bearer cope_YOUR_KEY" \
  -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:

# Sync their profile
curl -X POST https://api.cope.capital/v1/account/sync-fomo \
  -H "Authorization: Bearer cope_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fomo_handle": "THEIR_FOMO_USERNAME"}'

# Pull their follows
curl https://api.cope.capital/v1/account/follows \
  -H "Authorization: Bearer cope_YOUR_KEY"

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:

curl -X POST https://api.cope.capital/v1/watchlists \
  -H "Authorization: Bearer cope_YOUR_KEY" \
  -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:

# Check what frankdegods is buying (uses 1 of your 250 daily calls)
curl "https://api.cope.capital/v1/activity?handle=frankdegods&action=buy" \
  -H "Authorization: Bearer cope_YOUR_KEY"

Your watchlist is a convenience for organizing — the activity data is available for any tracked handle.

Endpoints

Always Free (no daily limit)

Counted (250/day free, then x402 or wait)

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

curl https://api.cope.capital/v1/leaderboard \
  -H "Authorization: Bearer cope_YOUR_KEY"

Returns top traders by PnL from Fomo. Supports ?timeframe=24h|7d|30d|all and ?limit=N.

Build a watchlist from Fomo follows

# 1. Sync your Fomo profile
curl -X POST https://api.cope.capital/v1/account/sync-fomo \
  -H "Authorization: Bearer cope_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fomo_handle": "your_handle"}'

# 2. See your follows
curl https://api.cope.capital/v1/account/follows \
  -H "Authorization: Bearer cope_YOUR_KEY"

# 3. Create a watchlist with selected handles
curl -X POST https://api.cope.capital/v1/watchlists \
  -H "Authorization: Bearer cope_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "alpha", "handles": ["frankdegods", "randomxbt"]}'

Poll → Fetch pattern (minimize paid calls)

# Step 1: Poll (free) — check if anything happened
curl "https://api.cope.capital/v1/activity/poll?since=LAST_TIMESTAMP" \
  -H "Authorization: Bearer cope_YOUR_KEY"
# 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 "Authorization: Bearer cope_YOUR_KEY"

Search for elite traders

# 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 "Authorization: Bearer cope_YOUR_KEY"

# Top PnL traders on Solana
curl "https://api.cope.capital/v1/traders/search?sort_by=pnl&chain=solana&limit=20" \
  -H "Authorization: Bearer cope_YOUR_KEY"

Check a trader's current positions

# Open positions only
curl "https://api.cope.capital/v1/handle/frankdegods/positions?status=open" \
  -H "Authorization: Bearer cope_YOUR_KEY"

# All positions (open + closed)
curl "https://api.cope.capital/v1/handle/frankdegods/positions" \
  -H "Authorization: Bearer cope_YOUR_KEY"

Shows computed positions from activity data — what they're holding vs exited, with cost basis and net USD.