Quickstart

FinData4AI should be evaluated by workflow, not by endpoint count. Start with the user task your agent must complete, call only the datasets that are available for that task, then pass compact source-aware context to the model.

1. Pick the user job first

The first workflows to validate are:

User job	Data needed	Coverage stage
Explain margin or cash-flow risk	Financial statements, filing links, market notes	P0
Extract risk changes from filings	SEC filings and company announcements	P0
Monitor a portfolio for events	Market bars, SEC filings, company announcements, news	P0
Add deeper research context	Ownership, transcripts, estimates, operating KPIs	Roadmap

2. Create a server-side API key

Create a key in the dashboard and keep it on your server. Do not expose the key in browser code, notebooks shared with users, or model prompts.

export FINDATA4AI_API_KEY="fd4a_..."

3. Choose the market before planning tools

Most equity workflows should carry explicit market context:

US equities     market=us   ticker=AAPL
Hong Kong       market=hk   ticker=00700
A-shares        market=cn   ticker=600519
Crypto pairs    roadmap

If a market is marked as preview or roadmap, keep it out of autonomous agent plans until your application has a fallback.

4. Run one grounded request

Start with a simple request and confirm the response shape before building a multi-step agent.

curl "https://api.findata4ai.com/financials/income-statements?market=hk&ticker=00700&period=annual" \
  -H "X-API-Key: $FINDATA4AI_API_KEY"

Server-side fetch:

const response = await fetch(
  'https://api.findata4ai.com/financials/income-statements?market=hk&ticker=00700&period=annual',
  {
    headers: {
      'X-API-Key': process.env.FINDATA4AI_API_KEY!,
    },
  },
);

if (!response.ok) {
  throw new Error(`FinData4AI request failed: ${response.status}`);
}

const data = await response.json();

5. Pass compact context to your agent

Do not paste entire filings, announcements, or news pages into the prompt. Retrieve the fields and source metadata your task needs, then pass a compact object.

const context = {
  task: 'Explain operating margin risk for Tencent',
  market: 'hk',
  ticker: '00700',
  fields: data.fields ?? data.items?.[0],
  sources: data.sources ?? [{ type: 'financial_statement', url: data.items?.[0]?.filing_url }],
  marketNotes: data.market_notes ?? ['Confirm market coverage before autonomous use.'],
};

6. Use the machine-readable contract

API reference: /docs/api
OpenAPI schema: /openapi.json
Agent-readable index: /llms.txt
Agent integration guide: /docs/agent-integration

Error handling

Status	Meaning	What to do
`400`	Invalid market, ticker, or parameter	Validate endpoint docs and supported market badges.
`401`	Missing or invalid API key	Check `X-API-Key` and keep it server-side.
`404`	No matching resource	Confirm ticker format, market, and coverage stage.
`429`	Rate limit or credits exhausted	Back off, inspect dashboard usage, or upgrade.
`5xx`	Service-side failure	Retry with backoff and keep request IDs for support.