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, Arbitrum, Polygon, Avalanche, or Solana 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, accepted networks, 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 endpoint uses speed-based pricing:

Speed Mode	Credits	USDC Cost
fast	5	$0.045
expert (default)	18	$0.162

To avoid confusion:

• /x402/v2/chat is speed-based (table above).
• Auto-specific x402 pricing is documented on x402 (Auto).

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

To pay on another network, swap the base chain and eip155:8453 for a supported one — e.g. Arbitrum (arbitrum, eip155:42161). Register a scheme for each network you want to pay from; the client uses the first one the server also accepts. See Supported Networks.

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
Scheme	exact (fixed price per request)
Asset	Native USDC on the selected network

Supported Networks

The server offers every supported network in the 402 response; your client signs on the first one it's registered for. Register the network(s) you hold USDC on.

Network	Chain ID	USDC Address	Facilitator
Base	eip155:8453	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	xpay.sh, payai.network
Arbitrum	eip155:42161	0xaf88d065e77c8cC2239327C5EDb3A432268e5831	payai.network
Polygon	eip155:137	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359	payai.network
Avalanche	eip155:43114	0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E	payai.network
Solana	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v	payai.network

All are native Circle USDC (6 decimals). Facilitators are non-custodial.

EVM networks use CAIP-2 eip155:* chain IDs; Solana uses the CAIP-2 solana:* identifier with a base58 USDC mint. To pay from Solana, sign with @x402/svm instead of @x402/evm — the facilitator acts as the transaction fee payer, so you don't need SOL for gas.

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)	1,000 RPM baseline (currently per client IP)
Best For	Apps, dashboards	AI agents, bots

Both access modes are independent. x402 does not consume API key credits. See x402 Rate Limits for implementation details.

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 (USDC on Base, Arbitrum, Polygon, Avalanche)
@x402/svm	Solana payment signing (USDC on Solana)

Resources

• x402 Protocol Specification
• x402 GitHub Repository
• xpay Facilitator
• PayAI Facilitator