{ "version": 1, "generatedAt": "2026-10-13T16:10:13.323Z", "source": { "openapi": "/swagger/swagger.json", "docsDirectory": "/api/rest" }, "endpointCount": 65, "endpoints": [ { "operationId": "auto-delete-query-v2", "method": "DELETE", "path": "/v2/auto/queries/{queryId}", "docsUrl": "/api/rest/auto-delete-query-v-2", "summary": "Delete Query", "description": "Delete a terminal query.\n\nOnly queries in a terminal status (`triggered`, `expired`, `cancelled`,\n`failed`) can be deleted. Active queries must be cancelled first.\nDo not use this endpoint to cancel running queries; use\n`POST /v2/auto/queries/{queryId}/cancel` for active queries.\n\n### Cost\n\nFree.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\n### Request Example\n\nPath parameter:\n- `queryId` (string)\n\n### Response Example (200)\n\n```json\n{\n \"id\": \"a12d20ff-6cb2-433e-afed-cc2e6a0380b6\",\n \"deletedAt\": \"2026-04-01T12:00:00.000Z\"\n}\n```", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "free", "notes": "Free." }, "requestExample": null, "responseExamples": { "200": { "key": {} } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 404, 409 ], "idempotencyKey": null }, { "operationId": "auto-delete-query-draft-v2", "method": "DELETE", "path": "/v2/auto/queries/drafts/{draftId}", "docsUrl": "/api/rest/auto-delete-query-draft-v-2", "summary": "Delete Query Draft", "description": "Delete a query draft.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "key": {} } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 404 ], "idempotencyKey": null }, { "operationId": "getAccountSmartStats-v2", "method": "GET", "path": "/v2/account/smart-stats", "docsUrl": "/api/rest/get-account-smart-stats-v-2", "summary": "Smart stats of accounts (legacy, removed 28 Oct 2026)", "description": "Retrieve smart stats given username", "tags": [ "v2 Account" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "averageReach": 1, "averageEngagement": 1, "smartFollowingCount": 1 } } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 404 ], "idempotencyKey": null }, { "operationId": "getTrendingCAsTelegram-v2", "method": "GET", "path": "/v2/aggregations/trending-cas/telegram", "docsUrl": "/api/rest/get-trending-c-as-telegram-v-2", "summary": "Trending contract addresses on Telegram", "description": "Get trending contract addresses mentioned on Telegram. Returns contract addresses with mention counts.\n\nNote: You must provide EITHER timeWindow OR both from and to parameters.\nIf both timeWindow and from/to are provided, from/to takes priority.", "tags": [ "v2 Aggregations" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "pageSize": 1, "page": 1, "total": 1, "data": [ { "contractAddress": "string", "chain": "ethereum", "mentionCount": 1 } ] } } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "getTrendingCAsTwitter-v2", "method": "GET", "path": "/v2/aggregations/trending-cas/twitter", "docsUrl": "/api/rest/get-trending-c-as-twitter-v-2", "summary": "Trending contract addresses on Twitter", "description": "Get trending contract addresses mentioned on Twitter/X. Returns contract addresses with mention counts.\n\nNote: You must provide EITHER timeWindow OR both from and to parameters.\nIf both timeWindow and from/to are provided, from/to takes priority.", "tags": [ "v2 Aggregations" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "pageSize": 1, "page": 1, "total": 1, "data": [ { "contractAddress": "string", "chain": "ethereum", "mentionCount": 1 } ] } } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "getTrendingTokens-v2", "method": "GET", "path": "/v2/aggregations/trending-tokens", "docsUrl": "/api/rest/get-trending-tokens-v-2", "summary": "Trending tokens", "description": "This experimental endpoint is under active development and its behavior may change without notice.\nUse with caution in production environments.\n\nRetrieve trending tokens based on highest mentions count,\nfiltered by a minimum mention threshold over a specified time period.\n\nNote: You must provide EITHER timeWindow OR both from and to parameters.\nIf both timeWindow and from/to are provided, from/to takes priority.", "tags": [ "v2 Aggregations" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "pageSize": 1, "page": 1, "total": 1, "data": [ { "change_percent": 1, "previous_count": 1, "current_count": 1, "token": "string" } ] } } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "auto-list-executions-v2", "method": "GET", "path": "/v2/auto/executions", "docsUrl": "/api/rest/auto-list-executions-v-2", "summary": "List Executions", "description": "List execution records.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "data": [ { "triggerTime": "string", "conditionsMet": 1, "trigger": { "type": "string", "time": "string", "matchedConditions": [ { "condition": null } ] } } ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "auto-get-execution-v2", "method": "GET", "path": "/v2/auto/executions/{executionId}", "docsUrl": "/api/rest/auto-get-execution-v-2", "summary": "Get Execution", "description": "Get a single execution record.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "triggerTime": "string", "conditionsMet": 1, "trigger": { "type": "string", "time": "string", "matchedConditions": [ { "condition": { "source": "string" } } ] } } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 404 ], "idempotencyKey": null }, { "operationId": "auto-list-queries-v2", "method": "GET", "path": "/v2/auto/queries", "docsUrl": "/api/rest/auto-list-queries-v-2", "summary": "List Queries", "description": "List Auto queries for the authenticated API-key user.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "key": {} } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "auto-poll-query-v2", "method": "GET", "path": "/v2/auto/queries/{queryId}", "docsUrl": "/api/rest/auto-poll-query-v-2", "summary": "Poll Query", "description": "Check query status and execution results.\n\n### Cost\n\nFree.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\n### Request Example\n\nPath parameter:\n- `queryId` (string)\n\n### Response Example (200)\n\n```json\n{\n \"queryId\": \"76e2e824-fc47-4d60-99b1-c227fbd2d3f5\",\n \"status\": \"active\",\n \"credits\": 0,\n \"latestEvaluation\": {\n \"evaluatedAt\": \"2026-04-01T12:00:00.000Z\",\n \"conditionStates\": [\n {\n \"index\": 0,\n \"source\": \"price\",\n \"method\": \"current\",\n \"args\": { \"symbol\": \"BTC\" },\n \"currentValue\": 97250.5,\n \"targetValue\": 100000,\n \"operator\": \"<\",\n \"isMet\": true,\n \"lastUpdated\": \"2026-04-01T12:00:00.000Z\"\n }\n ],\n \"wouldTriggerNow\": true,\n \"matchingConditions\": 1,\n \"totalConditions\": 1\n },\n \"executions\": [\n {\n \"id\": \"a12d20ff-6cb2-433e-afed-cc2e6a0380b6\",\n \"queryId\": \"76e2e824-fc47-4d60-99b1-c227fbd2d3f5\",\n \"type\": \"notification\",\n \"status\": \"success\",\n \"details\": { \"notification\": { \"channel\": \"webhook\" } },\n \"triggerTime\": \"2026-04-01T12:00:00.000Z\",\n \"conditionsMet\": 1,\n \"trigger\": {\n \"type\": \"price\",\n \"time\": \"2026-04-01T12:00:00.000Z\",\n \"matchedConditions\": [\n {\n \"condition\": {\n \"source\": \"price\",\n \"method\": \"current\",\n \"args\": { \"symbol\": \"BTC\" },\n \"operator\": \"<\",\n \"value\": 100000\n },\n \"match\": { \"observedValue\": 97250.5 }\n }\n ]\n },\n \"createdAt\": \"2026-04-01T12:00:01.000Z\"\n }\n ]\n}\n```\n\n`latestEvaluation` is the latest current-state snapshot. Auto Trigger\nContext (`triggerTime`, `conditionsMet`, `trigger`) explains what fired for\nan execution and uses the same public redaction boundary as outbound\ndelivery payloads.\n\n> Best practice: use polling for debugging or backfills. For production\n> delivery, prefer webhook/SSE notifications.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "free", "notes": "Free." }, "requestExample": null, "responseExamples": { "200": { "queryId": "string", "status": "string", "latestEvaluation": { "evaluatedAt": "string", "conditionStates": [ { "index": 1, "source": "string", "method": "string" } ], "wouldTriggerNow": true, "matchingConditions": 1, "totalConditions": 1 }, "executions": [ { "id": "string", "queryId": "string", "type": "string", "status": "string", "createdAt": "string" } ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 404 ], "idempotencyKey": null }, { "operationId": "auto-list-sessions-v2", "method": "GET", "path": "/v2/auto/queries/{queryId}/sessions", "docsUrl": "/api/rest/auto-list-sessions-v-2", "summary": "List LLM Sessions", "description": "List LLM output sessions for a query.\nOnly relevant for queries with `actions[0].type: \"llm\"`.\n\n### Cost\n\nFree.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\n### Request Example\n\nPath parameter:\n- `queryId` (string)\n\n### Response Example (200)\n\n```json\n{\n \"queryId\": \"a12d20ff-6cb2-433e-afed-cc2e6a0380b6\",\n \"sessions\": [\n {\n \"sessionId\": \"s_1\",\n \"status\": \"completed\",\n \"executedAt\": \"2026-04-01T12:00:00.000Z\"\n }\n ]\n}\n```\n\n> Best practice: store `sessionId` values from executions so you can fetch\n> full analysis records only when needed.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "free", "notes": "Free." }, "requestExample": null, "responseExamples": { "200": { "sessions": [ { "sessionId": "string", "status": "string", "executedAt": "string" } ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 404 ], "idempotencyKey": null }, { "operationId": "auto-get-session-v2", "method": "GET", "path": "/v2/auto/queries/{queryId}/sessions/{sessionId}", "docsUrl": "/api/rest/auto-get-session-v-2", "summary": "LLM Session Details", "description": "Get full LLM analysis output for a specific session.\n\n### Cost\n\nFree.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\n### Request Example\n\nPath parameters:\n- `queryId` (string)\n- `sessionId` (string)\n\n### Response Example (200)\n\n```json\n{\n \"sessionId\": \"s_1\",\n \"queryId\": \"a12d20ff-6cb2-433e-afed-cc2e6a0380b6\",\n \"title\": \"Token analysis\",\n \"analysisType\": \"tokenAnalysis\",\n \"createdAt\": \"2026-04-01T12:00:00.000Z\",\n \"messages\": [\n {\n \"query\": \"Analyze BTC\",\n \"response\": \"...\",\n \"status\": \"completed\",\n \"analysisType\": \"tokenAnalysis\",\n \"timestamp\": \"2026-04-01T12:00:00.000Z\"\n }\n ]\n}\n```\n\n> Best practice: treat top-level and message-level fields as nullable and\n> handle partial records defensively in your parser.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "free", "notes": "Free." }, "requestExample": null, "responseExamples": { "200": { "key": {} } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 404 ], "idempotencyKey": null }, { "operationId": "auto-stream-query-v2", "method": "GET", "path": "/v2/auto/queries/{queryId}/stream", "docsUrl": "/api/rest/auto-stream-query-v-2", "summary": "Stream Notifications", "description": "Stream notifications for a single query via Server-Sent Events (SSE).\n\nTo follow every query you own over one connection instead, use\n`/queries/stream` — see *Stream Notifications For All Queries*.\n\n### Cost\n\nFree.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\n### Request Example\n\nPath parameter:\n- `queryId` (string)\n\n### Response Format (SSE)\n\n```\nid: \nevent: notification\ndata: {\"status\":\"triggered\",\"title\":\"...\",\"body\":\"...\",\"queryId\":\"\",\"timestamp\":1743379200000}\n```\n\n`status` is one of `triggered`, `stopped`, `ended`, or `update`. The payload also\ncarries the query's execution context when present (`executionId`, `triggerTime`,\n`conditionsMet`, `autoDetails`). `id` is the notification outbox event UUID.\n\nA `: keep-alive` comment is sent every 15s. Events are live-only — there is no\nreplay, and `Last-Event-ID` is ignored.\n\n### Lifecycle\n\nThe request returns `410` when the query is already terminal and its notifications\nhave drained. Once the query reaches a terminal state (`triggered`, `failed`,\n`expired`, `cancelled`) and its notifications have been delivered, the stream emits\nand then closes:\n\n```\nevent: end\ndata: {\"code\":\"QUERY_STREAM_CLOSED\",\"status\":\"\",\"queryId\":\"\"}\n```\n\nA `recurring` query is not terminal — its stream stays open across triggers.\n\n> Best practice: deduplicate SSE events by event id and process with a\n> queue-backed worker for reliable agent execution.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "free", "notes": "Free." }, "requestExample": null, "responseExamples": null, "successStatuses": [ 200, 204 ], "errorStatuses": [ 401, 404, 410 ], "idempotencyKey": null }, { "operationId": "auto-list-query-drafts-v2", "method": "GET", "path": "/v2/auto/queries/drafts", "docsUrl": "/api/rest/auto-list-query-drafts-v-2", "summary": "List Query Drafts", "description": "List editable query drafts.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "key": {} } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "auto-get-query-draft-v2", "method": "GET", "path": "/v2/auto/queries/drafts/{draftId}", "docsUrl": "/api/rest/auto-get-query-draft-v-2", "summary": "Get Query Draft", "description": "Get a specific query draft (legacy; prefer GET /queries/{queryId} which resolves query or draft).", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "key": {} } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 404 ], "idempotencyKey": null }, { "operationId": "auto-stream-queries-v2", "method": "GET", "path": "/v2/auto/queries/stream", "docsUrl": "/api/rest/auto-stream-queries-v-2", "summary": "Stream All Notifications", "description": "Stream notifications for **all** of your queries over a single connection (SSE).\n\nUse this instead of opening one `/queries/{queryId}/stream` per query. Events for\nevery query you own arrive on one connection; correlate them with `data.queryId`.\n\n### Cost\n\nFree.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\n### Response Format (SSE)\n\n```\nid: \nevent: notification\ndata: {\"status\":\"triggered\",\"title\":\"...\",\"body\":\"...\",\"queryId\":\"\",\"timestamp\":1743379200000}\n```\n\nA `: keep-alive` comment is sent every 15s. Only notifications tied to a query are\ndelivered. Events are live-only — there is no replay, and `Last-Event-ID` is ignored.\n\n### Lifecycle\n\nOpen the stream *after* creating at least one query: the request returns `410` when\nyou have no active queries. Once your last query reaches a terminal state and all\nof its notifications have been delivered, the stream emits and then closes:\n\n```\nevent: end\ndata: {\"code\":\"USER_STREAM_CLOSED\"}\n```", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "free", "notes": "Free." }, "requestExample": null, "responseExamples": null, "successStatuses": [ 200, 204 ], "errorStatuses": [ 401, 410 ], "idempotencyKey": null }, { "operationId": "auto-validate-symbol-v2", "method": "GET", "path": "/v2/auto/validate-symbol/{exchange}/{symbol}", "docsUrl": "/api/rest/auto-validate-symbol-v-2", "summary": "Validate Symbol", "description": "Check whether a symbol is supported on the given exchange.\n\nUse this before submitting an EQL query based on symbols like `price` / `ta`\ntriggers. Symbols not supported return `\"false\"`.\n\n### Cost\n\nFree.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\n### Response Example (200)\n\n```json\n{\n \"supported\": \"true\"\n}\n```", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "free", "notes": "Free." }, "requestExample": null, "responseExamples": { "200": { "supported": "true" } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403 ], "idempotencyKey": null }, { "operationId": "getEventSummary-v2", "method": "GET", "path": "/v2/data/event-summary", "docsUrl": "/api/rest/get-event-summary-v-2", "summary": "Event summary from keyword mentions (5 credits total)", "description": "Generate event summaries based on keyword mentions within a time period.\nThis endpoint costs 5 credits total", "tags": [ "v2 Data" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": [ { "tweetIds": [ "string" ], "sourceLinks": [ "string" ], "summary": "string" } ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 503 ], "idempotencyKey": null }, { "operationId": "getKeywordMentions-v2", "method": "GET", "path": "/v2/data/keyword-mentions", "docsUrl": "/api/rest/get-keyword-mentions-v-2", "summary": "Multi keyword mentions search", "description": "Search mentions by keywords OR account name within a time period. Either\n`keywords` or `accountName` (or both) must be provided.\n\n**Response shape.** The response envelope is `{ success, data, metadata }`.\n`data` is a flat array of mentions; pagination state lives in `metadata`.\n\n**Cursor pagination.** Unlike `/v2/data/top-mentions` (which uses\n`page`/`pageSize`), this endpoint is cursor-paginated.\n`metadata.cursor` is a millisecond timestamp (number). To fetch the next\npage, pass its value back as the `cursor` query param. Page until `data`\nis empty; `metadata.cursor` is only omitted on that empty page.\n`metadata.total` is the complete matching result set, not the remainder\nafter the cursor, and may be capped at 10000 for performance.\n\n**No tweet content.** V2 does not return raw tweet text. Use the `link`\nfield to fetch the original tweet via the Twitter/X API if needed, or use\nthe SDK's `fetchRawTweets: true` option with a Twitter bearer token.\n\n**Account info.** Each mention includes a minimal `account` object with\nonly `username` and `isVerified`. No id, display name, follower count, or\nbio is returned.\n\n**Field notes.** `mentionedAt` is an ISO 8601 string (not a unix\ntimestamp). `repostBreakdown.smart` counts reposts by smart accounts;\n`repostBreakdown.ct` counts reposts by crypto-Twitter accounts.", "tags": [ "v2 Data" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": [ { "tweetId": "2045519677062066348", "link": "https://x.com/BillyM2k/status/2045519677062066348", "likeCount": 0, "repostCount": 0, "viewCount": 0, "quoteCount": 0, "replyCount": 0, "bookmarkCount": 0, "mentionedAt": "2026-04-18T15:07:49+00:00", "type": "post", "account": { "username": "BillyM2k", "isVerified": false }, "repostBreakdown": { "smart": 0, "ct": 0 } } ], "metadata": { "total": 1, "cursor": 1776524869000 } } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "getTokenNews-v2", "method": "GET", "path": "/v2/data/token-news", "docsUrl": "/api/rest/get-token-news-v-2", "summary": "Token news mentions (tweet source only)", "description": "Retrieve token-related news mentions.\n\nResults are X (Twitter) posts from accounts tagged as news sources, not\narticles published by news outlets.", "tags": [ "v2 Data" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": [ { "tweetId": "string", "link": "string", "likeCount": 1, "repostCount": 1, "viewCount": 1, "quoteCount": 1, "replyCount": 1, "bookmarkCount": 1, "mentionedAt": "string", "type": "repost", "repostBreakdown": { "ct": 1, "smart": 1 } } ], "metadata": { "pageSize": 1, "page": 1, "total": 1 } } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "getTopMentions-v2", "method": "GET", "path": "/v2/data/top-mentions", "docsUrl": "/api/rest/get-top-mentions-v-2", "summary": "Top mentions", "description": "Returns the most significant mentions for a given ticker symbol, ranked by\nengagement (viewCount → mentionedAt → relevance) within a specified time\nwindow.\n\n**Response shape.** The response envelope is `{ success, data, metadata }`.\n`data` is a flat array of mentions; pagination state lives in `metadata`\n(`total`, `page`, `pageSize`) — never merged into the top level.\n\n**No tweet content.** V2 does not return raw tweet text. Use the `link`\nfield to fetch the original tweet via the Twitter/X API if needed, or use\nthe SDK's `fetchRawTweets: true` option with a Twitter bearer token.\n\n**No account object.** Unlike `/v2/data/keyword-mentions`, this endpoint\ndoes not return an `account` object per mention.\n\n**Field notes.** `mentionedAt` is an ISO 8601 string (not a unix\ntimestamp). `repostBreakdown.smart` counts reposts by smart accounts;\n`repostBreakdown.ct` counts reposts by crypto-Twitter accounts.", "tags": [ "v2 Data" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": [ { "tweetId": "2045186844212756697", "link": "https://x.com/BillyM2k/status/2045186844212756697", "likeCount": 465, "repostCount": 45, "viewCount": 15914, "quoteCount": 10, "replyCount": 62, "bookmarkCount": 12, "mentionedAt": "2026-04-17T17:05:16+00:00", "type": "post", "repostBreakdown": { "smart": 0, "ct": 0 } } ], "metadata": { "total": 52, "page": 1, "pageSize": 2 } } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "getTrendingNarratives-v2", "method": "GET", "path": "/v2/data/trending-narratives", "docsUrl": "/api/rest/get-trending-narratives-v-2", "summary": "Trending narratives (5 credits total)", "description": "Get trending narratives based on Twitter mentions analysis.\nThis endpoint costs 5 credits total", "tags": [ "v2 Data" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "metadata": { "error": "string", "total_tweets": 1, "total_narratives": 1 }, "trending_narratives": [ { "tweet_ids": [ "string" ], "source_links": [ "string" ], "narrative": "string" } ] } } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "getApiKeyStatus-v2", "method": "GET", "path": "/v2/key-status", "docsUrl": "/api/rest/get-api-key-status-v-2", "summary": "API key status", "description": "Retrieve the current status and usage of your API key", "tags": [ "v2 System" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "id": 1, "key": "string", "name": "string", "status": "active", "dailyRequestLimit": 1, "monthlyRequestLimit": 1, "expiresAt": "string", "createdAt": "string", "updatedAt": "string", "requestsPerMinute": 1, "email": "string", "project": "string", "allowOverage": true, "maxOverage": 1, "spendCapCredits": 1, "bonusCredits": 1, "bonusCreditsExpiresAt": "string", "userId": 1, "emailNotificationsEnabled": true, "lastEmailSentAt": "string", "lastUsagePercentNotified": 1, "spendAlertThreshold": "string", "spendAlertMaxFrequencyHours": 1, "totalSpendAlerted": "string", "athenaEnabled": true, "scopes": [ "string" ], "tier": "string", "depositCredits": 1, "billingMode": "deposit", "usage": { "monthly": 1, "daily": 1 }, "limits": { "monthly": 1, "daily": 1 }, "isExpired": true, "remainingRequests": { "monthly": 1, "daily": 1 } } } }, "successStatuses": [ 200 ], "errorStatuses": [ 401 ], "idempotencyKey": null }, { "operationId": "ping-v2", "method": "GET", "path": "/v2/ping", "docsUrl": "/api/rest/ping-v-2", "summary": "Health check endpoint", "description": "Simple health check to verify API availability", "tags": [ "v2 System" ], "beta": false, "mode": "api_key", "auth": { "headers": [], "securitySchemes": [], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "message": "string" } } }, "successStatuses": [ 200 ], "errorStatuses": [], "idempotencyKey": null }, { "operationId": "calls-list-v3", "method": "GET", "path": "/v3/calls", "docsUrl": "/api/rest/calls-list-v-3", "summary": "Calls", "description": "Every call: one post that opened, added to, trimmed, reaffirmed, reversed, closed or\nstopped out of a position, with its setup and thesis. Telegram calls show, but only\nan X handle can be filtered on until channels are mapped.\n\nCost: `1` credit.", "tags": [ "v3 Calls" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "calls": [ { "handle": "string", "source": {}, "channel": "string", "id": "string", "episodeId": "string", "asset": { "id": "string", "symbol": "string", "name": "string", "entityType": null }, "callAction": "open", "setup": {}, "thesis": {}, "sourceRecordId": "string", "occurredAt": 1 } ], "nextCursor": "string", "hasMore": true, "servedFrom": 1 } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429 ], "idempotencyKey": null }, { "operationId": "call-episodes-list-v3", "method": "GET", "path": "/v3/calls/episodes", "docsUrl": "/api/rest/call-episodes-list-v-3", "summary": "Call episodes", "description": "One account's position on one asset, from the call that opened it to whatever closed\nit, with its calls by id. An episode is served when it was open at any point\nbetween `from` and `to`, not only when it opened in that range.\n\n`calls` lists only the calls inside the plan's history (the ones `/calls` serves when\nno `from` is given), so a position opened before it can come back with fewer calls,\nor none. Its position\nfacts (`openedAt`, `entryPrice`, `direction`, `status`, and how it closed) are kept.\n\nEach episode also carries the opening call's `setup`, `thesis` and stated target and\nstop, all null when that call is older than the plan's history, and `track`: the\nauthor's record over every position they have opened (alpha score, hit rate, average\nreturn), in every market and not cut to the plan's history.\n\nCost: `1` credit.", "tags": [ "v3 Calls" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "episodes": [ { "handle": "string", "source": {}, "channel": "string", "id": "string", "asset": { "id": "string", "symbol": "string", "name": "string", "entityType": null }, "direction": "long", "horizon": "scalp", "status": "open", "openedAt": 1, "closedAt": 1, "observedAt": 1, "entryPrice": 1, "exitPrice": 1, "closeReason": {}, "setup": {}, "thesis": {}, "statedTarget": 1, "statedStop": 1, "track": { "alphaScore": 1, "hitRate": 1, "avgReturn": 1, "scoredEpisodes": 1, "totalEpisodes": 1 }, "calls": [ { "callId": "string", "callAction": null, "occurredAt": 1 } ] } ], "nextCursor": "string", "hasMore": true, "servedFrom": 1 } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429 ], "idempotencyKey": null }, { "operationId": "positioning-v3", "method": "GET", "path": "/v3/calls/positioning", "docsUrl": "/api/rest/positioning-v-3", "summary": "Positioning", "description": "How the open episodes on one asset are split, right now. A count of the accounts long\nand short, not a share, because a caller reading two assets wants the size of each.\n`asOf` is when the last of those episodes last moved, or when it was read if none is\nopen.\n\nCost: `1` credit.", "tags": [ "v3 Calls" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "id": "string", "symbol": "string", "name": "string", "openLong": 1, "openShort": 1, "asOf": 1 } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429 ], "idempotencyKey": null }, { "operationId": "entities-list-v3", "method": "GET", "path": "/v3/entities", "docsUrl": "/api/rest/entities-list-v-3", "summary": "Entities", "description": "Turns what a caller holds into the id every other v3 endpoint takes. Asset results\nare collapsed to one row per family; people, projects and organisations remain\nindividual entities. A ticker, name, X handle, contract address, CoinGecko id, FIGI\nor CIK resolves; a string naming two things returns both, scored.\n\n**Exact matches only.** `solana` and `sol` resolve Solana; `sola` resolves the token\nwhose ticker is SOLA, not a prefix of Solana; `vitalik` returns nothing where\n`vitalik buterin` or `@VitalikButerin` returns the person. A listed company also\nanswers to its name without the legal form and share class, so `tesla` resolves Tesla,\nInc. as a `name` and `coinbase` resolves Coinbase Global, Inc. as an `alias`. What the\nstring hit comes back as `matchedOn`, and `score` ranks an exact id (a contract\naddress, FIGI, CIK or `@handle`) above a symbol above a loose alias. A CoinGecko id or\na handle without its `@` scores as a symbol, since `doge` or `ai` is often another\ncoin's ticker. Ties break on how prominent the thing is, which is what puts the real\nUSDT above the other ninety-five. A contract address that several tokens share across\nchains puts the one on its home chain first and scores the rest 0.95. The home chain\nis Solana for a base58 address, and Ethereum, then Base, Arbitrum, BNB Chain, Optimism,\nPolygon and Avalanche for a 0x one.\n\nA person or a company is only here if the registry already holds it, and a handle\nresolves to the entity behind the account rather than to the account, because handles\nchange and the id does not.\n\nCost: `1` credit.", "tags": [ "v3 Entities" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "entities": [ { "id": "string", "entityType": "token", "name": "string", "symbol": "string", "handle": "string", "matchedOn": "symbol", "score": 1, "externalIds": { "coingeckoId": "string", "figi": "string", "cik": "string" } } ], "nextCursor": "string", "hasMore": true } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429 ], "idempotencyKey": null }, { "operationId": "events-list-v3", "method": "GET", "path": "/v3/events", "docsUrl": "/api/rest/events-list-v-3", "summary": "Events", "description": "What happened, to what, and when. Newest first, with a cursor. Filter with\n`entityIds`: a family UUID for an asset, or an entity UUID for a person, project or\norganisation. Or fetch events you already hold with `eventIds`.\n\n`from` is required unless `eventIds` is sent, and `to` defaults to now. A range that\nstarts before the plan's history is cut, and `servedFrom` says where it started.\n\n`sort=relevant` ranks the last 24 hours by how newsworthy each event is, the order the\napp's feed shows, instead of newest first. It takes no range: `from`, `to`,\n`eventIds`, `eventClass`, `eventType`, `implication`, `novelty`, `arcId` and\n`order=asc` are refused with it, and `entityIds` must be assets. Every page is ranked\nas of the first, and `servedFrom` is null.\n\n`q` searches by topic instead: events ranked by how closely they match it, best first.\nWrite a theme or a phrase (\"stablecoin regulation in the US\", \"solana outage\"); for\neverything about one asset or company, resolve it with `/v3/entities` and pass\n`entityIds`, since a bare ticker is a poor topic. `q` takes `from` (optional, default\nthe plan's history), `to`, `entityIds`, `alertAction`, `eventType` and\n`hasStoryline`; anything else is refused with it. A search serves its first 100\nmatches that clear a minimum relevance, so a query nothing matches well returns an\nempty page, and a page can be shorter than `limit` while more follow.\n\nCost: `1` credit. Requires `x-elfa-api-key`.", "tags": [ "v3 Events" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "events": [ { "id": "string", "eventClass": "market", "alertTitle": "string", "summary": "string", "implication": {}, "eventType": {}, "primaryEntities": [ { "id": "string", "symbol": "string", "name": "string", "entityType": null } ], "relatedEntities": [ {} ], "alertAction": {}, "originCount": 1, "impacts": [ { "entityId": "string", "symbol": "string", "priceChange1d": 1, "movedFirst": true, "marketWide": true, "final": true } ], "analyzedAt": 1, "novelty": "new", "firstSeenAt": 1, "storylineId": "string", "citedSources": [ { "source": "string", "sourceRecordId": "string", "handle": "string", "link": "string" } ], "positions": { "long": 1, "short": 1, "side": "long" } } ], "nextCursor": "string", "hasMore": true, "servedFrom": 1 } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429, 503 ], "idempotencyKey": null }, { "operationId": "arcs-list-v3", "method": "GET", "path": "/v3/events/arcs", "docsUrl": "/api/rest/arcs-list-v-3", "summary": "Arcs", "description": "Storylines belonging to the same larger movement, with a summary and every storyline\nby id. Reconciled hourly, and most storylines never join one.\n\nBy default, arcs by when they last changed. `assetClass`, `entityIds` or `sort` read\nthe app's narrative list instead: active arcs in a market or about an asset, newest\nevent first, or by how many storylines or events they hold. That list holds active\narcs only, newest first, so it cannot be combined with `arcIds`, `status=retired` or\n`order=asc`, and it starts at the plan's history on the newest event.\n\n`q` searches arcs by topic, best match first, within `status`. It serves the first 100\nmatches that clear a minimum relevance; `arcIds`, `assetClass`, `entityIds`, `sort`\nand `order=asc` are refused with it.\n\nCost: `1` credit.", "tags": [ "v3 Events" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "arcs": [ { "id": "string", "name": "string", "summary": "string", "status": "active", "storylineIds": [ "string" ], "updatedAt": 1 } ], "nextCursor": "string", "hasMore": true } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429, 503 ], "idempotencyKey": null }, { "operationId": "storylines-list-v3", "method": "GET", "path": "/v3/events/storylines", "docsUrl": "/api/rest/storylines-list-v-3", "summary": "Storylines", "description": "What is developing over time. A storyline is many events, carries its summary and\nevery event it shows by id, and goes dormant after three quiet days.\n\n`q` searches storylines by topic, best match first, across every status unless\n`status` is sent; a more recently started storyline edges ahead of an older match of\nsimilar relevance. Its `from` and `to` bound when the title and summary were last\nrewritten (at or after `lastMaterialAt`), rather than `lastEventAt`. It takes `from`\n(optional, default the plan's history), `to`, `entityIds` and `status`, and serves the\nfirst 100 matches that clear a minimum relevance, none when nothing does;\n`storylineIds`, `relation` and `order=asc` are refused with it.\n\nCost: `1` credit.", "tags": [ "v3 Events" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "storylines": [ { "id": "string", "title": "string", "summary": "string", "status": "open", "entities": [ { "id": "string", "symbol": "string", "name": "string", "entityType": null } ], "startedAt": 1, "lastEventAt": 1, "lastMaterialAt": 1, "arcId": "string", "events": [ { "eventId": "string", "relation": null, "material": true, "occurredAt": 1 } ] } ], "nextCursor": "string", "hasMore": true, "servedFrom": 1 } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429, 503 ], "idempotencyKey": null }, { "operationId": "key-status-v3", "method": "GET", "path": "/v3/key-status", "docsUrl": "/api/rest/key-status-v-3", "summary": "Key status", "description": "What this key can do: its plan, scopes, credits, and how far back its plan reaches.\n\nFree.", "tags": [ "v3 System" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "plan": "payg", "billingMode": "deposit", "owner": "user", "scopes": [ "string" ], "credits": { "requestsPerMinute": 1, "resetsAt": 1, "remaining": 1, "used": 1, "limit": 1 }, "historyFrom": 1 } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 429 ], "idempotencyKey": null }, { "operationId": "call-book-crypto-v3", "method": "GET", "path": "/v3/market/crypto/call-book", "docsUrl": "/api/rest/call-book-crypto-v-3", "summary": "Crypto call book", "description": "How the accounts we follow are positioned in crypto, hour by hour. `longShare` is how\nmany of the counted accounts are long, `crowdingPercentile` where that lean sits\nagainst this book's own last 28 days, and the two pulse pairs how unusual the last\nday and the last six hours are.\n\nHistory is sealed hours. On a newest-first first page the top row is a live tick, at\nmost five minutes old, and it is the only unsealed row.\n\nCost: `1` credit.", "tags": [ "v3 Market" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "bars": [ { "barAt": 1, "live": true, "longShare": 1, "shortShare": 1, "crowdingPercentile": 1, "accountCount": 1, "pulse24": 1, "pulse24LongShare": 1, "pulse6": 1, "pulse6LongShare": 1, "formulaVersion": "string", "computedAt": 1 } ], "nextCursor": "string", "hasMore": true, "servedFrom": 1 } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429 ], "idempotencyKey": null }, { "operationId": "mindshare-crypto-v3", "method": "GET", "path": "/v3/market/crypto/mindshare", "docsUrl": "/api/rest/mindshare-crypto-v-3", "summary": "Crypto mindshare", "description": "Crypto assets ranked by share of attention over a period, weighted by who posted.\n`hot` marks a name whose last hour is running ahead of its last four, picked from the\ntop 25; it is null on the one-hour period.\n\nCost: `1` credit.", "tags": [ "v3 Market" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "assets": [ { "rank": 1, "id": "string", "symbol": "string", "name": "string", "share": 1, "changePct": 1, "hot": true, "share1h": 1, "share4h": 1, "ratio1h4h": 1, "capped1h": 1 } ], "nextCursor": "string", "hasMore": true } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429 ], "idempotencyKey": null }, { "operationId": "trending-contracts-v3", "method": "GET", "path": "/v3/market/crypto/trending-contracts", "docsUrl": "/api/rest/trending-contracts-v-3", "summary": "Trending contracts", "description": "Contract addresses being pasted on X and Telegram, counted together, named where\nthe registry knows the address. An address several tokens share across chains is\nnamed for the one on its home chain, the same order `entities` ranks by, and left\nunnamed when the home chains do not pick out exactly one.\n\nCost: `1` credit.", "tags": [ "v3 Market" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "contracts": [ { "rank": 1, "contractAddress": "string", "mentionCount": 1, "asset": { "symbol": "string", "name": "string", "id": "string", "chains": [ null ] } } ], "nextCursor": "string", "hasMore": true, "servedFrom": 1 } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429 ], "idempotencyKey": null }, { "operationId": "call-book-equity-v3", "method": "GET", "path": "/v3/market/equity/call-book", "docsUrl": "/api/rest/call-book-equity-v-3", "summary": "Equity call book", "description": "The same book over equities. Same shape as `GET /v3/market/crypto/call-book`.\n\nCost: `1` credit.", "tags": [ "v3 Market" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "bars": [ { "barAt": 1, "live": true, "longShare": 1, "shortShare": 1, "crowdingPercentile": 1, "accountCount": 1, "pulse24": 1, "pulse24LongShare": 1, "pulse6": 1, "pulse6LongShare": 1, "formulaVersion": "string", "computedAt": 1 } ], "nextCursor": "string", "hasMore": true, "servedFrom": 1 } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429 ], "idempotencyKey": null }, { "operationId": "mindshare-equity-v3", "method": "GET", "path": "/v3/market/equity/mindshare", "docsUrl": "/api/rest/mindshare-equity-v-3", "summary": "Equity mindshare", "description": "The same board over equities.\n\nCost: `1` credit.", "tags": [ "v3 Market" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "assets": [ { "rank": 1, "id": "string", "symbol": "string", "name": "string", "share": 1, "changePct": 1, "hot": true, "share1h": 1, "share4h": 1, "ratio1h4h": 1, "capped1h": 1 } ], "nextCursor": "string", "hasMore": true } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429 ], "idempotencyKey": null }, { "operationId": "top-accounts-v3", "method": "GET", "path": "/v3/people/accounts", "docsUrl": "/api/rest/top-accounts-v-3", "summary": "Top accounts", "description": "Who to watch, ranked by standing: how much other accounts reply to, quote and repost\nan account, newer engagement counting more. Standing refreshes daily.\n\nAn account we cannot name is left out rather than ranked blind, so ranks are dense.\n\nEach account carries its `standing` (the 0 to 1 percentile it is ranked by), its\ndisplay name, follower count and verified flag, and `track`, its record as a caller\n(null when it has never opened a position).\n\nCost: `1` credit.", "tags": [ "v3 People" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "accounts": [ { "rank": 1, "handle": "string", "name": "string", "followerCount": 1, "verified": true, "standing": 1, "track": { "alphaScore": 1, "hitRate": 1, "avgReturn": 1, "scoredEpisodes": 1, "totalEpisodes": 1 } } ], "nextCursor": "string", "hasMore": true } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403, 429 ], "idempotencyKey": null }, { "operationId": "x402-get-account-smart-stats-v2", "method": "GET", "path": "/x402/v2/account/smart-stats", "docsUrl": "/api/rest/x-402-get-account-smart-stats-v-2", "summary": "Smart stats of accounts (legacy, removed 28 Oct 2026)", "description": "Retrieve smart stats given username\n\n**Cost:** 1 credit ($0.0145). Requires x402 payment.", "tags": [ "x402 Account" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "fixed", "notes": "1 credit ($0.0145). Requires x402 payment." }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "averageReach": 1, "averageEngagement": 1, "smartFollowingCount": 1 } } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 402 ], "idempotencyKey": null }, { "operationId": "x402-get-trending-cas-telegram-v2", "method": "GET", "path": "/x402/v2/aggregations/trending-cas/telegram", "docsUrl": "/api/rest/x-402-get-trending-cas-telegram-v-2", "summary": "Trending contract addresses on Telegram", "description": "Get trending contract addresses mentioned on Telegram. Returns contract addresses with mention counts.\n\nNote: You must provide EITHER timeWindow OR both from and to parameters.\nIf both timeWindow and from/to are provided, from/to takes priority.\n\n**Cost:** 1 credit ($0.0145). Requires x402 payment.", "tags": [ "x402 Aggregations" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "fixed", "notes": "1 credit ($0.0145). Requires x402 payment." }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "pageSize": 1, "page": 1, "total": 1, "data": [ { "contractAddress": "string", "chain": "ethereum", "mentionCount": 1 } ] } } }, "successStatuses": [ 200 ], "errorStatuses": [ 402 ], "idempotencyKey": null }, { "operationId": "x402-get-trending-cas-twitter-v2", "method": "GET", "path": "/x402/v2/aggregations/trending-cas/twitter", "docsUrl": "/api/rest/x-402-get-trending-cas-twitter-v-2", "summary": "Trending contract addresses on Twitter", "description": "Get trending contract addresses mentioned on Twitter/X. Returns contract addresses with mention counts.\n\nNote: You must provide EITHER timeWindow OR both from and to parameters.\nIf both timeWindow and from/to are provided, from/to takes priority.\n\n**Cost:** 1 credit ($0.0145). Requires x402 payment.", "tags": [ "x402 Aggregations" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "fixed", "notes": "1 credit ($0.0145). Requires x402 payment." }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "pageSize": 1, "page": 1, "total": 1, "data": [ { "contractAddress": "string", "chain": "ethereum", "mentionCount": 1 } ] } } }, "successStatuses": [ 200 ], "errorStatuses": [ 402 ], "idempotencyKey": null }, { "operationId": "x402-get-trending-tokens-v2", "method": "GET", "path": "/x402/v2/aggregations/trending-tokens", "docsUrl": "/api/rest/x-402-get-trending-tokens-v-2", "summary": "Trending tokens", "description": "This experimental endpoint is under active development and its behavior may change without notice.\nUse with caution in production environments.\n\nRetrieve trending tokens based on highest mentions count,\nfiltered by a minimum mention threshold over a specified time period.\n\nNote: You must provide EITHER timeWindow OR both from and to parameters.\nIf both timeWindow and from/to are provided, from/to takes priority.\n\n**Cost:** 1 credit ($0.0145). Requires x402 payment.", "tags": [ "x402 Aggregations" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "fixed", "notes": "1 credit ($0.0145). Requires x402 payment." }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "pageSize": 1, "page": 1, "total": 1, "data": [ { "change_percent": 1, "previous_count": 1, "current_count": 1, "token": "string" } ] } } }, "successStatuses": [ 200 ], "errorStatuses": [ 402 ], "idempotencyKey": null }, { "operationId": "x402-auto-stream-notifications", "method": "GET", "path": "/x402/v2/auto/queries/{queryId}/stream", "docsUrl": "/api/rest/x-402-auto-stream-notifications", "summary": "Stream Notifications", "description": "Stream query notifications via Server-Sent Events (SSE).\nRequires `x-elfa-agent-secret` header.\n\n**Cost:** Free", "tags": [ "x402 Auto" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE", "x-elfa-agent-secret" ], "securitySchemes": [], "paymentRequired": false, "agentSecretRequired": true }, "cost": { "model": "free", "notes": "Free" }, "requestExample": null, "responseExamples": null, "successStatuses": [ 200, 204 ], "errorStatuses": [ 400, 404, 410 ], "idempotencyKey": null }, { "operationId": "x402-get-event-summary-v2", "method": "GET", "path": "/x402/v2/data/event-summary", "docsUrl": "/api/rest/x-402-get-event-summary-v-2", "summary": "Event summary from keyword mentions (5 credits total)", "description": "Generate event summaries based on keyword mentions within a time period.\n\n**Cost:** 5 credits ($0.0725). Requires x402 payment.", "tags": [ "x402 Data" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "fixed", "notes": "5 credits ($0.0725). Requires x402 payment." }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": [ { "tweetIds": [ "string" ], "sourceLinks": [ "string" ], "summary": "string" } ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 402 ], "idempotencyKey": null }, { "operationId": "x402-get-keyword-mentions-v2", "method": "GET", "path": "/x402/v2/data/keyword-mentions", "docsUrl": "/api/rest/x-402-get-keyword-mentions-v-2", "summary": "Multi keyword mentions search", "description": "Search mentions by keywords OR account name within a time period. Either\n`keywords` or `accountName` (or both) must be provided.\n\n**Response shape.** The response envelope is `{ success, data, metadata }`.\n`data` is a flat array of mentions; pagination state lives in `metadata`.\n\n**Cursor pagination.** Unlike `/x402/v2/data/top-mentions` (which uses\n`page`/`pageSize`), this endpoint is cursor-paginated.\n`metadata.cursor` is a millisecond timestamp (number). To fetch the next\npage, pass its value back as the `cursor` query param. Page until `data`\nis empty; `metadata.cursor` is only omitted on that empty page.\n`metadata.total` is the complete matching result set, not the remainder\nafter the cursor, and may be capped at 10000 for performance.\n\n**No tweet content.** V2 does not return raw tweet text. Use the `link`\nfield to fetch the original tweet via the Twitter/X API if needed.\n\n**Account info.** Each mention includes a minimal `account` object with\nonly `username` and `isVerified`. No id, display name, follower count, or\nbio is returned.\n\n**Field notes.** `mentionedAt` is an ISO 8601 string (not a unix\ntimestamp). `repostBreakdown.smart` counts reposts by smart accounts;\n`repostBreakdown.ct` counts reposts by crypto-Twitter accounts.\n\n**Cost:** 1 credit ($0.0145). Requires x402 payment.", "tags": [ "x402 Data" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "fixed", "notes": "1 credit ($0.0145). Requires x402 payment." }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": [ { "tweetId": "string", "link": "string", "likeCount": 1, "repostCount": 1, "viewCount": 1, "quoteCount": 1, "replyCount": 1, "bookmarkCount": 1, "mentionedAt": "string", "type": "repost", "repostBreakdown": { "ct": 1, "smart": 1 } } ], "metadata": { "total": 1 } } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 402 ], "idempotencyKey": null }, { "operationId": "x402-get-token-news-v2", "method": "GET", "path": "/x402/v2/data/token-news", "docsUrl": "/api/rest/x-402-get-token-news-v-2", "summary": "Token news mentions (tweet source only)", "description": "Retrieve token-related news mentions.\n\nResults are X (Twitter) posts from accounts tagged as news sources, not\narticles published by news outlets.\n\n**Cost:** 1 credit ($0.0145). Requires x402 payment.", "tags": [ "x402 Data" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "fixed", "notes": "1 credit ($0.0145). Requires x402 payment." }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": [ { "tweetId": "string", "link": "string", "likeCount": 1, "repostCount": 1, "viewCount": 1, "quoteCount": 1, "replyCount": 1, "bookmarkCount": 1, "mentionedAt": "string", "type": "repost", "repostBreakdown": { "ct": 1, "smart": 1 } } ], "metadata": { "pageSize": 1, "page": 1, "total": 1 } } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 402 ], "idempotencyKey": null }, { "operationId": "x402-get-top-mentions-v2", "method": "GET", "path": "/x402/v2/data/top-mentions", "docsUrl": "/api/rest/x-402-get-top-mentions-v-2", "summary": "Top mentions", "description": "Returns the most significant mentions for a given ticker symbol, ranked by\nengagement (viewCount → mentionedAt → relevance) within a specified time\nwindow.\n\n**Response shape.** The response envelope is `{ success, data, metadata }`.\n`data` is a flat array of mentions; pagination state lives in `metadata`\n(`total`, `page`, `pageSize`) — never merged into the top level.\n\n**No tweet content.** V2 does not return raw tweet text. Use the `link`\nfield to fetch the original tweet via the Twitter/X API if needed.\n\n**No account object.** Unlike `/x402/v2/data/keyword-mentions`, this\nendpoint does not return an `account` object per mention.\n\n**Field notes.** `mentionedAt` is an ISO 8601 string (not a unix\ntimestamp). `repostBreakdown.smart` counts reposts by smart accounts;\n`repostBreakdown.ct` counts reposts by crypto-Twitter accounts.\n\n**Cost:** 1 credit ($0.0145). Requires x402 payment.", "tags": [ "x402 Data" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "fixed", "notes": "1 credit ($0.0145). Requires x402 payment." }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": [ { "tweetId": "string", "link": "string", "likeCount": 1, "repostCount": 1, "viewCount": 1, "quoteCount": 1, "replyCount": 1, "bookmarkCount": 1, "mentionedAt": "string", "type": "repost", "repostBreakdown": { "ct": 1, "smart": 1 } } ], "metadata": { "pageSize": 1, "page": 1, "total": 1 } } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 402 ], "idempotencyKey": null }, { "operationId": "x402-get-trending-narratives-v2", "method": "GET", "path": "/x402/v2/data/trending-narratives", "docsUrl": "/api/rest/x-402-get-trending-narratives-v-2", "summary": "Trending narratives (5 credits total)", "description": "Get trending narratives based on Twitter mentions analysis.\n\n**Cost:** 5 credits ($0.0725). Requires x402 payment.", "tags": [ "x402 Data" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "fixed", "notes": "5 credits ($0.0725). Requires x402 payment." }, "requestExample": null, "responseExamples": { "200": { "success": true, "data": { "metadata": { "error": "string", "total_tweets": 1, "total_narratives": 1 }, "trending_narratives": [ { "tweet_ids": [ "string" ], "source_links": [ "string" ], "narrative": "string" } ] } } }, "successStatuses": [ 200 ], "errorStatuses": [ 402 ], "idempotencyKey": null }, { "operationId": "auto-chat-v2", "method": "POST", "path": "/v2/auto/chat", "docsUrl": "/api/rest/auto-chat-v-2", "summary": "Builder Chat", "description": "Ask the AI to help you build an EQL query.\n\nThe response message contains the AI's reply in Markdown. When it generates EQL,\nit will be in a JSON code block that you can extract, validate, and submit.\n\nUse `sessionId` in follow-up requests to maintain conversation context.\n\n### Cost\n\nAPI mode: `1 + dynamic` credits\n- base request charge: `1` credit\n- dynamic usage charge: `ceil(request_cost * 750)` credits\n\nx402 mode is quoted in USD per turn, not credits. The 402 response lists\nthe schemes it accepts and the client picks one:\n- `exact` (flat, charged in full): `fast` `$1`, `expert` `$2`\n- `batch-settlement` (Base, when listed: deposit once into a payment\n channel; each turn is capped at `fast` `$2`, `expert` `$6` and charged\n its actual cost)\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\nChat produces drafts only; subsequent activation goes through\n`POST /queries/drafts/{draftId}/convert`.\n\n### Request Example\n\n```json\n{\n \"message\": \"Alert me when BTC breaks 100k\",\n \"speed\": \"expert\",\n \"sessionId\": \"optional-session-id\"\n}\n```\n\n### Response Example (200)\n\n```json\n{\n \"sessionId\": \"session-uuid\",\n \"response\": \"I can help with that...\",\n \"title\": \"BTC Breakout Alert\",\n \"reasoning\": null,\n \"planIds\": [],\n \"credits\": 104\n}\n```\n\n`credits` is what this call cost, and carries the same total as the\n`x-elfa-credits` response header. Chat is dynamically priced, so read it\nrather than assuming a flat cost.\n\n> Best practice: persist `sessionId` and reuse it for follow-up prompts so\n> the model keeps context across turns.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "dynamic", "notes": "API mode: `1 + dynamic` credits - base request charge: `1` credit - dynamic usage charge: `ceil(request_cost * 750)` credits x402 mode is quoted in USD per turn, not credits. The 402 response lists the schemes it accepts and the client picks one: - `exact` (flat, charged in full): `fast` `$1`, `expert` `$2` - `batch-settlement` (Base, when listed: deposit once into a payment channel; each turn is capped at `fast` `$2`, `expert` `$6` and charged its actual cost)" }, "requestExample": { "message": "Build an Auto query for BTC breakout above 100k.", "speed": "expert" }, "responseExamples": { "200": { "sessionId": "string", "response": "string", "title": "string", "reasoning": "string", "planIds": [ "string" ], "credits": 1 } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403 ], "idempotencyKey": null }, { "operationId": "auto-create-query-v2", "method": "POST", "path": "/v2/auto/queries", "docsUrl": "/api/rest/auto-create-query-v-2", "summary": "Create Query", "description": "Create and activate a conditional query.\n\n### Required Sequence (Enforced)\n\nCall `POST /v2/auto/queries/validate` immediately before create.\n\nLifecycle after create:\n1. `POST /v2/auto/queries/{queryId}/cancel` while status is `active`.\n2. `DELETE /v2/auto/queries/{queryId}` only when status is terminal\n (`triggered`, `expired`, `cancelled`, `failed`).\n\n**Allowed action types (API key mode):**\n`webhook`, `notify`, `telegram_bot`, `llm`.\n\n### Cost\n\nSimulation-driven estimate (reference values):\n- baseline: `5 credits` (`$0.0725`)\n- fast call: `+5 credits` (`+$0.0725`)\n- expert call: `+18 credits` (`+$0.261`)\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\n### Request Example\n\n```json\n{\n \"query\": {\n \"conditions\": {\n \"AND\": [\n {\n \"source\": \"price\",\n \"method\": \"current\",\n \"args\": { \"symbol\": \"BTC\" },\n \"operator\": \">\",\n \"value\": 100000\n }\n ]\n },\n \"actions\": [\n {\n \"stepId\": \"step_1\",\n \"type\": \"notify\",\n \"params\": { \"message\": \"BTC crossed target\" }\n }\n ],\n \"expiresIn\": \"24h\"\n },\n \"title\": \"BTC breakout alert\",\n \"description\": \"Notify when BTC is above 100k\"\n}\n```\n\n### Response Example (201)\n\n```json\n{\n \"queryId\": \"a12d20ff-6cb2-433e-afed-cc2e6a0380b6\",\n \"status\": \"active\",\n \"estimatedCredits\": 116,\n \"simulationLlmCallsEstimate\": {\n \"conditionCallsUpperBound\": 1,\n \"actionCallsUpperBound\": 0,\n \"conditionCallsBySpeed\": {\"fast\": 1, \"expert\": 0, \"adaptive\": 0},\n \"actionCallsBySpeed\": {\"fast\": 0, \"expert\": 0, \"adaptive\": 0},\n \"autoActionCallsBySpeed\": {\"fast\": 0, \"expert\": 0, \"adaptive\": 0}\n }\n}\n```\n\n> Best practice: call validate first, then create. After creation, wire\n> notifications (`webhook`, `telegram_bot`, or SSE) to a background runner.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "dynamic", "notes": "Simulation-driven estimate (reference values): - baseline: `5 credits` (`$0.0725`) - fast call: `+5 credits` (`+$0.0725`) - expert call: `+18 credits` (`+$0.261`)" }, "requestExample": { "query": { "conditions": { "AND": [ { "source": "price", "method": "current", "args": { "symbol": "BTC" }, "operator": ">", "value": 100000 } ] }, "actions": [ { "stepId": "step_1", "type": "notify", "params": { "message": "BTC crossed target" } } ], "expiresIn": "24h" }, "title": "BTC breakout alert", "description": "Notify when BTC is above 100k so I can review the breakout setup." }, "responseExamples": { "200": { "key": {} }, "201": { "key": {} } }, "successStatuses": [ 200, 201 ], "errorStatuses": [ 400, 401, 403, 409, 422 ], "idempotencyKey": null }, { "operationId": "auto-cancel-query-v2", "method": "POST", "path": "/v2/auto/queries/{queryId}/cancel", "docsUrl": "/api/rest/auto-cancel-query-v-2", "summary": "Cancel Query", "description": "Cancel an active query.\n\nOnly queries in `active` status can be cancelled. Queries\nalready in a terminal state return 409 Conflict.\nThis endpoint does not delete query records; use\n`DELETE /v2/auto/queries/{queryId}` after a terminal status when you need\nsoft-delete behavior.\n\n### Cost\n\nFree.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\n### Request Example\n\nPath parameter:\n- `queryId` (string)\n\n### Response Example (200)\n\n```json\n{\n \"id\": \"a12d20ff-6cb2-433e-afed-cc2e6a0380b6\",\n \"status\": \"cancelled\",\n \"cancelledAt\": \"2026-04-01T12:00:00.000Z\"\n}\n```\n\n> Best practice: keep cancellation idempotent in your client workflow;\n> treat repeated cancel attempts as safe no-op behavior.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "free", "notes": "Free." }, "requestExample": null, "responseExamples": { "200": { "key": {} } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 404, 409 ], "idempotencyKey": null }, { "operationId": "auto-upsert-query-draft-v2", "method": "POST", "path": "/v2/auto/queries/drafts", "docsUrl": "/api/rest/auto-upsert-query-draft-v-2", "summary": "Upsert Query Draft", "description": "Create or update a query draft.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": { "query": { "conditions": { "AND": [ { "source": "price", "method": "change", "args": { "symbol": "ETH", "period": "24h" }, "operator": ">=", "value": 5 } ] }, "actions": [ { "stepId": "step_1", "type": "webhook", "params": { "url": "https://your-runner.example/auto/events" } } ], "expiresIn": "24h" }, "title": "ETH momentum draft", "description": "Draft query to alert when ETH 24h change is at least +5%." }, "responseExamples": { "200": { "key": {} } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401 ], "idempotencyKey": null }, { "operationId": "auto-convert-query-draft-v2", "method": "POST", "path": "/v2/auto/queries/drafts/{draftId}/convert", "docsUrl": "/api/rest/auto-convert-query-draft-v-2", "summary": "Convert Query Draft", "description": "Convert a draft into an active query.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": null, "responseExamples": { "200": { "key": {} }, "201": { "key": {} } }, "successStatuses": [ 200, 201 ], "errorStatuses": [ 401, 404, 409 ], "idempotencyKey": null }, { "operationId": "auto-validate-query-draft-v2", "method": "POST", "path": "/v2/auto/queries/drafts/{draftId}/validate", "docsUrl": "/api/rest/auto-validate-query-draft-v-2", "summary": "Validate Query Draft", "description": "Validate a stored query draft without converting it.\n\nRuns the same checks as `POST /v2/auto/queries/validate` against the draft's\ncurrent EQL: schema, semantics, action restrictions, and destination\nreachability. Returns simulation-based cost details when valid. Does not\nactivate the draft — call `POST /v2/auto/queries/drafts/{draftId}/convert`\nfor that.\n\n### Cost\n\nFree.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "free", "notes": "Free." }, "requestExample": null, "responseExamples": { "200": { "valid": true, "errors": [ "string" ], "warnings": [ "string" ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 401, 404 ], "idempotencyKey": null }, { "operationId": "auto-validate-query-v2", "method": "POST", "path": "/v2/auto/queries/validate", "docsUrl": "/api/rest/auto-validate-query-v-2", "summary": "Validate Query", "description": "Validate EQL syntax and get a cost estimate without creating a query.\nReturns simulation-based cost details when the query is valid.\n\n### Required Sequence (Enforced)\n\n`POST /v2/auto/queries/validate` must be called before\n`POST /v2/auto/queries`.\n\nLifecycle sequencing after create:\n1. `POST /v2/auto/queries/{queryId}/cancel` while status is\n `active`.\n2. `DELETE /v2/auto/queries/{queryId}` only after status is terminal\n (`triggered`, `expired`, `cancelled`, `failed`).\n\n### Cost\n\nFree.\n\n### Auth\n\nRequired header:\n```http\nx-elfa-api-key: \n```\n\n### Request Example\n\n```json\n{\n \"query\": {\n \"conditions\": {\n \"AND\": [\n {\n \"source\": \"price\",\n \"method\": \"current\",\n \"args\": { \"symbol\": \"BTC\" },\n \"operator\": \">\",\n \"value\": 100000\n }\n ]\n },\n \"actions\": [\n {\n \"stepId\": \"step_1\",\n \"type\": \"notify\",\n \"params\": { \"message\": \"BTC crossed target\" }\n }\n ],\n \"expiresIn\": \"24h\"\n },\n \"title\": \"BTC breakout alert\",\n \"description\": \"Notify when BTC is above 100k so I can review the breakout setup.\"\n}\n```\n\n### Response Example (200)\n\n```json\n{\n \"valid\": true,\n \"errors\": [],\n \"warnings\": [],\n \"simulationLlmCallsEstimate\": {\n \"conditionCallsUpperBound\": 1,\n \"actionCallsUpperBound\": 0,\n \"conditionCallsBySpeed\": { \"fast\": 1, \"expert\": 0, \"adaptive\": 0 },\n \"actionCallsBySpeed\": { \"fast\": 0, \"expert\": 0, \"adaptive\": 0 },\n \"autoActionCallsBySpeed\": { \"fast\": 0, \"expert\": 0, \"adaptive\": 0 }\n },\n \"estimatedCost\": {\n \"credits\": 30,\n \"price\": \"$0.270\"\n }\n}\n```\n\n> Best practice: always validate before create to catch schema issues and\n> preview estimated cost.", "tags": [ "v2 Auto" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "free", "notes": "Free." }, "requestExample": { "query": { "conditions": { "AND": [ { "source": "price", "method": "current", "args": { "symbol": "BTC" }, "operator": ">", "value": 100000 } ] }, "actions": [ { "stepId": "step_1", "type": "notify", "params": { "message": "BTC crossed target" } } ], "expiresIn": "24h" }, "title": "BTC breakout alert", "description": "Notify when BTC is above 100k so I can review the breakout setup." }, "responseExamples": { "200": { "valid": true, "errors": [ "string" ], "warnings": [ "string" ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403 ], "idempotencyKey": null }, { "operationId": "chat-v2", "method": "POST", "path": "/v2/chat", "docsUrl": "/api/rest/chat-v-2", "summary": "AI chat", "description": "Send a message to the Elfa AI and receive a complete response.\nSuited for agents and integrations that do not support server-sent events (SSE).\n\n**Session management:** omit `sessionId` to start a new conversation.\nThe response includes a `sessionId` — pass it in subsequent requests to continue the same conversation.\n\n**Analysis types and required fields:**\n- `chat` (default) — general conversation. Requires `message`.\n- `macro` — macro market overview. No `message` needed.\n- `summary` — quick market summary. No `message` needed.\n- `tokenIntro` — token introduction. Requires `assetMetadata` with `symbol`, or `chain` + `contractAddress`.\n- `tokenAnalysis` — token trade setup analysis. Same `assetMetadata` requirements as `tokenIntro`.\n- `accountAnalysis` — Twitter/X account analysis. Requires `assetMetadata.username`.\n\n`message` is only used for `analysisType: \"chat\"` and is ignored for other\nanalysis types.\n\n**Sources (opt-in):** send `includeSources: true` to receive `data.sources`,\nthe links the research behind the answer read (X posts, news, DEX and\nexplorer pages, prediction markets), each with a `kind`. Links only: page\nand post content is not returned. A source was read, not necessarily cited\nin `message`. Without the flag the response is unchanged.\n\n**`assetMetadata` fields (when applicable):**\n- `symbol` — token ticker symbol (e.g. `\"BTC\"`, `\"$ETH\"`)\n- `chain` — blockchain name (e.g. `\"ethereum\"`, `\"solana\"`)\n- `contractAddress` — token contract address\n- `username` — Twitter/X username for account analysis", "tags": [ "v2 Chat" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": { "message": "Why is BTC moving today?", "analysisType": "chat", "speed": "expert" }, "responseExamples": { "200": { "success": true, "data": { "creditsConsumed": 1, "sessionId": "string", "message": "string" } } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401 ], "idempotencyKey": null }, { "operationId": "chat-stream-v2", "method": "POST", "path": "/v2/chat/stream", "docsUrl": "/api/rest/chat-stream-v-2", "summary": "AI chat stream", "description": "Stream a response from Elfa AI using Server-Sent Events (SSE).\n\nUse this when your client can consume incremental events. Use\n`POST /v2/chat` instead when your integration needs a complete JSON\nresponse.\n\n**Access:** PAYG and Enterprise API keys.\n\n**Response format:** `text/event-stream`.\n\nCommon `data:` event payloads include:\n- `session_info` with `sessionId` and `analysisType`\n- `title` with a generated session or analysis title\n- `text` with incremental Markdown content\n- `text_complete` when incremental text has finished\n- `status` with progress updates\n- `credits` with consumed credits\n- `complete` with final `sessionId`, `success`, and `creditsConsumed`; with\n `includeSources: true` in the request it also carries `sources` (the\n links the research read; same shape as `POST /v2/chat`)\n- `invalid_request` when a query is rejected by safety checks\n- `error` for stream failures\n\nA `: keep-alive` comment may be sent during long gaps. The stream ends\nwith `data: [DONE]`.\n\nRequest-body semantics match `POST /v2/chat`: `message` is required only\nfor `analysisType: \"chat\"`; token and account modes use `assetMetadata`.", "tags": [ "v2 Chat" ], "beta": false, "mode": "api_key", "auth": { "headers": [ "x-elfa-api-key" ], "securitySchemes": [ "api_key" ], "paymentRequired": false, "agentSecretRequired": false }, "cost": { "model": "unknown", "notes": null }, "requestExample": { "message": "Why is BTC moving today?", "analysisType": "chat", "speed": "expert" }, "responseExamples": null, "successStatuses": [ 200 ], "errorStatuses": [ 400, 401, 403 ], "idempotencyKey": null }, { "operationId": "x402-auto-chat", "method": "POST", "path": "/x402/v2/auto/chat", "docsUrl": "/api/rest/x-402-auto-chat", "summary": "Builder Chat", "description": "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.\n\nThe response message contains the AI's reply in Markdown. When it generates EQL,\nit will be in a JSON code block that you can extract, validate, and submit.\n\nUse `sessionId` in follow-up requests to maintain conversation context.\n\n**Cost:** speed based. Pay a flat price per turn with the `exact` scheme\n(`fast` $1, `expert` $2). Where the 402 also lists `batch-settlement`\n(Base), you can instead deposit once into a payment channel: each turn is\nthen capped at `fast` $2 / `expert` $6 and charged only what it cost.\nRequires x402 payment.", "tags": [ "x402 Auto" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "dynamic", "notes": "speed based. Pay a flat price per turn with the `exact` scheme" }, "requestExample": { "message": "Build an Auto query for ETH downside alert under 2500.", "speed": "fast" }, "responseExamples": { "200": { "success": true, "data": { "creditsConsumed": 1, "sessionId": "string", "message": "string" } } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 402 ], "idempotencyKey": null }, { "operationId": "x402-auto-create-query", "method": "POST", "path": "/x402/v2/auto/queries", "docsUrl": "/api/rest/x-402-auto-create-query", "summary": "Create Query", "description": "Create and activate a conditional query that monitors market data and triggers actions when conditions are met.\n\n**Allowed action types:** `webhook`, `notify`, `telegram_bot`, `llm`.\n\n**Cost:** Dynamic. Base fee is 5 credits ($0.0725) plus simulated LLM calls:\nfast = +5 credits (+$0.0725) per call, expert = +18 credits (+$0.261) per call.\nUse the validate endpoint to preview costs.\nRequires `x-elfa-agent-secret` header.\nRequires x402 payment.", "tags": [ "x402 Auto" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE", "x-elfa-agent-secret" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": true }, "cost": { "model": "dynamic", "notes": "Dynamic. Base fee is 5 credits ($0.0725) plus simulated LLM calls:" }, "requestExample": { "query": { "conditions": { "AND": [ { "source": "price", "method": "current", "args": { "symbol": "SOL" }, "operator": ">", "value": 220 } ] }, "actions": [ { "stepId": "step_1", "type": "telegram_bot", "params": { "botToken": "", "chatId": "" } } ], "expiresIn": "24h" }, "title": "SOL breakout alert", "description": "Send a Telegram alert if SOL moves above 220." }, "responseExamples": { "200": { "queryId": "string", "status": "string" }, "201": { "queryId": "string", "status": "string" } }, "successStatuses": [ 200, 201 ], "errorStatuses": [ 400, 402, 422 ], "idempotencyKey": null }, { "operationId": "x402-auto-poll-query", "method": "POST", "path": "/x402/v2/auto/queries/{queryId}", "docsUrl": "/api/rest/x-402-auto-poll-query", "summary": "Poll Query", "description": "Check query status and execution results.\nRequires `x-elfa-agent-secret` header.\n\n`latestEvaluation` is the latest current-state snapshot, including\n`conditionStates[]`. Execution records include Auto Trigger Context\n(`triggerTime`, `conditionsMet`, `trigger`) when the query has fired.\n\n**Cost:** Free", "tags": [ "x402 Auto" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE", "x-elfa-agent-secret" ], "securitySchemes": [], "paymentRequired": false, "agentSecretRequired": true }, "cost": { "model": "free", "notes": "Free" }, "requestExample": null, "responseExamples": { "200": { "queryId": "string", "status": "string", "latestEvaluation": { "evaluatedAt": "string", "conditionStates": [ { "index": 1, "source": "string", "method": "string" } ], "wouldTriggerNow": true, "matchingConditions": 1, "totalConditions": 1 }, "executions": [ { "id": "string", "queryId": "string", "type": "string", "status": "string", "createdAt": "string" } ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 404 ], "idempotencyKey": null }, { "operationId": "x402-auto-cancel-query", "method": "POST", "path": "/x402/v2/auto/queries/{queryId}/cancel", "docsUrl": "/api/rest/x-402-auto-cancel-query", "summary": "Cancel Query", "description": "Cancel an active query.\nRequires `x-elfa-agent-secret` header.\n\n**Cost:** Free", "tags": [ "x402 Auto" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE", "x-elfa-agent-secret" ], "securitySchemes": [], "paymentRequired": false, "agentSecretRequired": true }, "cost": { "model": "free", "notes": "Free" }, "requestExample": null, "responseExamples": { "200": { "id": "string", "status": "string", "cancelledAt": "string" } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 404, 409 ], "idempotencyKey": null }, { "operationId": "x402-auto-list-sessions", "method": "POST", "path": "/x402/v2/auto/queries/{queryId}/sessions", "docsUrl": "/api/rest/x-402-auto-list-sessions", "summary": "List LLM Sessions", "description": "List LLM output sessions for a query.\nOnly relevant for queries with `actions[0].type: \"llm\"`.\nRequires `x-elfa-agent-secret` header.\n\n**Cost:** Free", "tags": [ "x402 Auto" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE", "x-elfa-agent-secret" ], "securitySchemes": [], "paymentRequired": false, "agentSecretRequired": true }, "cost": { "model": "free", "notes": "Free" }, "requestExample": null, "responseExamples": { "200": { "queryId": "string", "sessions": [ { "sessionId": "string", "status": "string", "executedAt": "string" } ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 400 ], "idempotencyKey": null }, { "operationId": "x402-auto-get-session", "method": "POST", "path": "/x402/v2/auto/queries/{queryId}/sessions/{sessionId}", "docsUrl": "/api/rest/x-402-auto-get-session", "summary": "LLM Session Details", "description": "Get full LLM analysis output for a specific session, including conversation messages and analysis details.\nRequires `x-elfa-agent-secret` header.\n\n**Cost:** Free", "tags": [ "x402 Auto" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE", "x-elfa-agent-secret" ], "securitySchemes": [], "paymentRequired": false, "agentSecretRequired": true }, "cost": { "model": "free", "notes": "Free" }, "requestExample": null, "responseExamples": { "200": { "sessionId": "string", "queryId": "string", "title": "string", "analysisType": "string", "createdAt": "string", "messages": [ { "query": "string", "response": "string", "status": "string", "analysisType": "string", "timestamp": "string" } ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 404 ], "idempotencyKey": null }, { "operationId": "x402-auto-validate-query", "method": "POST", "path": "/x402/v2/auto/queries/validate", "docsUrl": "/api/rest/x-402-auto-validate-query", "summary": "Validate Query", "description": "Validate EQL syntax and get a cost estimate without creating a query.\nReturns a simulation-based cost estimate when the query is valid.\nRequires `x-elfa-agent-secret` header.\n\n**Cost:** Free", "tags": [ "x402 Auto" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE", "x-elfa-agent-secret" ], "securitySchemes": [], "paymentRequired": false, "agentSecretRequired": true }, "cost": { "model": "free", "notes": "Free" }, "requestExample": { "query": { "conditions": { "AND": [ { "source": "price", "method": "current", "args": { "symbol": "ETH" }, "operator": "<", "value": 2500 } ] }, "actions": [ { "stepId": "step_1", "type": "webhook", "params": { "url": "https://your-runner.example/auto/events" } } ], "expiresIn": "24h" }, "title": "ETH downside guardrail", "description": "Alert if ETH breaks below 2500 so risk can be reviewed quickly." }, "responseExamples": { "200": { "valid": true, "errors": [ "string" ], "warnings": [ "string" ] } }, "successStatuses": [ 200 ], "errorStatuses": [ 400 ], "idempotencyKey": null }, { "operationId": "x402-chat-v2", "method": "POST", "path": "/x402/v2/chat", "docsUrl": "/api/rest/x-402-chat-v-2", "summary": "AI chat", "description": "Send a message to the Elfa AI and receive a complete response.\nSuited for agents and integrations that do not support server-sent events (SSE).\n\n**Analysis types and required fields:**\n- `chat` (default) — general conversation. Requires `message`.\n- `macro` — macro market overview. No `message` needed.\n- `summary` — quick market summary. No `message` needed.\n- `tokenIntro` — token introduction. Requires `assetMetadata` with `symbol`, or `chain` + `contractAddress`.\n- `tokenAnalysis` — token trade setup analysis. Same `assetMetadata` requirements as `tokenIntro`.\n- `accountAnalysis` — Twitter/X account analysis. Requires `assetMetadata.username`.\n\n`message` is only used for `analysisType: \"chat\"` and is ignored for other\nanalysis types. `adaptive` speed is not available on x402.\n\nSend `includeSources: true` to receive `data.sources`: the links the\nresearch behind the answer read, with a `kind` each. Links only: page and\npost content is not returned.\n\n**`assetMetadata` fields (when applicable):**\n- `symbol` — token ticker symbol (e.g. `\"BTC\"`, `\"$ETH\"`)\n- `chain` — blockchain name (e.g. `\"ethereum\"`, `\"solana\"`)\n- `contractAddress` — token contract address\n- `username` — Twitter/X username for account analysis\n\n**Cost:** speed based. Pay a flat price per turn with the `exact` scheme\n(`fast` $1, `expert` $2). Where the 402 also lists `batch-settlement`\n(Base), you can instead deposit once into a payment channel: each turn is\nthen capped at `fast` $2 / `expert` $6 and charged only what it cost.\nRequires x402 payment.", "tags": [ "x402 Chat" ], "beta": false, "mode": "x402", "auth": { "headers": [ "PAYMENT-SIGNATURE" ], "securitySchemes": [], "paymentRequired": true, "agentSecretRequired": false }, "cost": { "model": "dynamic", "notes": "speed based. Pay a flat price per turn with the `exact` scheme" }, "requestExample": { "analysisType": "summary", "speed": "fast" }, "responseExamples": { "200": { "success": true, "data": { "creditsConsumed": 1, "sessionId": "string", "message": "string" } } }, "successStatuses": [ 200 ], "errorStatuses": [ 400, 402 ], "idempotencyKey": null } ] }