x402 Payments (Pay-Per-Request)

Elfa API supports keyless, pay-per-request access via the x402 protocol. Any wallet can call any Elfa endpoint — no API key, no subscription, no registration. Payment is in USDC on Base and is verified and settled per-request.

This is ideal for AI agents making autonomous API calls.

caution

x402 payment access is currently in beta. Endpoints are available at the /x402/v2/ prefix.

How It Works

x402 uses the HTTP 402 Payment Required status code for machine-to-machine payments:

1. Request — Send a normal HTTP request to an /x402/v2/ endpoint (no API key needed)
2. 402 Response — The server responds with payment requirements (price, network, recipient)
3. Sign — Your wallet signs a USDC transfer authorization (no gas required)
4. Retry — Resend the request with the signed payment in the PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1) header
5. Verify & Serve — The server verifies payment, serves the response, and settles on-chain

Funds flow directly from your wallet to Elfa's treasury. The facilitator is non-custodial.

Base URL

All x402 endpoints are served under the /x402/v2/ prefix:

https://api.elfa.ai/x402/v2/

These mirror the standard /v2/ endpoints but accept x402 payment instead of an API key.

Pricing

Standard Endpoints

Endpoint	Credits	USDC Cost
/aggregations/trending-tokens	1	$0.009
/account/smart-stats	1	$0.009
/data/keyword-mentions	1	$0.009
/data/token-news	1	$0.009
/data/top-mentions	1	$0.009
/aggregations/trending-cas/twitter	1	$0.009
/aggregations/trending-cas/telegram	1	$0.009
/data/event-summary	5	$0.045
/data/trending-narratives	5	$0.045

Chat Endpoint

The /chat and /auto/chat endpoints use speed-based pricing:

Speed Mode	USDC Cost
fast	$0.225
expert (default)	$1.00

To avoid confusion:

• /x402/v2/chat is speed-based (table above).
• /x402/v2/auto/chat (Auto Builder chat) is also speed-based (fast $0.225, expert $1.00).

Quick Start

Using @x402/fetch (Recommended)

The easiest way to interact with x402 endpoints is with the @x402/fetch client, which automatically handles the 402 payment flow.

npm install @x402/fetch @x402/evm @x402/core viem

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";

// Create a signer from your private key
const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const publicClient = createPublicClient({ chain: base, transport: http() });
const signer = toClientEvmSigner(account, publicClient);

// Create an x402 client with the EVM exact scheme for Base
const client = new x402Client().register(
  "eip155:8453",
  new ExactEvmScheme(signer)
);

// Wrap fetch — payment is handled automatically on 402 responses
const x402Fetch = wrapFetchWithPayment(fetch, client);

// Make a request
const response = await x402Fetch(
  "https://api.elfa.ai/x402/v2/aggregations/trending-tokens?timeWindow=24h"
);
const data = await response.json();
console.log("Trending tokens:", data);

Using @x402/axios

npm install @x402/axios @x402/evm @x402/core viem

import { wrapAxiosWithPayment } from "@x402/axios";
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";
import axios from "axios";

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 x402Axios = wrapAxiosWithPayment(axios, client);

const { data } = await x402Axios.get(
  "https://api.elfa.ai/x402/v2/data/keyword-mentions",
  { params: { keywords: "bitcoin", timeWindow: "24h" } }
);

Chat Example

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",
    }),
  }
);
const data = await response.json();
console.log(data.data.message);

Manual Flow (cURL)

If you prefer to handle the 402 flow manually:

# Step 1: Send request without payment — get 402 with requirements
curl -s https://api.elfa.ai/x402/v2/aggregations/trending-tokens

# Step 2: Sign the payment requirements with your wallet
# (use @x402/core or @x402/evm to create the payment payload)

# Step 3: Resend with payment header
curl -s https://api.elfa.ai/x402/v2/aggregations/trending-tokens \
  -H "PAYMENT-SIGNATURE: <base64-encoded-payment-payload>"

Payment Details

Property	Value
Network	Base (eip155:8453)
Asset	USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
Scheme	exact (fixed price per request)
Facilitator	xpay.sh

x402 vs API Key

	API Key	x402
Setup	Register, get key	None — just a wallet
Auth	x-elfa-api-key header	PAYMENT-SIGNATURE or X-PAYMENT header
Billing	Monthly credits or PAYG	Per-request USDC
Identity	API key	Wallet address
Rate Limit	Per API key (60-120 RPM)	Per wallet address
Best For	Apps, dashboards	AI agents, bots

Both access modes are independent. x402 does not consume API key credits.

Client Libraries

Package	Description
@x402/fetch	Drop-in fetch wrapper (auto-handles 402)
@x402/axios	Axios interceptor
@x402/core	Core protocol types and utilities
@x402/evm	EVM payment signing (Base/USDC)

Resources

• x402 Protocol Specification
• x402 GitHub Repository
• xpay Facilitator