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

Every documented GET data endpoint, 36 in all:

• Historical and real-time stock prices
• Income statements, balance sheets, cash flow statements, and their segment breakdowns
• Historical and real-time financial metrics
• Company facts, SEC filings, earnings, and news
• Insider trades and insider ownership
• Beneficial, activist, and institutional holdings, and index fund constituents
• Macro series: interest rates, the yield curve, inflation, labor, and GPU prices
• IPO filings and KPIs: operating metrics, guidance, and non-GAAP figures

Not covered: filing items, the market snapshot, POST endpoints, and the free helper lists such as the ticker lists. 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

• 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 endpoints not covered 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?

Every documented GET data endpoint, 36 in all: prices, financial statements and segments, financial metrics, company facts, filings, earnings, news, insider trades and ownership, beneficial, activist and institutional holdings, index funds, macro series, IPOs, and KPIs. 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.