Elfa: market intelligence API for agents — no more Twitter scrapers

Elfa: real-time market intelligence APIs for traders and AI agents.

Most agent stacks reinvent the same three jobs: watch CT, rank what is loud, then explain why. Elfa ships that layer as product and API — built for finance markets, crypto-first, agent-ready.

Site: elfa.ai. App: app.elfa.ai. Docs: docs.elfa.ai. Keys: Developer Portal.

Click to zoom

What you are plugging into

Three surfaces builders actually use:

• Trading app — chat, automate, monitor, explore on app.elfa.ai
• REST + agent infrastructure — Market Intelligence and Auto under https://api.elfa.ai/v2 (docs)
• Widget / Iris — embed or deploy agents on their intelligence stack (product)

Their own framing: real-time data infrastructure for financial AI — social, on-chain, and market sources fused for humans and agents (llms.txt).

Two ways in: API key or x402

Documented in Authentication:

• Keyed — header x-elfa-api-key: <key> on /v2/* (and /v2/auto/*). Some Auto mutations also need HMAC (x-elfa-signature + x-elfa-timestamp).
• Keyless x402 — same data under /x402/v2/*, pay per request in USDC (Base, Arbitrum, Polygon, Avalanche). No account. Ideal for autonomous agents (x402 docs).

Free tier is real: core social endpoints, ~60 RPM, monthly credits. Higher plans unlock mindshare, narratives, AI chat, etc. (Pricing · Rate limits).

Measurement vs interpretation

From Elfa’s Market Intelligence overview— read this before you invent a pipeline:

• Measurement — trending tokens, trending CAs, top-mentions, keyword-mentions, smart-stats, token-news. Counts, engagement, links, account metadata. No raw tweet text. No sentiment field. Your system interprets.
• Interpretation — chat, event-summary, trending-narratives. Written analysis with source links where available.

If you need full tweet bodies, fetch via X (or the SDK’s optional raw path with your own bearer). Elfa is the attention layer, not a full Twitter dump.

Auth check

Always start with key status so you know tier, scopes, and remaining credits:

curl -sS "https://api.elfa.ai/v2/key-status" \
  -H "x-elfa-api-key: $ELFA_API_KEY" \
  -H "Accept: application/json"

Live response shape (fields redacted): active free-tier key, 60 RPM, monthly credit budget, and an explicit scopes list — including aggregations/trending-tokens, data/top-mentions, aggregations/trending-cas/twitter, data/trending-narratives, account/smart-stats, and more.

Live examples (pulled from the API)

These calls were run against production with a free key. Numbers move every minute — treat them as “this is what the JSON looks like,” not a permanent leaderboard.

1. Trending tokens (24h)

curl -sS "https://api.elfa.ai/v2/aggregations/trending-tokens?timeWindow=24h&minMentions=5" \
  -H "x-elfa-api-key: $ELFA_API_KEY"

Each row is roughly { token, current_count, previous_count, change_percent }. A snapshot from one run:

• btc — 725 mentions (24h), −18% vs prior window
• eth — 413, −29%
• hype — 227, +12%
• sol — 179, −4%
• skhy — 201, +116% (attention spike)

Docs: GET /v2/aggregations/trending-tokens. Full endpoint index: REST reference.

2. Trending contract addresses on X (Solana-heavy)

curl -sS "https://api.elfa.ai/v2/aggregations/trending-cas/twitter?timeWindow=24h" \
  -H "x-elfa-api-key: $ELFA_API_KEY"

Returns contractAddress, chain, mentionCount. One snapshot’s top Solana rows included pump.fun-style mints plus native SOL (So1111…1112) mixed with Ethereum addresses — useful as a CA radar for agents that only care about Solana:

const res = await fetch(
  "https://api.elfa.ai/v2/aggregations/trending-cas/twitter?timeWindow=24h",
  { headers: { "x-elfa-api-key": process.env.ELFA_API_KEY } },
);
const json = await res.json();
const sol = (json.data?.data || []).filter((r) => r.chain === "solana");
console.log(sol.slice(0, 5));
// e.g. { contractAddress: "9cRCn9r…pump", chain: "solana", mentionCount: 76 }

3. Top mentions for SOL

curl -sS "https://api.elfa.ai/v2/data/top-mentions?ticker=SOL&timeWindow=24h&limit=5" \
  -H "x-elfa-api-key: $ELFA_API_KEY"

Ranked by engagement. You get tweet id, link, view/like/reply counts, mentionedAt, and a small repostBreakdown (smart vs CT) — still no full text body. Example high-view SOL mention from a run: x.com/…/2082176828181999971 with multi-million views in the metrics payload.

4. Smart stats for an account

curl -sS "https://api.elfa.ai/v2/account/smart-stats?username=toly" \
  -H "x-elfa-api-key: $ELFA_API_KEY"

Live for toly: roughly 2.0M followers, smart follower / following counts, average engagement and reach. Handy when an agent asks “is this account actually followed by people who matter?”

5. Trending narratives (interpretation tier)

curl -sS "https://api.elfa.ai/v2/data/trending-narratives?timeWindow=24h" \
  -H "x-elfa-api-key: $ELFA_API_KEY"

Returns short narrative labels plus source_links / tweet ids. One snapshot included themes like Korean equity stress, AI semiconductor rotation, Robinhood-chain token chatter, and a memecoin frenzy — each with five source posts. That is the “explain the tape” endpoint when you do not want to run your own LLM over a firehose yet.

Note: narratives and event-summary cost more credits (docs list 5 credits each on keyed and x402 tables).

6. Keyword mentions stream

curl -sS "https://api.elfa.ai/v2/data/keyword-mentions?keywords=solana&timeWindow=24h&limit=5" \
  -H "x-elfa-api-key: $ELFA_API_KEY"

One run returned metadata total: 2147 mentions for “solana” in 24h, with a cursor for paging — each hit includes account username, engagement counters, and link.

Minimal JS helper

async function elfa(path, params = {}) {
  const url = new URL(`https://api.elfa.ai/v2/${path}`);
  for (const [k, v] of Object.entries(params)) {
    if (v != null) url.searchParams.set(k, String(v));
  }
  const res = await fetch(url, {
    headers: {
      "x-elfa-api-key": process.env.ELFA_API_KEY,
      Accept: "application/json",
    },
  });
  if (res.status === 401) throw new Error("bad API key");
  if (res.status === 429) throw new Error("rate limited — back off");
  if (!res.ok) throw new Error(`elfa ${res.status}: ${await res.text()}`);
  return res.json();
}

// Agent-style loop: what is loud on Solana right now?
const [tokens, cas] = await Promise.all([
  elfa("aggregations/trending-tokens", { timeWindow: "1h", minMentions: 3 }),
  elfa("aggregations/trending-cas/twitter", { timeWindow: "1h" }),
]);
const solCas = (cas.data?.data || []).filter((x) => x.chain === "solana");
console.log({ tokens: tokens.data?.data?.slice(0, 5), solCas: solCas.slice(0, 5) });

Official examples: Code examples. TypeScript SDK: @elfa-ai/sdk (GitHub).

x402 path for agents without keys

Same routes under https://api.elfa.ai/x402/v2/…. Flow is standard x402: request → HTTP 402 with payment requirements → sign USDC authorization → retry with PAYMENT-SIGNATURE. Docs recommend @x402/fetch + EVM wallet packages. Standard endpoints are about $0.009 / credit; chat is higher (fast vs expert). Details: x402 Payments.

That pairs cleanly with the rest of the Solana agent payments stack — discover → pay → call — without storing a long-lived Elfa secret in the agent.

Agent skills

Elfa publishes installable agent skills for trending tokens, narratives, mentions, and Auto workflows:

npx skills add elfa-ai/skills

Repo: github.com/elfa-ai/skills. Works with Claude Code, Cursor, Codex, and other skills-compatible agents.

When to use what

• “What is loud right now?” → trending-tokens + trending-cas/*
• “Show me the posts driving SOL” → top-mentions?ticker=SOL then open links / X API for text
• “Is this account real CT gravity?” → account/smart-stats
• “What story is forming?” → trending-narratives or event-summary
• “Answer in prose for a user” → POST /v2/chat (plan-gated)
• “Watch forever / trade when…” → Auto (/v2/auto/*) — see Auto docs in the portal nav

Builder path this week

1. Create a key at dev.elfa.ai (or use x402 from a wallet).
2. Hit /v2/key-status, then trending-tokens?timeWindow=1h.
3. Filter trending-cas/twitter to chain === "solana" for a mint watchlist.
4. Wire top-mentions into a dashboard or Telegram alert with links only (respect X ToS if you expand to full text).
5. Optional: install npx skills add elfa-ai/skills and @elfa-ai/sdk.
6. For headless agents, prefer /x402/v2 so you are not shipping API keys in prompts.

Resources

• elfa.ai
• App
• Docs
• Authentication
• REST endpoint index
• Market Intelligence overview
• Code examples
• x402 payments
• Pricing
• @elfa-ai/sdk
• Agent skills
• llms.txt
• @elfa_ai

Bottom line

Elfa is the “attention API” many Solana agents half-build with brittle scrapers. Call keyed /v2 for product integrations, or /x402/v2 when the agent should pay its own way. Start with trending tokens and Solana CAs, add top-mentions for links, then narratives or chat when you need prose. Docs and the SDK are the source of truth — wire them once, stop maintaining a hobby CT indexer.