feat: add Elfa AI provider (Auto condition engine + Iris market intelligence, x402)

[nero-sensei]

Adds Elfa AI (elfa-ai/api).

Elfa is real-time data infrastructure for financial AI, powered by our intelligence stack Iris. Iris synthesises signals across social, on-chain and off-chain market data, then traces their second and third-order effects, so agents act on greater context.

These endpoints serve the same signals our own finance agent runs on, pay-per-call over x402 — no API key and no account. We run them ourselves at https://api.elfa.ai, no gateway in front.

Auto — the condition engine

The part we expect agents to reach for most. Describe what to watch and Elfa fires a webhook when it happens: register an EQL query against price or social conditions, and it is evaluated continuously. Identity is SHA256(x-elfa-agent-secret), so an agent invents a secret once and reuses it to reach its own queries.

Creating a query is the only paid step — validating, polling, cancelling, listing LLM sessions and the SSE notification stream are free.

Iris market intelligence

Point-in-time reads of what the market is saying and doing: trending assets and contract addresses surfacing on X and Telegram, smart-account stats, keyword mention feeds, token news, event summaries and narratives, plus an LLM chat endpoint that interprets them.

Payment

• USDC on Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp), plus Base, Arbitrum, Polygon and Avalanche — every rail is quoted in the same 402, so the caller pays on whichever they already hold.
• Solana payments are gasless; the facilitator acts as fee payer.
• x402 v2, exact scheme, challenge in the PAYMENT-REQUIRED header.

Endpoints

18 total — twelve paid, six free.

Price	Endpoints
$0.09 / $0.207	Auto query creation, by speed
free	Auto validate, poll, cancel, list sessions, session detail, SSE stream
$0.045 / $0.162	LLM chat and Auto builder chat, by speed
$0.045	event summary, trending narratives
$0.009	trending tokens, trending contract addresses (X / Telegram), smart-account stats, keyword mentions, token news, top mentions

Notes for reviewers

Auto query pricing is dynamic. POST /x402/v2/auto/queries costs a $0.045 baseline plus each simulated LLM call the query needs ($0.045 fast, $0.162 expert). The listed variants describe the common single-call case rather than a floor or ceiling. PAY.md says so and points callers at the free validate endpoint, which returns the exact cost before anything is created. Happy to express this differently if you would rather see the baseline advertised.

The six free Auto endpoints carry explicit price_usd: 0 variants. They are identity-scoped on an x-elfa-agent-secret header, so an unauthenticated probe cannot classify them. The zero-priced variants are what let them publish honestly instead of being dropped.

The spec is generated, not hand-maintained. openapi.json is produced from the same price table our payment middleware charges from, so the advertised price cannot drift from what we bill. Refreshing it is a single command on our side.

Checks

pay catalog check . --changed-from origin/main
│ Changed providers check successful
│ 18 endpoints tested across 1 provider
│ 11/11 gates compatible with Solana

pay catalog check providers/elfa/api/PAY.md --strict is also clean, with zero static warnings.

[greptile-apps]

Greptile Summary

The PR adds the native elfa-ai/api provider with an OpenAPI-backed catalog entry for Iris market intelligence and the Auto condition engine.

• Publishes 18 paid and free x402 operations for market data, chat, query lifecycle management, and SSE notifications.
• Documents Solana-compatible payment support, dynamic query pricing, identity-scoped Auto operations, and spend-aware usage.
• Adds request/response schemas, examples, and metering metadata used by catalog consumers.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete changed-code defect established in the provider metadata or generated API contract.

The provider layout and frontmatter follow registry conventions, paid and free operations are consistently documented, and the reported catalog checks cover all 18 added endpoints without an accepted runtime, publication, or security failure.

Important Files Changed

Filename	Overview
providers/elfa-ai/api/PAY.md	Adds valid provider metadata and concise operational guidance for Auto, Iris, payment rails, and spend-aware use.
providers/elfa-ai/api/openapi.json	Adds the generated 18-operation OpenAPI contract with request and response schemas, examples, and paid or zero-price metering variants.

Sequence Diagram

sequenceDiagram
  participant Agent
  participant Elfa as Elfa AI API
  participant Webhook as Agent Webhook
  Agent->>Elfa: Validate EQL query (free)
  Elfa-->>Agent: Validation result and exact cost
  Agent->>Elfa: Create query (x402 payment)
  Elfa-->>Agent: Query ID and active status
  loop Query lifecycle
    Agent->>Elfa: Poll status or open SSE stream (free)
    Elfa-->>Agent: Status and notifications
  end
  Elfa->>Webhook: Fire configured action when condition matches
  Agent->>Elfa: Cancel query (free)

Loading

_{Reviews (1): Last reviewed commit: "feat: add Elfa AI provider (Auto conditi..." | Re-trigger Greptile}