US Stock Endpoints

GET /api/v1/us/companies

US public company metadata.

Query Parameters:

Parameter	Type	Filter Type	Description
cik	string	exact	SEC CIK
ticker	string	exact	Stock ticker
exchange	string	exact	Exchange (NYSE, NASDAQ, etc.)
industry	string	exact	Industry
sector	string	exact	Sector
name	string	like	Company name (fuzzy)

Example:

curl -H "F-API-KEY: fk-xxxxx" \
  "https://finance-api.xp-java.workers.dev/api/v1/us/companies?ticker=AAPL"

GET /api/v1/us/filings

SEC filings (10-K, 10-Q, 8-K, etc.).

Query Parameters:

Parameter	Type	Filter Type	Description
cik	string	exact	SEC CIK
ticker	string	exact	Stock ticker
filing_type	string	exact	Filing type
accession_number	string	exact	Accession number
date_from	string	date range	Start date
date_to	string	date range	End date

GET /api/v1/us/financial-facts

Standardized US GAAP financial facts (XBRL).

Query Parameters:

Parameter	Type	Filter Type	Description
cik	string	exact	SEC CIK
ticker	string	exact	Stock ticker
standard_name	string	exact	Standardized concept name
fiscal_year	string	exact	Fiscal year
fiscal_period	string	exact	Fiscal period (FY, Q1, Q2, Q3, Q4)
date_from	string	date range	Start date
date_to	string	date range	End date

GET /api/v1/us/financial-statements

Full financial statement line items.

Query Parameters:

Parameter	Type	Filter Type	Description
cik	string	exact	SEC CIK
ticker	string	exact	Stock ticker
accession_number	string	exact	Accession number
statement_type	string	exact	BalanceSheet, IncomeStatement, CashFlow
concept	string	exact	XBRL concept
fiscal_year	string	exact	Fiscal year
fiscal_period	string	exact	Fiscal period
date_from	string	date range	Start date
date_to	string	date range	End date

GET /api/v1/us/financial-metrics

Pre-calculated financial metrics.

Query Parameters:

Parameter	Type	Filter Type	Description
cik	string	exact	SEC CIK
ticker	string	exact	Stock ticker
metric_name	string	exact	Metric name
fiscal_year	string	exact	Fiscal year
fiscal_period	string	exact	Fiscal period

GET /api/v1/us/insider-trades

Insider trading transactions.

Query Parameters:

Parameter	Type	Filter Type	Description
cik	string	exact	SEC CIK
ticker	string	exact	Stock ticker
insider_name	string	exact	Insider name
transaction_type	string	exact	Transaction type
transaction_code	string	exact	Transaction code
accession_number	string	exact	Accession number
date_from	string	date range	Start date
date_to	string	date range	End date

GET /api/v1/us/13f-holdings

Institutional 13F holdings.

Query Parameters:

Parameter	Type	Filter Type	Description
cik	string	exact	SEC CIK
ticker	string	exact	Stock ticker
filing_type	string	exact	Filing type
accession_number	string	exact	Accession number
cusip	string	exact	CUSIP
manager_name	string	like	Manager name (fuzzy)
date_from	string	date range	Start date
date_to	string	date range	End date