> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Financial Datasets API is served at https://api.financialdatasets.ai. Authenticate with the `X-API-KEY` header; create keys at https://financialdatasets.ai. Agents can open and fund their own account without a dashboard: see https://docs.financialdatasets.ai/agents.md.
> Tool-using agents can call Financial Datasets without writing code through the hosted MCP server at https://mcp.financialdatasets.ai/.
> The OpenAPI spec at https://financialdatasets.ai/openapi.json is the source of truth for request and response schemas.
> The index of every docs page is at https://docs.financialdatasets.ai/llms.txt. Append .md to any docs URL to get that page as Markdown.

# x402

> Access the Financial Datasets API without an API key by paying per request with x402.

## Overview

[x402](https://www.x402.org) is an open payment protocol. A client pays for each HTTP request with USDC on [Base](https://base.org). No API key or account is required.

Requests that include an `X-API-KEY` header are billed to that account as usual. x402 applies only to requests without a key.

## How it works

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

The x402 client libraries handle steps 2 to 4.

## Supported endpoints

| Endpoint | Data |
| - | - |
| [`GET /prices`](https://docs.financialdatasets.ai/api/prices/historical) | Historical end-of-day prices |
| [`GET /prices/snapshot`](https://docs.financialdatasets.ai/api/prices/snapshot) | Real-time price |
| [`GET /financials/income-statements`](https://docs.financialdatasets.ai/api/financials/income-statements) | Income statements |
| [`GET /financials/balance-sheets`](https://docs.financialdatasets.ai/api/financials/balance-sheets) | Balance sheets |
| [`GET /financials/cash-flow-statements`](https://docs.financialdatasets.ai/api/financials/cash-flow-statements) | Cash flow statements |
| [`GET /financial-metrics`](https://docs.financialdatasets.ai/api/financial-metrics/historical) | Historical financial metrics |
| [`GET /financial-metrics/snapshot`](https://docs.financialdatasets.ai/api/financial-metrics/snapshot) | Real-time financial metrics |
| [`GET /earnings`](https://docs.financialdatasets.ai/api/earnings) | Earnings results and estimates |
| [`GET /insider-trades`](https://docs.financialdatasets.ai/api/insider-trades) | Form 4 insider transactions |
| [`GET /beneficial-ownership`](https://docs.financialdatasets.ai/api/beneficial-ownership) | Schedule 13D and 13G holdings |
| [`GET /activist-ownership`](https://docs.financialdatasets.ai/api/activist-ownership) | Schedule 13D activist holdings |

Parameters and response formats are the same as with an API key. All other endpoints require an [API key](https://docs.financialdatasets.ai/quickstart.md).

## Requirements

* A wallet on Base whose private key the client holds. The client signs each payment locally.
* USDC on Base in that wallet.
* No ETH is needed. The facilitator pays the gas.

## Example

```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# pip install "x402[evm]" requests
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.status_code)                    # 200
print(response.headers["PAYMENT-RESPONSE"])    # base64 receipt with the transaction hash
print(response.json()["earnings"][0])
```

```typescript TypeScript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// npm install @x402/fetch @x402/evm viem
import { privateKeyToAccount } from "viem/accounts";
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);

const client = new x402Client();
client.register("eip155:8453", new ExactEvmScheme(account));
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

const response = await fetchWithPayment(
  "https://api.financialdatasets.ai/earnings?ticker=NVDA&limit=4"
);
console.log(response.status);                          // 200
console.log(response.headers.get("PAYMENT-RESPONSE")); // base64 receipt with the transaction hash
console.log((await response.json()).earnings[0]);
```

```bash cURL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Without a client library, the request returns the 402 and the payment terms.
curl -i "https://api.financialdatasets.ai/earnings?ticker=NVDA&limit=4"

# HTTP/2 402
# payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIi...
# {"error": "Payment required", "message": "Send an X-API-KEY header, or pay per call with x402 ..."}
```

## Payment terms

The `PAYMENT-REQUIRED` header is base64-encoded JSON:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "x402Version": 2,
  "resource": {
    "url": "https://api.financialdatasets.ai/earnings",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "<amount in USDC base units>",
      "payTo": "0xC45E70793C01C6Ae4336dd5a5503baC958d32403",
      "maxTimeoutSeconds": 300
    }
  ]
}
```

| Field | Value |
| - | - |
| `network` | `eip155:8453` (Base mainnet) |
| `asset` | USDC contract on Base |
| `amount` | Amount in USDC base units (6 decimals) |
| `payTo` | Financial Datasets receiving address |

Read the amount from the header on each request.

## Receipts

Every paid `200` response includes a `PAYMENT-RESPONSE` header. It is base64-encoded JSON with `success`, `network`, `payer`, and `transaction` (the on-chain transaction hash).

## Limits

* **History.** x402 requests return data from the last 365 days. A request for older data only returns `403` with the window start date. Full history requires an [API key](https://docs.financialdatasets.ai/quickstart.md).
* **Rate limit.** 10,000 requests per minute per wallet.
* **Pagination.** `next_page_url` works the same as with an API key. Each page is a separate paid request.
* **Settlement.** Payment is settled only after a successful response. Error responses are not charged.
* **License.** Data accessed with x402 is for Non-Professional use. Professional use requires a plan at [financialdatasets.ai](https://financialdatasets.ai).

## Errors

Payment errors return `402` with a JSON body. The `error` field identifies the cause.

| `error` | Meaning |
| - | - |
| `Payment required` | No payment was included. Sign a payment from the `PAYMENT-REQUIRED` terms and retry. |
| `duplicate_payment` | The signature was already used. Sign a new payment. |
| `payer_blocked` | Recent payments from this wallet failed to settle. Check the USDC balance and retry later. |
| `settlement_failed` | Verification passed but the on-chain transfer failed. No data was returned and nothing was charged. |

A `503` with a `Retry-After` header means the facilitator is temporarily unavailable. Retry after the given interval.

## Related

> **[Agent Onboarding](https://docs.financialdatasets.ai/agents.md)**
>
> Create an API key programmatically for endpoints and history not covered by x402.

> **[Endpoint map](https://www.financialdatasets.ai/llms.txt)**
>
> Every endpoint with parameters, in llms.txt form.

> **[Announcement](https://www.financialdatasets.ai/blogs/x402)**
>
> Introducing x402 payments on the Financial Datasets blog.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.