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)

## agent-quickstart

- [Agent Quickstart](/agent-quickstart.md): High-signal setup path for AI agents using Elfa docs, skills, endpoint metadata, and product-specific workflows.

## api

- [Elfa Market Events](/api/beta/elfa-market-events.md): Documentation-only OpenAPI source for Market Events.
- [Market events New](/api/beta/get-market-events-v-2.md): Market Events is Elfa's proprietary stream of emerging narratives and events across financial markets.
- [API Reference](/api/endpoints.md): Every Elfa REST endpoint at a glance: the new API v3, then API v2 with its keyed and x402 pay-per-request surfaces, grouped by resource.
- [Arcs](/api/rest/arcs-list-v-3.md): Storylines belonging to the same larger movement, with a summary and every storyline
- [Cancel Query](/api/rest/auto-cancel-query-v-2.md): Cancel an active query.
- [Builder Chat](/api/rest/auto-chat-v-2.md): Ask the AI to help you build an EQL query.
- [Convert Query Draft](/api/rest/auto-convert-query-draft-v-2.md): Convert a draft into an active query.
- [Create Query](/api/rest/auto-create-query-v-2.md): Create and activate a conditional query.
- [Delete Query Draft](/api/rest/auto-delete-query-draft-v-2.md): Delete a query draft.
- [Delete Query](/api/rest/auto-delete-query-v-2.md): Delete a terminal query.
- [Get Execution](/api/rest/auto-get-execution-v-2.md): Get a single execution record.
- [Get Query Draft](/api/rest/auto-get-query-draft-v-2.md): Get a specific query draft (legacy; prefer GET /queries/{queryId} which resolves query or draft).
- [LLM Session Details](/api/rest/auto-get-session-v-2.md): Get full LLM analysis output for a specific session.
- [List Executions](/api/rest/auto-list-executions-v-2.md): List execution records.
- [List Queries](/api/rest/auto-list-queries-v-2.md): List Auto queries for the authenticated API-key user.
- [List Query Drafts](/api/rest/auto-list-query-drafts-v-2.md): List editable query drafts.
- [List LLM Sessions](/api/rest/auto-list-sessions-v-2.md): List LLM output sessions for a query.
- [Poll Query](/api/rest/auto-poll-query-v-2.md): Check query status and execution results.
- [Stream All Notifications](/api/rest/auto-stream-queries-v-2.md): Stream notifications for **all** of your queries over a single connection (SSE).
- [Stream Notifications](/api/rest/auto-stream-query-v-2.md): Stream notifications for a single query via Server-Sent Events (SSE).
- [Upsert Query Draft](/api/rest/auto-upsert-query-draft-v-2.md): Create or update a query draft.
- [Validate Query Draft](/api/rest/auto-validate-query-draft-v-2.md): Validate a stored query draft without converting it.
- [Validate Query](/api/rest/auto-validate-query-v-2.md): Validate EQL syntax and get a cost estimate without creating a query.
- [Validate Symbol](/api/rest/auto-validate-symbol-v-2.md): Check whether a symbol is supported on the given exchange.
- [Crypto call book](/api/rest/call-book-crypto-v-3.md): How the accounts we follow are positioned in crypto, hour by hour. `longShare` is how
- [Equity call book](/api/rest/call-book-equity-v-3.md): The same book over equities. Same shape as `GET /v3/market/crypto/call-book`.
- [Call episodes](/api/rest/call-episodes-list-v-3.md): One account's position on one asset, from the call that opened it to whatever closed
- [Calls](/api/rest/calls-list-v-3.md): Every call: one post that opened, added to, trimmed, reaffirmed, reversed, closed or
- [AI chat stream](/api/rest/chat-stream-v-2.md): Stream a response from Elfa AI using Server-Sent Events (SSE).
- [AI chat](/api/rest/chat-v-2.md): Send a message to the Elfa AI and receive a complete response.
- [Elfa Api](/api/rest/elfa-api.md): API documentation for Elfa
- [Entities](/api/rest/entities-list-v-3.md): Turns what a caller holds into the id every other v3 endpoint takes. Asset results
- [Events](/api/rest/events-list-v-3.md): What happened, to what, and when. Newest first, with a cursor. Filter with
- [Smart stats of accounts (legacy, removed 28 Oct 2026)](/api/rest/get-account-smart-stats-v-2.md): Retrieve smart stats given username
- [API key status](/api/rest/get-api-key-status-v-2.md): Retrieve the current status and usage of your API key
- [Event summary from keyword mentions (5 credits total)](/api/rest/get-event-summary-v-2.md): Generate event summaries based on keyword mentions within a time period.
- [Multi keyword mentions search](/api/rest/get-keyword-mentions-v-2.md): Search mentions by keywords OR account name within a time period. Either
- [Token news mentions (tweet source only)](/api/rest/get-token-news-v-2.md): Retrieve token-related news mentions.
- [Top mentions](/api/rest/get-top-mentions-v-2.md): Returns the most significant mentions for a given ticker symbol, ranked by
- [Trending contract addresses on Telegram](/api/rest/get-trending-c-as-telegram-v-2.md): Get trending contract addresses mentioned on Telegram. Returns contract addresses with mention counts.
- [Trending contract addresses on Twitter](/api/rest/get-trending-c-as-twitter-v-2.md): Get trending contract addresses mentioned on Twitter/X. Returns contract addresses with mention counts.
- [Trending narratives (5 credits total)](/api/rest/get-trending-narratives-v-2.md): Get trending narratives based on Twitter mentions analysis.
- [Trending tokens](/api/rest/get-trending-tokens-v-2.md): This experimental endpoint is under active development and its behavior may change without notice.
- [Key status](/api/rest/key-status-v-3.md): What this key can do: its plan, scopes, credits, and how far back its plan reaches.
- [Crypto mindshare](/api/rest/mindshare-crypto-v-3.md): Crypto assets ranked by share of attention over a period, weighted by who posted.
- [Equity mindshare](/api/rest/mindshare-equity-v-3.md): The same board over equities.
- [Health check endpoint](/api/rest/ping-v-2.md): Simple health check to verify API availability
- [Positioning](/api/rest/positioning-v-3.md): How the open episodes on one asset are split, right now. A count of the accounts long
- [Storylines](/api/rest/storylines-list-v-3.md): What is developing over time. A storyline is many events, carries its summary and
- [Top accounts](/api/rest/top-accounts-v-3.md): Who to watch, ranked by standing: how much other accounts reply to, quote and repost
- [Trending contracts](/api/rest/trending-contracts-v-3.md): Contract addresses being pasted on X and Telegram, counted together, named where
- [v2 Account](/api/rest/v-2-account.md): v2 Account
- [v2 Aggregations](/api/rest/v-2-aggregations.md): v2 Aggregations
- [v2 Auto](/api/rest/v-2-auto.md): v2 Auto
- [v2 Chat](/api/rest/v-2-chat.md): v2 Chat
- [v2 Data](/api/rest/v-2-data.md): v2 Data
- [v2 System](/api/rest/v-2-system.md): v2 System
- [x402 Account](/api/rest/x-402-account.md): x402 Account
- [x402 Aggregations](/api/rest/x-402-aggregations.md): x402 Aggregations
- [x402 Auto](/api/rest/x-402-auto.md): x402 Auto
- [Cancel Query](/api/rest/x-402-auto-cancel-query.md): Cancel an active query.
- [Builder Chat](/api/rest/x-402-auto-chat.md): 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.
- [Create Query](/api/rest/x-402-auto-create-query.md): Create and activate a conditional query that monitors market data and triggers actions when conditions are met.
- [LLM Session Details](/api/rest/x-402-auto-get-session.md): Get full LLM analysis output for a specific session, including conversation messages and analysis details.
- [List LLM Sessions](/api/rest/x-402-auto-list-sessions.md): List LLM output sessions for a query.
- [Poll Query](/api/rest/x-402-auto-poll-query.md): Check query status and execution results.
- [Stream Notifications](/api/rest/x-402-auto-stream-notifications.md): Stream query notifications via Server-Sent Events (SSE).
- [Validate Query](/api/rest/x-402-auto-validate-query.md): Validate EQL syntax and get a cost estimate without creating a query.
- [x402 Chat](/api/rest/x-402-chat.md): x402 Chat
- [AI chat](/api/rest/x-402-chat-v-2.md): Send a message to the Elfa AI and receive a complete response.
- [x402 Data](/api/rest/x-402-data.md): x402 Data
- [Smart stats of accounts (legacy, removed 28 Oct 2026)](/api/rest/x-402-get-account-smart-stats-v-2.md): Retrieve smart stats given username
- [Event summary from keyword mentions (5 credits total)](/api/rest/x-402-get-event-summary-v-2.md): Generate event summaries based on keyword mentions within a time period.
- [Multi keyword mentions search](/api/rest/x-402-get-keyword-mentions-v-2.md): Search mentions by keywords OR account name within a time period. Either
- [Token news mentions (tweet source only)](/api/rest/x-402-get-token-news-v-2.md): Retrieve token-related news mentions.
- [Top mentions](/api/rest/x-402-get-top-mentions-v-2.md): Returns the most significant mentions for a given ticker symbol, ranked by
- [Trending contract addresses on Telegram](/api/rest/x-402-get-trending-cas-telegram-v-2.md): Get trending contract addresses mentioned on Telegram. Returns contract addresses with mention counts.
- [Trending contract addresses on Twitter](/api/rest/x-402-get-trending-cas-twitter-v-2.md): Get trending contract addresses mentioned on Twitter/X. Returns contract addresses with mention counts.
- [Trending narratives (5 credits total)](/api/rest/x-402-get-trending-narratives-v-2.md): Get trending narratives based on Twitter mentions analysis.
- [Trending tokens](/api/rest/x-402-get-trending-tokens-v-2.md): This experimental endpoint is under active development and its behavior may change without notice.

## authentication

- [Authentication](/authentication.md): Authentication requirements for /v2, /v2/auto, and /x402/v2 routes, including API key and payment headers.

## 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.
- [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.
- [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, Telegram Channel, and Event triggers, including condition contracts and authoring guidance.
- [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.

## code-examples

- [Code Examples](/code-examples.md): Practical JavaScript, Python, and cURL examples for common Elfa API calls, pagination, and error handling.

## errors

- [Error Responses](/errors.md): The three response bodies the Elfa API uses to report failure, the codes each one carries, and which failures are worth retrying.

## market-intelligence

- [Agent Playbooks](/market-intelligence/agent-playbooks.md): Endpoint chains agents can use to turn Elfa market intelligence into higher-level workflows.
- [Chat](/market-intelligence/chat.md): Use Elfa Chat when agents or developers need written market interpretation instead of raw metrics.
- [Discovery](/market-intelligence/discovery.md): Use trending token and contract-address endpoints to find what is moving before building a watchlist.
- [Mentions and Accounts](/market-intelligence/mentions-accounts.md): Use mention and smart-account endpoints to evaluate attention quality, amplification, and account reach.
- [News and Narratives](/market-intelligence/news-narratives.md): Use token news, event summaries, and trending narratives to attach causes and themes to market moves.
- [Market Intelligence](/market-intelligence/overview.md): How to use Elfa market intelligence endpoints for attention measurement, interpretation, and agent workflows.

## mcp

- [MCP](/mcp.md): Connect Claude, ChatGPT, Claude Code, Codex, Cursor and other MCP clients to Elfa social intelligence and the Auto condition engine: sign in to the hosted server, or run it locally with an API key.

## pricing

- [Pricing](/pricing.md): API plans, rate limits, credits, Auto query costs, and widget pricing.

## rate-limits

- [Rate Limits](/rate-limits.md): API key, x402, monthly credit, and retry guidance for Elfa API integrations.

## sdks

- [SDKs](/sdks.md): Official Elfa SDKs for TypeScript and Python — typed clients for social intelligence, AI chat, and the Auto condition engine, with retries and streaming built in.

## v3

- [Calls, Call Episodes and Positioning](/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](/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.
- [Entities](/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.
- [Events, Storylines and Arcs](/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](/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](/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](/v3/people.md): Who is worth reading: accounts ranked by standing, how much other accounts engage with them.
- [Field Reference](/v3/reference.md): Every enum value and every error status API v3 returns, with what each one means and what to do next.
- [Workflows](/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.

## 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.

## x402-payments

- [x402 Payments (Pay-Per-Request)](/x402-payments.md): How to call Elfa endpoints with x402 pay-per-request USDC payments, including pricing and client setup.

## x402-rate-limits

- [x402 Rate Limits and Usage Controls](/x402-rate-limits.md): Current x402 request limits, limiter scope, and retry/backoff guidance for high-volume clients.

## 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