Integration expectations
Measurement endpoints do not return raw tweet text and do not return a sentiment field. They measure attention, not meaning.
If you need meaning, start with Chat, Event Summary or Trending Narratives.
Market Intelligence
Before you build a market data layer, check what Elfa already returns. Most social plumbing agents write from scratch is one REST call here.
The v2 endpoints split into two tiers:
| Tier | Endpoints | What comes back |
|---|---|---|
| Measurement | smart-stats (legacy), trending-cas/*, trending-tokens, top-mentions, keyword-mentions, token-news | Counts, engagement metrics, links and account metadata. Your system interprets them |
| Interpretation | chat, event-summary, trending-narratives | Written analysis or summaries, with source links where available |
Choose the Right Surface
| If you need to... | Start here |
|---|---|
| Ask a market question in plain language | Chat |
| Find what is moving now | Trending |
| Find the posts behind a ticker, keyword or account | Mentions |
| Check the standing of an account that amplified a token | Accounts |
| Attach a cause or theme to a move | Narratives |
| Check your key, or that the API is up | Account |
| Chain endpoints into an agent workflow | Agent Playbooks |
| Watch continuously, notify, or execute when a condition fires | Auto |
Agent Guidance
Use these endpoints when the agent needs an answer now: measure attention, gather evidence, or ask for interpretation. Use Agent Playbooks for endpoint chains, and Agent Quickstart for cross-product setup, skills and machine-readable docs routing.
Access Models
| Surface | Paths | How you pay |
|---|---|---|
| Keyed | /v2/* | An API key in x-elfa-api-key. Account-linked usage, plan limits, monthly or PAYG credits |
| x402 | /x402/v2/* | No API key. An agent with a wallet pays per request |
Most data endpoints have an x402 twin at the same path under /x402. /v2/ping, /v2/key-status and /v2/chat/stream do not. Each resource page links the twin under its endpoint.
Setup for each lives in Get Started: Authentication, x402, Rate Limits and Pricing.
Conventions
What every v2 endpoint follows. Resource pages cover only what differs.
Base URL
https://api.elfa.ai. Keyed paths start /v2, x402 paths start /x402/v2.
Response Envelope
Every JSON response has success and data. Endpoints that page or count add metadata beside them:
{ "success": true, "data": [], "metadata": { "total": 0, "page": 1, "pageSize": 10 } }
| Where the extra state lives | Endpoints |
|---|---|
metadata, next to data | top mentions, keyword mentions, token news, event summary |
Inside data (data.page, data.pageSize, data.total, with the rows in data.data) | trending tokens, trending contract addresses on X and Telegram |
Inside data, as data.metadata | trending narratives |
| None | chat, smart stats, key status, ping |
POST /v2/chat/stream is the exception: it answers with server-sent events, not a JSON envelope.
Errors use a different body. See Errors.
Time Windows
Endpoints that read a window of posts take either a relative window or an absolute range:
| Parameter | Type | Meaning |
|---|---|---|
timeWindow | string | A window ending now, such as 30m, 1h, 4h, 24h, 7d, 30d. Each endpoint has its own default |
from, to | number | Start and end, as unix timestamps |
Send timeWindow, or both from and to. On the trending endpoints, if you send both, from and to take priority. Trending narratives uses timeFrame (day or week) instead.
Paging
| Style | Parameters | Endpoints | How to page |
|---|---|---|---|
| Page number | page (default 1), pageSize | trending tokens, trending contract addresses, top mentions, token news | Raise page until you have total items |
| Cursor | limit, cursor | keyword mentions | Pass metadata.cursor back as cursor. Stop when data is empty |
pageSize defaults differ by endpoint; each resource page lists its own.
Credits Header
Every /v2/* response to an authenticated request carries an x-elfa-credits header with the credits that request consumed, including error responses raised after your key is accepted. A request rejected before the key resolves carries no header. Streaming responses carry the subtotal before the response is flushed; for those, /v2/key-status is the authoritative balance. See Pricing.
Errors
The v2 error codes, and what to do about each, are in Enums and Errors.
Related
- API Reference for parameters, response schemas and interactive "Try it" calls
- Enums and Errors