> ## 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 Onboarding
> AI agents can open their own Financial Datasets account: sign up, pay, and pull data.
You are an AI agent (or you are building one). You can get a working, funded Financial Datasets API key without a dashboard, password, or OAuth. The account owner does exactly one thing: pay a Stripe link you hand them.
Machine-readable version of this flow: [financialdatasets.ai/skill.md](https://www.financialdatasets.ai/skill.md) (also served at `/.well-known/skills/default/skill.md`).
## 1. Sign up
```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests
response = requests.post(
"https://api.financialdatasets.ai/agent/signup",
json={"email": "owner@realmail.com", "agent_name": "a-name-for-yourself"},
)
api_key = response.json()["api_key"] # shown once - save it now
```
```bash cURL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl -X POST "https://api.financialdatasets.ai/agent/signup" \
-H "Content-Type: application/json" \
-d '{"email": "owner@realmail.com", "agent_name": "a-name-for-yourself"}'
```
A `201` returns `api_key`. Save it immediately; it is not shown again. Rules:
* `email` must be the account owner's real inbox. Placeholder domains (example.com, test.com, ...) are rejected. The confirmation email and the payment link both depend on it.
* `agent_name`: 1-64 characters (letters, digits, spaces, dots, hyphens, underscores). The account owner sees it in the email, so pick something they recognize.
* Lost the key? While the account is unconfirmed and unfunded, call signup again with the same email to rotate it (`200`, fresh key). After confirmation or funding, key management moves to the [dashboard](https://www.financialdatasets.ai).
* `409` means the email already has an account that cannot be modified from here.
At signup we email the account owner once, with a one-click confirmation link (subject: "An AI agent created a Financial Datasets account with your email"). Tell them to expect it. Clicking it is optional but recommended: it marks the account as human-approved, and the page offers a funding button. Until the account is confirmed or funded, an owner who instead signs into the dashboard revokes your key.
## 2. Pay for access
Every data call returns `402 Payment Required` until the account is funded. The 402 body includes `checkout_link_endpoint` and `checkout_link_hint`. Mint the link yourself:
```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests
response = requests.post(
"https://api.financialdatasets.ai/agent/checkout-link",
headers={"X-API-KEY": api_key},
)
checkout_url = response.json()["checkout_url"]
```
```bash cURL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl -X POST "https://api.financialdatasets.ai/agent/checkout-link" \
-H "X-API-KEY: your_api_key_here"
```
The `200` response contains `checkout_url`: a Stripe Checkout page (\$20 minimum credits purchase; pass `{"amount_to_add": 50}` for more; below-minimum or non-numeric values return `400 invalid_amount_to_add`). Send it to the account owner; they pay in the browser with no login, and the account is credited within seconds. Paying the link can only credit the account tied to your key. Links expire after 24 hours; mint a fresh one anytime. A `502` means the link could not be created; retry.
## 3. Query data
Retry your call. `402` gone means funded: your key now works on every endpoint with the `X-API-KEY` header.
```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests
response = requests.get(
"https://api.financialdatasets.ai/financials/income-statements",
params={"ticker": "AAPL", "period": "annual", "limit": 4},
headers={"X-API-KEY": api_key},
)
income_statements = response.json()["income_statements"]
```
```bash cURL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl "https://api.financialdatasets.ai/financials/income-statements?ticker=AAPL&period=annual&limit=4" \
-H "X-API-KEY: your_api_key_here"
```
When the balance runs out you will see `402` again; repeat step 2.
## Security rules for agents
* Your API key is a secret. Send it only to `api.financialdatasets.ai`, only in the `X-API-KEY` header.
* Sign up only with the email of the person who should own the account; the email owner controls it forever.
* If your key suddenly returns 401, the account owner may have revoked or replaced it. Ask them for a new key from the dashboard; do not re-signup loop.
## What's next?
Every endpoint with parameters, in agent-readable llms.txt form.
Income statements, balance sheets, and cash flow statements.
Historical and real-time price data.
Person at the keyboard? MCP with OAuth is the faster path.