Claude AI Trading Skill

Elfa API Skill

This skill enables Claude to work with the Elfa API — a social listening and market context layer for crypto traders. Elfa ingests real-time data from Twitter/X, Telegram, and other sources, then structures sentiment, narratives, and attention shifts into actionable trading insights.

When to use this skill

API Overview

Base URL: https://api.elfa.ai Version: v2 (current)

Two access modes

Elfa supports two independent ways to authenticate requests:

| Mode | Endpoint prefix | Auth header | Best for | |---|---|---|---| | API key | /v2/ | x-elfa-api-key: YOUR_KEY | Humans & apps with a registered key | | x402 (keyless) | /x402/v2/ | X-PAYMENT: | Agents & wallets — no signup needed |

Both modes access the same data. The only difference is how you authenticate:

Endpoints at a glance

All endpoints below work with both /v2/ (API key) and /x402/v2/ (keyless) prefixes, except key-status which is API key mode only.

| Endpoint | Method | Description | |---|---|---| | /v2/key-status | GET | API key usage & limits (API key mode only) | | /v2/aggregations/trending-tokens | GET | Trending tokens by mention count | | /v2/account/smart-stats | GET | Smart follower & engagement stats for a Twitter account | | /v2/data/top-mentions | GET | Top mentions for a ticker symbol | | /v2/data/keyword-mentions | GET | Search mentions by keywords or account name | | /v2/data/event-summary | GET | AI event summaries from keyword mentions (5 credits) | | /v2/data/trending-narratives | GET | Trending narrative clusters (5 credits) | | /v2/data/token-news | GET | Token-related news mentions | | /v2/aggregations/trending-cas/twitter | GET | Trending contract addresses on Twitter | | /v2/aggregations/trending-cas/telegram | GET | Trending contract addresses on Telegram | | /v2/chat | POST | AI chat with multiple analysis modes |

For full parameter details, read references/api-reference.md.

How to use this skill

Step 1: Determine the mode

Check whether the user wants to make a live call or get code/integration help.

Step 2a: Making live API calls (API key mode)

Use the bash_tool to call the Elfa API via curl.

Getting the API key: 1. Check if the ELFA_API_KEY environment variable is set. This is the preferred method. 2. If the env var is not set, stop and prompt the user. Offer both options:

> To make live calls, you have two options: > > Option A — API key (free tier): Get a free key with 1,000 credits at > https://go.elfa.ai/claude-skills — then set it as the ELFA_API_KEY environment > variable (do not paste it directly into the chat). > > Option B — x402 keyless payments: Pay per request with USDC on Base — no signup > needed. See the x402 docs for setup.

Do not attempt any authenticated API calls without a key or x402 setup. Wait for the user. 3. Credential safety: - Always read the API key from the ELFA_API_KEY environment variable, never ask the user to paste it into the conversation. - Never log or expose the full API key in outputs — mask it when displaying curl commands. - If a user does paste a key in chat, warn them to rotate it and set it as an env var instead.

Free tier limitations: The free tier provides 1,000 credits that work on most endpoints. However, the following endpoints require a Pay-As-You-Go or Grow plan:

If a user hits an authorization error on one of these endpoints, let them know they can upgrade their plan or use x402 payments instead. Full details at https://go.elfa.ai/claude-skills.

Making the call:

curl -s -H "x-elfa-api-key: $ELFA_API_KEY" "https://api.elfa.ai/v2/aggregations/trending-tokens?timeWindow=24h&pageSize=10"

Step 2b: Making live API calls (x402 keyless mode)

x402 lets any wallet pay per request using USDC on Base — no API key, no registration. This is ideal for agents, bots, and programmatic access.

How x402 works: 1. Send a request to the /x402/v2/ version of any endpoint (no auth header). 2. The server responds with HTTP 402 containing payment requirements. 3. Your wallet signs a USDC transfer authorization (no gas fees). 4. Resend the request with the signed payment in the X-PAYMENT header. 5. Server verifies payment, serves the response, and settles on-chain.

x402 signing and security:

x402 details:

x402 pricing: | Tier | Cost | Endpoints | |---|---|---| | Standard (1 credit) | $0.009 | trending-tokens, smart-stats, keyword-mentions, token-news, top-mentions, trending-cas | | Extended (5 credits) | $0.045 | event-summary, trending-narratives | | Chat — fast | $0.225 | chat (speed: "fast") | | Chat — expert | $1.00 | chat (speed: "expert", default) |

Making an x402 call with curl (manual flow):

# Step 1: Send request without payment — get 402 with payment requirements
curl -s https://api.elfa.ai/x402/v2/aggregations/trending-tokens?timeWindow=24h
Step 2: After signing the payment payload with your wallet, resend with X-PAYMENT header
curl -s -H "X-PAYMENT: " \
  "https://api.elfa.ai/x402/v2/aggregations/trending-tokens?timeWindow=24h"

Recommended: use the @x402/fetch library which handles payment automatically:

import { wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
import { x402Client } from "@x402/core/client";
import { createPublicClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";
const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const publicClient = createPublicClient({ chain: base, transport: http() });
const signer = toClientEvmSigner(account, publicClient);
const client = new x402Client().register(
  "eip155:8453",
  new ExactEvmScheme(signer));
const x402Fetch = wrapFetchWithPayment(fetch, client);
// Use x402Fetch exactly like regular fetch — payment is handled automatically on 402 responses
const response = await x402Fetch(
  "https://api.elfa.ai/x402/v2/aggregations/trending-tokens?timeWindow=24h");
const data = await response.json();

x402 with the Chat endpoint (POST):

const response = await x402Fetch(
  "https://api.elfa.ai/x402/v2/chat",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      message: "What is the current sentiment on BTC?",
      analysisType: "chat",
      speed: "fast", // "fast" = $0.225, "expert" = $1.00
    }),
  });
const data = await response.json();
console.log(data.data.message);

Presenting results:

Step 3: Generating code snippets

When the user wants integration help, generate correct, production-ready code. Read references/api-reference.md for the full parameter specs.

Principles for code generation:

Language priorities (use unless the user specifies otherwise): 1. TypeScript/JavaScript (fetch) — most Elfa integrators are web/Node devs 2. Python (requests) 3. curl

The Chat endpoint deserves special attention — it's the most complex:

Common patterns

Time window parameters: Many endpoints accept either timeWindow (e.g., "30m", "1h", "4h", "24h", "7d", "30d") OR from/to unix timestamps. If both are provided, from/to takes priority.

Pagination: Most list endpoints support page and pageSize. The keyword-mentions endpoint uses cursor-based pagination instead (cursor parameter).

Ticker format: For top-mentions, the ticker param can be prefixed with $ to match only cashtags (e.g., $SOL vs SOL).

Credit costs (both modes):

Important notes

Troubleshooting

CORS or network errors in the Claude desktop app: If the user is running this skill in the Claude desktop app and API calls are failing due to CORS or network issues, guide them through this fix:

1. Open Settings in the Claude desktop app 2. Go to Capabilities 3. Enable Network Egress 4. Add *.elfa.ai to the allowed domains list

This grants the app permission to make outbound requests to the Elfa API.

CORS or network errors in the Claude desktop app: If the user is running this skill in the Claude desktop app and API calls are failing due to CORS or network issues, guide them through this fix:

1. Open Settings in the Claude desktop app 2. Go to Capabilities 3. Enable Network Egress 4. Add *.elfa.ai to the allowed domains list

This grants the app permission to make outbound requests to the Elfa API.