SDKs

The TypeScript and Python clients cover the same surface — social intelligence data, chat (including SSE streaming), and the Auto condition engine — with typed responses and retries handled for you. If your agent has a shell, the Agent Skill is the lighter surface; if your client cannot run commands, use the MCP Server.

SDK	Package	Source
TypeScript / JavaScript	@elfa-ai/sdk	elfa-ai/elfa-sdk-js
Python	elfa-sdk	elfa-ai/elfa-sdk-python

Install

Node 22 or newer, or Python 3.9 or newer. Get a key from dev.elfa.ai.

@elfa-ai/sdk requires Node 22 from v6 onward — Node 18 and 20 have both reached end of life. On an older runtime, pin @elfa-ai/sdk@5, which talks to the same API.

npm install @elfa-ai/sdk

First Request

import { ElfaSDK } from "@elfa-ai/sdk";

const elfa = new ElfaSDK({ elfaApiKey: process.env.ELFA_API_KEY! });

const trending = await elfa.getTrendingTokens({ timeWindow: "24h" });
const mentions = await elfa.getKeywordMentions({
  keywords: "bitcoin,ethereum",
  timeWindow: "1h",
});

Python also ships AsyncElfaClient — the same surface with await, usable as an async context manager.

Methods

JavaScript	Python	Endpoint
ping()	ping()	/v2/ping
getApiKeyStatus()	get_api_key_status()	/v2/key-status
getTrendingTokens()	get_trending_tokens()	/v2/aggregations/trending-tokens
getTrendingCAsTwitter()	get_trending_cas_twitter()	/v2/aggregations/trending-cas/twitter
getTrendingCAsTelegram()	get_trending_cas_telegram()	/v2/aggregations/trending-cas/telegram
getAccountSmartStats()	get_account_smart_stats()	/v2/account/smart-stats
getKeywordMentions()	get_keyword_mentions()	/v2/data/keyword-mentions
getTopMentions()	get_top_mentions()	/v2/data/top-mentions
getTokenNews()	get_token_news()	/v2/data/token-news
getEventSummary()	get_event_summary()	/v2/data/event-summary
getTrendingNarratives()	get_trending_narratives()	/v2/data/trending-narratives
chat()	chat()	/v2/chat
chatStream()	chat_stream()	/v2/chat/stream

Time-ranged endpoints take either a time window (timeWindow / time_window, for example "24h") or an explicit range (from and to, from_time and to_time, in unix seconds). See the REST Reference for parameters and response schemas.

No raw tweet content

The SDKs return Elfa's processed data — metadata, engagement metrics, and tweet links. They do not return tweet text. Fetch the linked post through the X API with your own credentials if you need it.

Chat Streaming

The streaming methods take the same arguments as chat and yield one event per data: frame, ending on the terminating [DONE] frame. Streaming Chat requires a PAYG or Enterprise key — see Chat.

for await (const event of elfa.chatStream({ message: "Sentiment on SOL?" })) {
  if (event.type === "text") process.stdout.write(event.content);
}

Event types are session_info, title, text, text_complete, status, credits, complete, invalid_request and error.

Auto

elfa.auto and client.auto drive the Auto condition engine — EQL queries that watch markets and fire notifications. Validate first, then create, then stream or poll.

await elfa.auto.validateQuery(query);
const created = await elfa.auto.createQuery(query);

for await (const event of elfa.auto.streamQuery(created.id ?? created.queryId!)) {
  console.log(event.event, event.data);
}

Also available on both: builder chat, query list/get/cancel/delete, drafts, sessions, executions, symbol validation, and a stream of every query's notifications.

Options

JavaScript	Python	Default	Purpose
elfaApiKey	api_key	—	Required. Sent as x-elfa-api-key.
baseUrl	base_url	https://api.elfa.ai	API base URL.
timeout	timeout	30s	Per-request timeout.
retries	retries	3	Retries for idempotent requests.
retryDelay	retry_delay	1s	Base delay for exponential backoff.
headers	headers	—	Extra headers on every request.
debug	—	false	Request and response logging.

Idempotent requests are retried with exponential backoff on network errors, rate limits, and 5xx responses. Mutations are never retried automatically.

Errors

import { ElfaApiError, RateLimitError, AuthenticationError } from "@elfa-ai/sdk";

try {
  await elfa.getKeywordMentions({ keywords: "bitcoin" });
} catch (error) {
  if (error instanceof AuthenticationError) console.log("Invalid API key");
  else if (error instanceof RateLimitError) console.log("Retry at", error.resetTime);
  else if (error instanceof ElfaApiError) console.log("API error", error.statusCode);
}

Validation errors (ValidationError / ElfaValidationError) cover rejected parameters, and network errors (NetworkError / ElfaNetworkError) cover connection failures. See Rate Limits for quota behavior.

Next Step

Read Market Intelligence for what each data method returns, or Auto for the condition engine.