Financial Datasets
Back to Blog

Introducing x402 payments

Financial Datasets Team · 3 min read

Introducing x402 payments

Financial Datasets now supports x402 payments. x402 is an open protocol for paying for an HTTP request with a stablecoin. An AI agent can call our financial data API without an API key or an account. It pays for each request with USDC on Base, and the data comes back in the same response.

Why

An agent that needs a price or a filing today has to stop and ask a person for an API key. With x402, the agent sends the request, pays for it, and moves on. There is nothing to sign up for and nothing to configure beyond a wallet.

How a request works

  1. The agent calls an endpoint with no X-API-KEY header.
  2. The API returns 402 Payment Required. A PAYMENT-REQUIRED header carries the terms: the amount, the USDC contract on Base, and our receiving address.
  3. The agent signs a USDC transfer authorization for that amount and retries the request with a PAYMENT-SIGNATURE header.
  4. The API verifies the signature, returns the data, and settles the payment on-chain. A PAYMENT-RESPONSE header carries the transaction hash as the receipt.

The x402 client libraries handle steps 2 to 4. The agent's code makes a normal GET request.

import os
from eth_account import Account
from x402 import x402ClientSync
from x402.http.clients.requests import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact import ExactEvmScheme

account = Account.from_key(os.environ["WALLET_PRIVATE_KEY"])

client = x402ClientSync()
client.register("eip155:8453", ExactEvmScheme(EthAccountSigner(account)))
session = x402_requests(client)

response = session.get("https://api.financialdatasets.ai/earnings?ticker=NVDA&limit=4")
print(response.json()["earnings"][0])

Supported endpoints

  • Historical and real-time stock prices
  • Income statements, balance sheets, and cash flow statements
  • Historical and real-time financial metrics
  • Earnings results and estimates
  • Insider trades
  • Beneficial ownership and activist ownership

Parameters and response formats are the same as with an API key. Requests that include an API key are billed to that account as before.

Limits

  • x402 requests return data from the last 365 days. Full history requires an API key.
  • Payment is settled only after a successful response. Error responses are not charged.
  • Data accessed with x402 is for Non-Professional use.

The full reference, including the TypeScript example, payment terms, and error codes, is in the x402 docs. Agents that need the full endpoint set or full history can create an API key programmatically instead.

FAQ

What is x402?

x402 is an open protocol for paying for an HTTP request with a stablecoin. The server answers an unpaid request with HTTP status 402 and the payment terms. The client signs a payment and retries, and the server returns the data with an on-chain receipt.

Do I need an API key to use x402?

No. An x402 request carries a signed USDC payment instead of an API key. Requests that include an API key are billed to that account as before.

Which endpoints accept x402?

Stock prices, income statements, balance sheets, cash flow statements, financial metrics, earnings, insider trades, beneficial ownership, and activist ownership. The full list is in the x402 docs.

What wallet do I need?

A wallet on Base whose private key your client holds, with USDC in it. The client signs each payment locally. No ETH is needed because the facilitator pays the gas.