ELFA DOCS — plain text for machines ================================== You asked for this site without asking for a document, so here is the machine-readable index instead of the rendered site. A human should open the same URL in a browser. https://docs.elfa.ai/llms.txt this index https://docs.elfa.ai/llms-full.txt every page, one file The API origin is separate and pay-per-request over x402: https://api.elfa.ai/.well-known/x402 payable resources, JSON Documentation pages in the sections below are also served as raw markdown at the same path with a `.md` suffix. The external links and generated JSON artifacts listed at the end are not. # Elfa API Documentation > Developer and agent documentation for Elfa APIs: API v3 real-time events, calls, positioning, mindshare and ranked accounts; v2 REST market intelligence endpoints, Auto condition/action workflows, x402 pay-per-request access, Widget integration, authentication, rate limits, and machine-readable endpoint metadata. Base URL: https://api.elfa.ai. - [Elfa API Documentation](/index.md) ## api - [API Reference](/api.md): Every Elfa REST endpoint in one table, grouped by resource, with the version each belongs to: API v3, API v2, and API v2 over x402. - [Account](/api/v2/account.md): Check your v2 API key's status, limits and usage, and check that the API is up. - [Accounts](/api/v2/accounts.md): Raw reach and smart-audience metrics for one X account, from the legacy smart stats endpoint. - [Chat](/api/v2/chat.md): Ask Elfa a market question in plain language and get a written answer, as one JSON response or as a Server-Sent Events stream. - [AI chat](/api/v2/endpoints/chat.md): Ask Elfa AI and get one complete JSON answer. - [AI chat stream](/api/v2/endpoints/chat-stream.md): Ask Elfa AI and stream the answer as server-sent events. - [Elfa Api](/api/v2/endpoints/elfa-api.md): API documentation for Elfa - [Event summary from keyword mentions (5 credits total)](/api/v2/endpoints/event-summary.md): AI summaries of the events behind keyword mentions in a time window. - [API key status](/api/v2/endpoints/key-status.md): The status and usage of your API key. - [Multi keyword mentions search](/api/v2/endpoints/keyword-mentions.md): Posts matching keywords or from one account in a time window. - [Health check endpoint](/api/v2/endpoints/ping.md): Health check: answers when the API is up. - [Smart stats of accounts (legacy, removed 28 Oct 2026)](/api/v2/endpoints/smart-stats.md): Smart stats for one X account, removed 28 Oct 2026. - [Token news mentions (tweet source only)](/api/v2/endpoints/token-news.md): Token news posts on X from accounts tagged as news sources. - [Top mentions](/api/v2/endpoints/top-mentions.md): The most-engaged posts about one ticker in a time window. - [Trending contract addresses on Telegram](/api/v2/endpoints/trending-cas-telegram.md): Contract addresses trending on Telegram, with mention counts. - [Trending contract addresses on Twitter](/api/v2/endpoints/trending-cas-twitter.md): Contract addresses trending on X, with mention counts. - [Trending narratives (5 credits total)](/api/v2/endpoints/trending-narratives.md): The narratives trending in X mentions. - [Trending tokens](/api/v2/endpoints/trending-tokens.md): Tokens ranked by mention count over a time window. - [Enums and Errors](/api/v2/enums-and-errors.md): Every enum value the v2 and x402 v2 endpoints take or return, and every v2 error code, with what each one means and what to do next. - [Mentions](/api/v2/mentions.md): Find the X posts behind a ticker, keyword, account or token news, with links and engagement metrics. - [Narratives](/api/v2/narratives.md): Get written, source-linked summaries of what happened for a keyword and of the themes leading market attention. - [Market Intelligence](/api/v2/overview.md): How the v2 market intelligence endpoints split into measurement and interpretation, how to reach them, and the conventions every v2 endpoint follows. - [Trending](/api/v2/trending.md): Find which tokens and contract addresses are getting attention right now, ranked by mention counts. - [AI chat](/api/v2/x402/chat.md): Ask Elfa AI and get one complete JSON answer. - [Elfa Api](/api/v2/x402/elfa-api.md): API documentation for Elfa - [Event summary from keyword mentions (5 credits total)](/api/v2/x402/event-summary.md): AI summaries of the events behind keyword mentions in a time window. - [Multi keyword mentions search](/api/v2/x402/keyword-mentions.md): Posts matching keywords or from one account in a time window. - [Smart stats of accounts (legacy, removed 28 Oct 2026)](/api/v2/x402/smart-stats.md): Smart stats for one X account, removed 28 Oct 2026. - [Token news mentions (tweet source only)](/api/v2/x402/token-news.md): Token news posts on X from accounts tagged as news sources. - [Top mentions](/api/v2/x402/top-mentions.md): The most-engaged posts about one ticker in a time window. - [Trending contract addresses on Telegram](/api/v2/x402/trending-cas-telegram.md): Contract addresses trending on Telegram, with mention counts. - [Trending contract addresses on Twitter](/api/v2/x402/trending-cas-twitter.md): Contract addresses trending on X, with mention counts. - [Trending narratives (5 credits total)](/api/v2/x402/trending-narratives.md): The narratives trending in X mentions. - [Trending tokens](/api/v2/x402/trending-tokens.md): Tokens ranked by mention count over a time window. - [Account: Key Status](/api/v3/account.md): What your API key can do and what it has left: plan, scopes, credits, per-minute limit and how far back it reads. - [Calls, Call Episodes and Positioning](/api/v3/calls.md): What accounts are doing: every post where an account or channel takes or changes a position (calls), the positions those posts make up from open to close (call episodes), and how many positions are open long and short on one asset (positioning). - [Concepts](/api/v3/concepts.md): What each thing API v3 returns is, in plain words with a real example: entities and asset families, events, storylines, arcs, calls, call episodes, call books, positioning, mindshare and hot, trending contracts, standing, and the history limit. - [Crypto call book](/api/v3/endpoints/crypto-call-book.md): How the accounts Elfa follows are positioned in crypto, hour by hour. - [Crypto mindshare](/api/v3/endpoints/crypto-mindshare.md): Crypto assets ranked by share of attention over a period. - [Elfa Api](/api/v3/endpoints/elfa-api.md): API documentation for Elfa - [Equity call book](/api/v3/endpoints/equity-call-book.md): How the accounts Elfa follows are positioned in equities, hour by hour. - [Equity mindshare](/api/v3/endpoints/equity-mindshare.md): Equities ranked by share of attention over a period. - [Key status](/api/v3/endpoints/key-status.md): What this key can do: its plan, scopes, credits and history reach. - [Arcs](/api/v3/endpoints/list-arcs.md): Storylines that belong to the same larger movement. - [Call episodes](/api/v3/endpoints/list-call-episodes.md): One account's position on one asset, from the call that opened it to the one that closed it. - [Calls](/api/v3/endpoints/list-calls.md): Every call: one post that opened, changed or closed a position. - [Events](/api/v3/endpoints/list-events.md): What happened, to what, and when, newest first. - [Storylines](/api/v3/endpoints/list-storylines.md): What is developing over time: storylines, each built from many events. - [Positioning](/api/v3/endpoints/positioning.md): How the open positions on one asset are split, right now. - [Entities](/api/v3/endpoints/resolve-entities.md): Turns what a caller holds into the id every other v3 endpoint takes. - [Top accounts](/api/v3/endpoints/top-accounts.md): The accounts worth watching, ranked. - [Trending contracts](/api/v3/endpoints/trending-contracts.md): Contract addresses being pasted on X and Telegram, counted together. - [Entities](/api/v3/entities.md): Resolve a ticker, name, handle, contract address, CoinGecko id, FIGI or CIK to the id every v3 endpoint takes, and how asset families make WBTC and BTC the same asset. - [Enums and Errors](/api/v3/enums-and-errors.md): Every enum value and every error status API v3 returns, with what each one means and what to do next. - [Events, Storylines and Arcs](/api/v3/events.md): What is happening in crypto and equity markets: events Elfa writes up from posts across many sources, the storylines that thread them over days, and the arcs that group storylines into larger movements. - [Market: Call Books, Mindshare and Trending Contracts](/api/v3/market.md): Whole-market views from API v3: hourly call books for crypto and equities, assets ranked by share of attention with hot, and contract addresses ranked by how many posts pasted them. - [API v3 New](/api/v3/overview.md): API v3, the data stack that powers agent awareness with real-time context: events, storylines and arcs; call books, mindshare and trending contracts; calls, call episodes and positioning; ranked accounts. What it returns, how to get access, and the rules every v3 endpoint shares. - [People: Top Accounts](/api/v3/people.md): Who is worth reading: accounts ranked by standing (how much other accounts engage with them) or by their record as callers (alpha score, hit rate, average return). ## auto - [Follow Graph](/auto/account-follows.md): Follow graph condition sources for Auto queries — new followers, new follows, and convergence across a watched set, with routing, methods, coverage limits, and examples. - [Agent Quickstart](/auto/agent-quickstart.md): Deterministic Auto integration flow for agents, including auth setup, endpoint order, and manifest-driven routing. - [Agent Runner](/auto/agent-runner.md): Reference architecture for background post-trigger orchestration, idempotency, and local/cloud runner deployment. - [API Key Auth](/auto/api-key-auth.md): Use API keys with /v2/auto. - [Capabilities](/auto/capabilities.md): Supported Auto workflows, substitution strategies, and builder-first patterns for agent implementations. - [Catalyst Triggers](/auto/catalyst-triggers.md): Fire an alert on an equity, index, or commodity perp when a real-world catalyst moves — a rate decision, an inflation print, an earnings beat, a headline. - [Events](/auto/events.md): Event conditions for Auto queries — trigger on news about an asset, project, company, person, or macro, with filters, optional text verification, entity routing, runtime semantics, the trigger payload, and examples. - [Funding and Liquidations](/auto/funding-and-liquidations.md): Funding-rate and liquidation-window condition sources: methods, venues, composite tickers, and feed-quality caveats. - [Notifications](/auto/notifications.md): Webhook, Telegram, and SSE delivery patterns with canonical event contracts and signature verification. - [Auto](/auto/overview.md): Auto overview, capability scope, and access-model choice between API key and x402. - [Prediction Markets](/auto/prediction-markets.md): Trigger Auto conditions on Kalshi and Polymarket prediction markets — trade prints, quotes, and lifecycle — with full method/operator/enum reference and example automations. - [Query Model and Templates](/auto/query-model.md): Canonical Auto query schema, action types, expiry guidance, and validated copy/paste query templates. - [Cancel Query](/auto/reference/rest/cancel-query.md): Cancel an active query. - [Builder Chat](/auto/reference/rest/chat.md): Ask the builder AI to draft an EQL query. - [Convert Query Draft](/auto/reference/rest/convert-query-draft.md): Turn a draft into an active query. - [Create Query](/auto/reference/rest/create-query.md): Create and activate a query. - [Delete Query](/auto/reference/rest/delete-query.md): Delete a query that has finished. - [Delete Query Draft](/auto/reference/rest/delete-query-draft.md): Delete a query draft. - [Elfa Api](/auto/reference/rest/elfa-api.md): API documentation for Elfa - [Get Execution](/auto/reference/rest/get-execution.md): One execution record. - [Get Query Draft](/auto/reference/rest/get-query-draft.md): One query draft. - [LLM Session Details](/auto/reference/rest/get-session.md): One LLM session's full analysis output. - [List Executions](/auto/reference/rest/list-executions.md): List execution records. - [List Queries](/auto/reference/rest/list-queries.md): List your queries. - [List Query Drafts](/auto/reference/rest/list-query-drafts.md): List your query drafts. - [List LLM Sessions](/auto/reference/rest/list-sessions.md): List the LLM output sessions of a query. - [Poll Query](/auto/reference/rest/poll-query.md): A query's status and its executions. - [Stream All Notifications](/auto/reference/rest/stream-queries.md): Stream notifications for all your queries over server-sent events. - [Stream Notifications](/auto/reference/rest/stream-query.md): Stream one query's notifications over server-sent events. - [Upsert Query Draft](/auto/reference/rest/upsert-query-draft.md): Create or update a query draft. - [Validate Query](/auto/reference/rest/validate-query.md): Validate an EQL query and get its cost estimate without creating it. - [Validate Query Draft](/auto/reference/rest/validate-query-draft.md): Validate a stored draft without converting it. - [Validate Symbol](/auto/reference/rest/validate-symbol.md): Check whether an exchange supports a symbol. - [Cancel Query](/auto/reference/x402/cancel-query.md): Cancel an active query. - [Builder Chat](/auto/reference/x402/chat.md): Ask the builder AI to draft an EQL query. - [Create Query](/auto/reference/x402/create-query.md): Create and activate a query. - [Elfa Api](/auto/reference/x402/elfa-api.md): API documentation for Elfa - [LLM Session Details](/auto/reference/x402/get-session.md): One LLM session's full analysis output. - [List LLM Sessions](/auto/reference/x402/list-sessions.md): List the LLM output sessions of a query. - [Poll Query](/auto/reference/x402/poll-query.md): A query's status and its executions. - [Stream Notifications](/auto/reference/x402/stream-notifications.md): Stream one query's notifications over server-sent events. - [Validate Query](/auto/reference/x402/validate-query.md): Validate an EQL query and get its cost estimate without creating it. - [SEC Filings](/auto/sec-filings.md): SEC filing condition source for Auto queries, including CIK routing, methods, operators, repeat semantics, and examples. - [Signal Triggers](/auto/signal.md): Signal category reference for X/Twitter Post and Telegram Channel triggers — posts from a specific account or channel — with condition contracts, authoring guidance, and when to use the Events trigger instead. - [Symbols](/auto/symbols.md): How symbol identifiers work for Auto tracking and market-data conditions. - [Triggers (Conditions + Indicators)](/auto/triggers.md): Trigger condition model, supported sources/operators, TA args contract, and validation troubleshooting. - [x402 (Auto)](/auto/x402.md): x402 keyless Auto integration, agent-secret identity model, pricing, and endpoint references. ## changelog - [Changelog](/changelog.md): Versioned Elfa API changes, including endpoint additions, behavior updates, and deprecations. ## get-started - [Agent Quickstart](/get-started/agent-quickstart.md): High-signal setup path for AI agents using Elfa docs, skills, endpoint metadata, and product-specific workflows. - [Authentication](/get-started/authentication.md): How to authenticate to API v3, API v2 (/v2 and /v2/auto) and the keyless x402 routes, and which keys can call v3. - [Error Responses](/get-started/errors.md): The three response bodies the Elfa API uses to report failure, the codes each one carries, and which failures are worth retrying. - [Pricing](/get-started/pricing.md): API plans, rate limits, credits, Auto query costs, and widget pricing. - [Quickstart](/get-started/quickstart.md): Resolve an entity, read its last day of events, then check how accounts are positioned on it with API v3. - [Rate Limits](/get-started/rate-limits.md): API key, v3, x402, monthly credit, and retry guidance for Elfa API integrations. - [x402 Payments (Pay-Per-Request)](/get-started/x402.md): How to call Elfa endpoints with x402 pay-per-request USDC payments, including pricing and client setup. ## guides - [Alerts with Auto](/guides/alerts-with-auto.md): Turn a GET /v3/events query into an Auto events condition, so you are told when a new event matches instead of polling for it. - [Agent Playbooks](/guides/v2-agent-playbooks.md): Endpoint chains agents can use to turn Elfa market intelligence into higher-level workflows. - [Workflows](/guides/v3-workflows.md): End-to-end API v3 recipes: a view of one asset, a daily market brief, polling for new events, following a storyline, researching a topic, checking how an account's calls ended, and spotting new contracts. ## tools - [Code Examples](/tools/code-examples.md): Practical JavaScript, Python, and cURL examples for common Elfa API calls, pagination, and error handling. - [MCP](/tools/mcp.md): Connect Claude, ChatGPT, Claude Code, Codex, Cursor and other MCP clients to Elfa social intelligence, API v3 and the Auto condition engine: sign in to the hosted server, or run it locally with an API key. - [SDKs](/tools/sdks.md): Official Elfa SDKs for TypeScript and Python — typed clients for API v3, social intelligence, AI chat, and the Auto condition engine, with retries and streaming built in. ## widget - [Headless API Reference Beta](/widget/headless-api-reference.md): Every /widget-api/v1 endpoint — key introspection, chat, Auto, feed, search, workspace, and markets — with required feature flags and notable parameters. - [Headless Quickstart Beta](/widget/headless-quickstart.md): Authenticate to the Headless Widget API with a widget key + inline end-user context, send your first chat stream request, and handle the error contract. - [Widget Beta](/widget/overview.md): The Elfa Widget: drop-in hosted chat via iframe embed, or the enterprise Headless Widget API for building your own UI on Elfa's chat, Auto, feed, and workspace runtime. ## Optional - [Elfa Developer Portal](https://go.elfa.ai/dev): Sign up and manage your API keys - [Elfa Agent Skill](https://github.com/elfa-ai/skills): Install agent-ready Elfa integration guidance - [OpenAPI Spec](/swagger/swagger.json): Machine-readable REST API schema - [Endpoint Manifest](/agent/endpoints.manifest.json): Agent-oriented endpoint metadata generated from the OpenAPI spec