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

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)	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 (Base/USDC)

Resources

• x402 Protocol Specification
• x402 GitHub Repository
• xpay Facilitator