Base Mainnet · $0.05 per request

XFinance API Docs

Institutional-grade market intelligence delivered over a pay-per-request gateway. Every call is settled through x402, so humans and autonomous agents can access premium equity, ETF and insider data without subscriptions.

Open Swagger

Why XFinance

Agent-ready

Exposes rich metadata to the x402 Bazaar so AI agents instantly understand inputs, outputs and pricing. No key provisioning or manual onboarding.

Production hardened

100 req/min/IP rate limiting, exponential retries, async timeouts and JSON structured logs. Hooks for Sentry alerts are wired in for enterprise monitoring.

Deterministic billing

Flat $0.05 per endpoint, charged only once per 5-minute cache window. Perfect for deterministic agents that need predictable costs.

Deep coverage

33 endpoints across fundamentals, analysts, insiders, ETFs, corporate actions and discovery—consolidated behind a single paywall.

Quickstart

  1. Load any Base wallet (EVM address) with enough USDC to cover the calls you plan to make.
  2. Hit one of the documented endpoints. The first response is 402 Payment Required and contains an x402 payment object.
  3. Use an x402-capable agent, SDK or wallet to sign and submit the payment. The middleware handles verification and settlement automatically.
  4. Retry the same request. Once the facilitator confirms settlement, the live data response is returned. Cached hits within 5 minutes are free.

Need a ready-made workflow? Any client that speaks x402 (Coinbase Agent Kit, custom bots, etc.) can consume the payment payload without additional integration work.

Payment Flow

Pricing

$0.05 per paid endpoint. Health check and root stay free.

Payee: 0x7f8A1E403fF9FD25bd03Ff2e3aF806f41eA662E7

Network: Base

Facilitator

CDP facilitator via cdp-sdk with retries, structured logging and Sentry-ready hooks. Payments are verified, settled and recorded server-side with full audit trails.

Every protected path exposes metadata so the API can be discovered directly inside the x402 Bazaar.

All discoverable endpoints are listed in the x402 Bazaar API (GET /platform/v2/x402/discovery/resources).

Example Flow

Below is a condensed, human-friendly flow. Agents follow the same pattern automatically.

# 1. Initial request
GET https://api.xfinance.cc/ticker/AAPL/info
→ 402 Payment Required
→ Body contains payment instructions + resource metadata

# 2. Payment handshake
Handled automatically by your x402 client (wallet, bot or SDK) → verifies + settles with facilitator

# 3. Retry original request with X-PAYMENT header
GET https://api.xfinance.cc/ticker/AAPL/info
X-PAYMENT: eyJ2ZXJzaW9uIjoxLCJ... (signed proof)
→ 200 OK with fresh market data

The paywall handles expiry (up to 60 seconds) and prevents replay once a session is settled.

See the 402 handshake

Test the paywall directly. The first call returns the 402 payload that any x402-aware HTTP client can consume.

$ curl -i https://api.xfinance.cc/ticker/AAPL/info
HTTP/2 402
content-type: application/json
x402version: 1

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "resource": "https://api.xfinance.cc/ticker/AAPL/info",
      "payTo": "0x7f8A1E403fF9FD25bd03Ff2e3aF806f41eA662E7",
      "price": "$0.05",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxTimeoutSeconds": 60
    }
  ]
}

Use an x402-enabled HTTP stack (e.g., Coinbase Agent Kit, axios/httpx middleware) to auto-detect 402 responses, perform verify/settle, and replay the request with the generated X-PAYMENT header.

Endpoints

33 production-grade endpoints grouped in three routers. Each response is JSON, protected by rate limiting (100 req/min/IP) and enforces a 10 s upstream timeout with automatic retries.

GroupHighlightsPath
Ticker Core Quote info, history, options chain, dividends, splits. /ticker/<symbol>/*
Advanced Analytics Analyst targets, earnings/revenue estimates, EPS trend, growth forecasts. /ticker/<symbol>/<analysis>
Insiders & Holdings Insider roster, transactions, mutual funds, ETFs fund data, capital gains. /ticker/<symbol>/insider-*
Market & Search Market movers plus smart search for equities, ETFs and funds. /market/*, /search

How to Use: Step-by-Step Examples

👤 For Humans

Option 1: Python Script (Automatic Payment)

This is the easiest way. The x402 client handles payment automatically:

from eth_account import Account
from x402.clients.requests import x402_requests

# 1. Setup your wallet
account = Account.from_key("0xYOUR_PRIVATE_KEY")

# 2. Create x402-enabled session
session = x402_requests(account)

# 3. Make request - payment happens automatically!
response = session.get(
    "https://api.xfinance.cc/ticker/AAPL/info"
)

# 4. Use the data
data = response.json()
print(f"Company: {data['data']['longName']}")
print(f"Price: ${data['data']['currentPrice']}")

# Output:
# Company: Apple Inc.
# Price: $175.43

The client automatically: detects 402 → signs payment → retries request → returns data. You just call the endpoint!

Option 2: cURL (Manual Payment)

See what happens step-by-step:

# Step 1: First request (no payment)
$ curl https://api.xfinance.cc/ticker/AAPL/info

# Response: 402 Payment Required
{
  "x402Version": 1,
  "accepts": [{
    "network": "base",
    "payTo": "0x7f8A1E403fF9FD25bd03Ff2e3aF806f41eA662E7",
    "maxAmountRequired": "50000",  # 0.05 USDC
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 60
  }],
  "error": "No X-PAYMENT header provided"
}

# Step 2: Use x402 CLI or Python script to:
#   - Sign the payment object with your wallet
#   - Get X-PAYMENT header from facilitator

# Step 3: Retry with payment header
$ curl -H "X-PAYMENT: eyJ2ZXJzaW9uIjoxLCJ..." \
       https://api.xfinance.cc/ticker/AAPL/info

# Response: 200 OK
{
  "symbol": "AAPL",
  "data": {
    "longName": "Apple Inc.",
    "currentPrice": 175.43,
    "marketCap": 2700000000000,
    ...
  }
}

Option 3: Browser (Paywall UI)

Open any endpoint in your browser. If paywall UI is configured, you'll see a wallet connection prompt:

  1. Visit: https://api.xfinance.cc/ticker/AAPL/info
  2. Connect your wallet (MetaMask, Coinbase Wallet, etc.)
  3. Approve the $0.05 USDC payment
  4. Page automatically reloads with data

🤖 For AI Agents

Automatic Discovery + Usage

Agents can discover your API automatically via the x402 Bazaar:

from x402.verify import useFacilitator
from coinbase.x402 import facilitator
from eth_account import Account
from x402.clients.httpx import x402HttpxClient

# 1. Discover available financial APIs
facilitator_client = useFacilitator(facilitator)
services = await facilitator_client.list()

# Filter for finance services under $0.10
finance_apis = [
    s for s in services.items 
    if "finance" in s.metadata.get("tags", [])
    and int(s.accepts[0].maxAmountRequired) < 100000
]

# 2. Select XFinance API
xfinance = next(s for s in finance_apis if "xfinance" in s.resource)

# 3. Use it (payment automatic)
account = Account.from_key(AGENT_WALLET_KEY)
async with x402HttpxClient(account=account, base_url=xfinance.resource) as client:
    response = await client.get("/ticker/AAPL/info")
    data = await response.json()
    
    # Agent processes data
    agent.analyze_market_data(data)

The agent never needs to know your API URL beforehand. It discovers, pays, and uses automatically!

Direct Usage (If Agent Knows Your URL)

from eth_account import Account
from x402.clients.httpx import x402HttpxClient

account = Account.from_key(AGENT_WALLET_KEY)

async with x402HttpxClient(
    account=account,
    base_url="https://api.xfinance.cc"
) as client:
    # Agent makes multiple requests
    aapl = await client.get("/ticker/AAPL/info")
    msft = await client.get("/ticker/MSFT/info")
    history = await client.get("/ticker/AAPL/history?period=1mo")
    
    # All payments handled automatically
    # Cache means subsequent calls to same endpoint are free

📊 Real-World Flow Visualization

Human Flow:

1. Developer writes: session.get("/ticker/AAPL/info")
2. Client sends: GET /ticker/AAPL/info
3. Server responds: 402 Payment Required
4. Client detects 402 → signs payment → sends to facilitator
5. Facilitator verifies → settles on-chain
6. Client retries: GET /ticker/AAPL/info + X-PAYMENT header
7. Server responds: 200 OK + market data
8. Developer gets: {"symbol": "AAPL", "data": {...}}

AI Agent Flow:

1. Agent queries Bazaar: "Find finance APIs"
2. Bazaar returns: [XFinance, TokenMetrics, ...]
3. Agent selects XFinance (best price/coverage)
4. Agent calls: GET /ticker/AAPL/info
5. Same 402 → pay → retry → 200 flow (automatic)
6. Agent processes data and continues workflow

Integration Tips