REST Reference
Every Elfa REST endpoint at a glance. The API surface uses your API key (x-elfa-api-key); the x402 surface exposes the same data as pay-per-request in USDC with no account. Click any endpoint for full parameters, responses, and an interactive "Try it" console.
API
Keyed endpoints under api.elfa.ai/v2. See Getting started for authentication.
| Endpoints | Description |
|---|---|
| Account | |
| Smart stats of accounts | Retrieve smart stats given username GET /v2/account/smart-stats |
| Aggregations | |
| Trending contract addresses on Telegram | Get trending contract addresses mentioned on Telegram. Returns contract addresses with mention counts. GET /v2/aggregations/trending-cas/telegram |
| Trending contract addresses on Twitter | Get trending contract addresses mentioned on Twitter/X. Returns contract addresses with mention counts. GET /v2/aggregations/trending-cas/twitter |
| Trending tokens | Retrieve trending tokens based on highest mentions count, filtered by a minimum mention threshold over a specified time period. GET /v2/aggregations/trending-tokens |
| Data | |
| Event summary from keyword mentions (5 credits total) | Generate event summaries based on keyword mentions within a time period. This endpoint costs 5 credits total GET /v2/data/event-summary |
| Multi keyword mentions search | Search mentions by keywords OR account name within a time period. Either `keywords` or `accountName` (or both) must be provided. GET /v2/data/keyword-mentions |
| Token news mentions | Retrieve token-related news mentions. GET /v2/data/token-news |
| Top mentions | Returns the most significant mentions for a given ticker symbol, ranked by engagement (viewCount → mentionedAt → relevance) within a specified time window. GET /v2/data/top-mentions |
| Trending narratives (5 credits total) | Get trending narratives based on Twitter mentions analysis. This endpoint costs 5 credits total GET /v2/data/trending-narratives |
| Chat | |
| AI chat | Send a message to the Elfa AI and receive a complete response. Suited for agents and integrations that do not support server-sent events (SSE). POST /v2/chat |
| AI chat stream | Stream a response from Elfa AI using Server-Sent Events (SSE). POST /v2/chat/stream |
| System | |
| API key status | Retrieve the current status and usage of your API key GET /v2/key-status |
| Health check endpoint | Simple health check to verify API availability GET /v2/ping |
| Auto | |
| Disconnect Exchange | Disconnect an exchange integration. DELETE /v2/auto/exchanges/{exchange} |
| Delete Query | Delete a terminal query. DELETE /v2/auto/queries/{queryId} |
| Delete Query Draft | Delete a query draft. DELETE /v2/auto/queries/drafts/{draftId} |
| List Exchanges | List connected exchanges. GET /v2/auto/exchanges |
| List Executions | List execution records. GET /v2/auto/executions |
| Get Execution | Get a single execution record. GET /v2/auto/executions/{executionId} |
| List Queries | List Auto queries for the authenticated API-key user. GET /v2/auto/queries |
| Poll Query | Check query status and execution results. GET /v2/auto/queries/{queryId} |
| List LLM Sessions | List LLM output sessions for a query. Only relevant for queries with `actions[0].type: "llm"`. GET /v2/auto/queries/{queryId}/sessions |
| LLM Session Details | Get full LLM analysis output for a specific session. GET /v2/auto/queries/{queryId}/sessions/{sessionId} |
| Stream Notifications | Stream notifications for a single query via Server-Sent Events (SSE). GET /v2/auto/queries/{queryId}/stream |
| List Query Drafts | List editable query drafts. GET /v2/auto/queries/drafts |
| Get Query Draft | Get a specific query draft (legacy; prefer GET /queries/{queryId} which resolves query or draft). GET /v2/auto/queries/drafts/{draftId} |
| Stream All Notifications | Stream notifications for **all** of your queries over a single connection (SSE). GET /v2/auto/queries/stream |
| Validate Symbol | Check whether a symbol is supported on the given exchange. GET /v2/auto/validate-symbol/{exchange}/{symbol} |
| Builder Chat | Ask the AI to help you build an EQL query. POST /v2/auto/chat |
| Connect Exchange | Connect an exchange integration. POST /v2/auto/exchanges |
| Create Query | Create and activate a conditional query. POST /v2/auto/queries |
| Cancel Query | Cancel an active query. POST /v2/auto/queries/{queryId}/cancel |
| Upsert Query Draft | Create or update a query draft. POST /v2/auto/queries/drafts |
| Convert Query Draft | Convert a draft into an active query. POST /v2/auto/queries/drafts/{draftId}/convert |
| Validate Query Draft | Validate a stored query draft without converting it. POST /v2/auto/queries/drafts/{draftId}/validate |
| Validate Query | Validate EQL syntax and get a cost estimate without creating a query. Returns simulation-based cost details when the query is valid. POST /v2/auto/queries/validate |
x402
Keyless pay-per-request endpoints under api.elfa.ai/x402/v2. See x402 Authentication and x402 Rate Limits.
| Endpoints | Description |
|---|---|
| Account | |
| Smart stats of accounts | Retrieve smart account statistics for a username. GET /x402/v2/account/smart-stats |
| Aggregations | |
| Trending contract addresses on Telegram | Retrieve trending contract addresses on Telegram. GET /x402/v2/aggregations/trending-cas/telegram |
| Trending contract addresses on Twitter | Retrieve trending contract addresses on Twitter. GET /x402/v2/aggregations/trending-cas/twitter |
| Trending tokens | Retrieve trending tokens based on mention activity and momentum. GET /x402/v2/aggregations/trending-tokens |
| Data | |
| Event summary from keyword mentions (5 credits total) | Get event summary generated from keyword mention windows. GET /x402/v2/data/event-summary |
| Multi keyword mentions search | Search mentions by keywords or account with cursor pagination. GET /x402/v2/data/keyword-mentions |
| Token news mentions | Get token-related news mention feed. GET /x402/v2/data/token-news |
| Top mentions | Returns the most significant mentions for a given ticker symbol. GET /x402/v2/data/top-mentions |
| Trending narratives (5 credits total) | Analyze narrative trends from recent market discussions. GET /x402/v2/data/trending-narratives |
| Chat | |
| AI chat | Send a message to Elfa AI and receive a complete response. POST /x402/v2/chat |
| Auto | |
| Stream query notifications | Stream query notifications via Server-Sent Events (SSE). Requires `x-elfa-agent-secret` header. GET /x402/v2/auto/queries/{queryId}/stream |
| Auto Builder chat | Ask the AI to help you build an EQL query. It can research live market data, suggest strategies, and return ready-to-use EQL JSON. POST /x402/v2/auto/chat |
| Create conditional query | Create and activate a conditional query that monitors market data and triggers actions when conditions are met. POST /x402/v2/auto/queries |
| Poll query status | Check query status and execution results. Requires `x-elfa-agent-secret` header. POST /x402/v2/auto/queries/{queryId} |
| Cancel query | Cancel an active query. Requires `x-elfa-agent-secret` header. POST /x402/v2/auto/queries/{queryId}/cancel |
| List LLM sessions | List LLM output sessions for a query. Only relevant for queries with `actions[0].type: "llm"`. Requires `x-elfa-agent-secret` header. POST /x402/v2/auto/queries/{queryId}/sessions |
| Get LLM session details | Get full LLM analysis output for a specific session, including conversation messages and any trade signals. Requires `x-elfa-agent-secret` header. POST /x402/v2/auto/queries/{queryId}/sessions/{sessionId} |
| Validate EQL query | Validate EQL syntax and get a cost estimate without creating a query. Returns a simulation-based cost estimate when the query is valid. Requires `x-elfa-agent-secret` hea… POST /x402/v2/auto/queries/validate |