# Changelog
Source: https://docs.ainvest.com/docs/changelog
Product updates and release plan
**Breaking change!**
[News](/reference/news/wires-content) and [Articles](/reference/news/articles-content) details endpoints now require to use content\_id instead of seo\_key to retrieve content body
[Financial statements by stock ticker](/reference/securities/stock-statements) updated to reflect proper hierarchical structure of every item
[Economic events calendar](/reference/calendar/economics) interface to report major economic events, like agricultural reports, Federal Reserve rates changes, Unemployment claims updates, Treasury auctions and so on.
[News wires](/reference/news/wires) is changed to separate content body as a separate endpoint [News content](/reference/news/wires-content)
[Financial statements by stock ticker](/reference/securities/stock-statements), includes income, cashflow and balance sheets
[Dividends by stock ticker](/reference/securities/stock-dividends). ETFs are not supported yet.
[Earnings by stock ticker](/reference/securities/stock-earnings) includes links to official SEC filings, investor call transcripts and AI-generated summary of call transcripts
[Candles](/reference/marketdata/candles) now supports `adjustment` parameter that calculates backward or forward-adjusted historical prices.
[Earnings AI backtesting](/reference/calendar/earnings-backtesting) that provides statistics of a stock performance after earnings reports
[Dividends by date](/reference/calendar/dividends)
[Earnings by date](/reference/calendar/earnings)
[IPO by date](/reference/calendar/ipo)
[Splits by date](/reference/calendar/corporateactions) by date
[ETF profile](/reference/securities/etf-profile) by ticker
[ETF holdings](/reference/securities/etf-holdings) by ticker
[Historical prices](/reference/marketdata/candles) as candlesticks in open-high-low-close-volume format.
[Tick data](/reference/marketdata/trades) for current trading day.
[Company financials](/reference/securities/stock-financials) collected from public earning reports and balance sheets.
[Securities search](/reference/securities/search) by ticker or security name
[US Congress trades](/reference/ownership/congress). Purchases and sales made by members of US Congress
[Insider trades](/reference/ownership/insider). Purchases and sales made by officers, directors, and those that hold more than 10% of any class of a company’s securities.
[Analyst ratings](/reference/analysis-ratings/history) dataset to allow to drill down to firm and date level to see the history of ratings
**MCP Server** to connect with AI models
[News wires](/reference/news/wires). Near-realtime aggregated news feed curated by human financial professionals and enriched by our AI models.
[Average analysts rating](/reference/analysis-ratings/consensus). Recommendations given to a stock by financial analysts.
# MCP servers
Source: https://docs.ainvest.com/docs/mcp-servers
Connecting AI chatbots to Ainvest financial data
An MCP server is a component of the Model Context Protocol (MCP), an open standard developed by Anthropic, the company behind Claude.
MCP is used for connecting AI models with external tools and data sources. It acts as a bridge, enabling AI applications to access and use external API.
## Remote Ainvest MCP
Server url: [https://docsmcp.ainvest.com](https://docsmcp.ainvest.com). Make sure you configure your MCP client to pass the Authorization header the same way as you would call an API endpoint:
```
Authorization: Bearer {AUTH_TOKEN}
```
## Configuring Claude Code
With Claude Code command line client installed, run the following command:
```
claude mcp add --transport http ainvest https://docsmcp.ainvest.com --header "Authorization: Bearer ${AUTH_TOKEN}" -s user
```
## Configuring Claude Desktop
Claude offers direct connectivity to remote MCP servers with their more expensive subscription plan. With free version you can still use MCP servers, but they have to be run locally.
One of the easier ways is to use [https://www.npmjs.com/package/mcp-remote](https://www.npmjs.com/package/mcp-remote), which is run locally and simply converts local calls to remote calls. Add this to Claude Desktop configuration.
Note that you still need to have nodejs and npx installed on your machine:
```json theme={null}
"remote ainvest": {
"command": "npx",
"args": [
"mcp-remote",
"https://docsmcp.ainvest.com",
"--header",
"Authorization: Bearer ${AUTH_TOKEN}"
],
"env": {
"AUTH_TOKEN": "your token goes here"
}
}
```
# Getting started
Source: https://docs.ainvest.com/docs/quickstart
Financial data suite built by finance people for engineers. Simple steps to try now
## See the data in action
If not yet, register an account with [Ainvest](https://ainvest.com).
When logged in, go to the [Developer center](https://www.ainvest.com/business/widgets/developer-manage/) to create your api keys. No credit card or other payment is required. Our free data plan allows limited amount of api calls per minute and per day, but this is quite enough for development and testing purposes.
Go to our [API playground](/reference), paste the key to the Authorization header field to try it directly from the browser. Production base url is [https://openapi.ainvest.com/open](https://openapi.ainvest.com/open)
# Analyst ratings
Source: https://docs.ainvest.com/reference/analysis-ratings
## Basics
An analyst rating is a one-word recommendation given to a stock by a financial analyst,
indicating their view on whether the stock is a good buy, sell, or hold.
These ratings help investors understand the analyst's perspective on a stock's future performance.
Analysts are usually operating with the following or similar categories
**strong\_buy**: The analyst believes the stock is undervalued and has potential for significant growth, making it a good investment opportunity.
**buy**: A more positive rating than **hold**, indicating the stock is expected to outperform its benchmark index.
**hold**: Good enough to keep in a portfolio but not worthy of additional investment.
**sell**: A more negative rating than **hold**, suggesting the stock is expected to underperform its benchmark index.
**strong\_sell**: The analyst believes the stock is overvalued and likely to decline in price, suggesting it's best to sell.
The SEC and FINRA have rules in place to help make sure there is objectivity and transparency in research reports.
Any recommendations, ratings, or price targets in reports must have a reasonable basis.
Ratings should reflect research outcomes and be based on facts, independent of any conflicts of interest that the firm or its employees may have.
## Examples
With this data, you can create data widgets. You can also analyze the data to drill further down to firms and dates of their research reports.
Another good approach is to connect it to an LLM for further analysis.
# Average rating
Source: https://docs.ainvest.com/reference/analysis-ratings/consensus
reference/analysis-ratings/analysis-ratings.yaml GET /analysis-ratings/consensus
Get current rating and target price averaged across all analysts opinions
```json Response example for AAPL theme={null}
"data": {
"analysts_ratings": {
"count": 50,
"buy": 32,
"hold": 14,
"sell": 4,
"average_rating": "Buy"
},
"target_price": {
"count": 16,
"high": 300.0,
"average": 226.97625,
"low": 170.0
}
}
```
# All ratings
Source: https://docs.ainvest.com/reference/analysis-ratings/history
reference/analysis-ratings/analysis-ratings.yaml GET /analysis-ratings/history
Get all ratings along with target prices, firm names and dates of the research publication
```json Response example for AAPL theme={null}
"data": {
"data": [
{
"date": "2025-06-26",
"firm": "JP Morgan",
"action": "Maintained",
"rating_previous": null,
"rating": "Overweight",
"target_price_previous": 240.0,
"price_target": 230.0
},
{
"date": "2025-06-10",
"firm": "Needham",
"action": "Maintained",
"rating_previous": null,
"rating": "Hold",
"target_price_previous": null,
"price_target": null
},
{
"date": "2025-06-10",
"firm": "B of A Securities",
"action": "Maintained",
"rating_previous": null,
"rating": "Buy",
"target_price_previous": null,
"price_target": 235.0
}
]
}
```
# Splits calendar
Source: https://docs.ainvest.com/reference/calendar/corporateactions
reference/calendar/calendar.yaml GET /calendar/corporateactions
Get corporate actions (stock splits and reverse splits) on the specified date.
# Dividends calendar
Source: https://docs.ainvest.com/reference/calendar/dividends
reference/calendar/calendar.yaml GET /calendar/dividends
Get dividends on the specified ex-date. Both historical or upcoming dividends can be retrieved.
# Earnings calendar
Source: https://docs.ainvest.com/reference/calendar/earnings
reference/calendar/calendar.yaml GET /calendar/earnings
Get earnings announcements on the specified date
For more info including corresponding SEC forms and investor call transcripts, please refer to [earnings by ticker](/reference/securities/stock-earnings) API endpoint.
An earnings report is a company's official statement showing how much money they made (or lost) during the previous quarter.
Securities and Exchange Commission (SEC) requires all public companies to file Form 10-Q for each of the first three quarters of the company's fiscal year.
At the last quarter of a fiscal year the quarterly report is not published, the annual Form 10-K must be filed instead. This report, unlike the quarterly one, is audited by an independent audit firm and tends to have more details.
The exact filing dates depend on organization's fiscal year.
### The two numbers that matter most
Earnings reports matter because they're the closest thing to financial truth in the stock market.
**Earnings Per Share (EPS)**: This is the company's total profit divided by the number of shares outstanding. If a company earned \$100 million and has 50 million shares, that's \$2 per share. EPS tells you how profitable the company is.
**Revenue**: This is the total amount of money flowing into the company before expenses. Revenue shows whether the business is growing, shrinking, or staying flat. A company might have great revenue but poor profits, or they might have lower revenue but excellent profit margins.
Here's where it gets interesting for traders. Before each earnings report, analysts make predictions about what they think the EPS and revenue will be. These are called "estimates" or "expectations". Beat expectations? Stock often jumps up. Miss expectations? Stock often goes down. Sometimes even good news sends stocks down if investors were expecting *great* news.
There are multiple strategies that can help making a decision, one of them is [testing on historical data](/reference/calendar/earnings-backtesting).
# Earnings backtesting
Source: https://docs.ainvest.com/reference/calendar/earnings-backtesting
reference/calendar/calendar.yaml GET /calendar/earnings/backtesting
Get earnings backtesting results
Earnings reports are anticipated by analysts and traders because they reveal the hard numbers on a company's wellbeing.
After the report is published, traders expect price movements. To help them make a decision, our [Aime the AI](https://www.ainvest.com/chat)
does some backtesting analysis by looking back at all previous earnings reports and tracking the stock price after each report.
With this data in hand, Aime provides some statistics on how the stock price usually performs after actual earnings beat forecasts.
For example, according to Aime's analysis on July 31 2025,
the stock price of [CMCSA (Comcast)](https://www.ainvest.com/stocks/NASDAQ-CMCSA) grows within the next 3 days in 80% of cases.
In 30 days after the earnings report, the returns tend to stay positive.
```json theme={null}
{
"data": {
"headline": "Backtest CMCSA Earning Beats",
"summary": "The backtest shows CMCSA consistently
outperforms following earnings beats, with an 80% win rate
over three days and sustained positive
returns up to 30 days. In contrast, the broader
Media Industry exhibits negligible impact from earnings
beats, suggesting company-specific factors drive
CMCSA's success. Furthermore, Comcast's earnings
beat positively influences the overall market
but negatively affects the Healthcare Services
sector due to shifting consumer spending.
This indicates a sector-specific dynamic where
strong telecom earnings can bolster market
confidence yet divert attention from healthcare.
Investors might benefit from focusing on CMCSA
directly while monitoring sector rotations."
},
"status_code": 0,
"status_msg": "success"
}
```
# Economic events calendar
Source: https://docs.ainvest.com/reference/calendar/economics
reference/calendar/calendar.yaml GET /calendar/economics
Get economic events (e.g. GDP releases, employment reports) on the specified date.
# IPO calendar
Source: https://docs.ainvest.com/reference/calendar/ipo
reference/calendar/calendar.yaml GET /calendar/ipo
Get Initial Public Offerings (IPO) scheduled on the specified date. Both historical or upcoming IPOs can be retrieved.
IPOs (Initial Public Offerings) are how private companies first sell shares to the public and get listed on stock exchanges.
A company wanting to go public typically hires investment banks as underwriters. These banks help determine the company's value, prepare regulatory filings (like the S-1 with the SEC), and market the shares to institutional investors.
The banks define a range of prices to accept bids from potential investors. This allows underwriters to gauge investor demand. If there's strong interest, they can price at the high end or even above the range. Weak demand might push pricing to the low end or cause a delay.
The actual IPO price is set the evening before public trading begins, based on the order book from institutional investors. This "book building" process shows real demand at different price levels, allowing underwriters to optimize both the price and allocation of shares.
The goal is to price the IPO so it trades positively on the first day (showing investor confidence) but doesn't leave too much money on the table for the company.
# Codes
Source: https://docs.ainvest.com/reference/codes
Some API endpoints return exchanges as internal codes:
| Exchange | Code |
| -------- | ---- |
| NYSE | 169 |
| AMEX | 170 |
| CBOE | 171 |
| NASDAQ | 185 |
# Candles
Source: https://docs.ainvest.com/reference/marketdata/candles
reference/marketdata/marketdata.yaml GET /marketdata/candles
Use this endpoint to get prices as OHLCV (open-high-low-closed-volume) data for specified period, aggregation interval and trading session
# Trades
Source: https://docs.ainvest.com/reference/marketdata/trades
reference/marketdata/marketdata.yaml GET /marketdata/trades
Use this endpoint to get `count` trades for a specific stock `ticker`, printed immediately before the `to` timestamp. The trades are ordered by time, ascending.
Currently only returns data for current trading day. Access to historical tick data is not implemented yet
# Articles
Source: https://docs.ainvest.com/reference/news/articles
reference/news/news.yaml GET /news/v1/article/page/history
Returns latest articles ordered by time latest first, supports pagination and filtering options.
# Articles content
Source: https://docs.ainvest.com/reference/news/articles-content
reference/news/news.yaml GET /news/v1/article/info/{content_id}
Returns the article content body for a given article ID. For performance reasons, content body is not included in the articles list [page](/reference/news/articles) endpoint.
# News wires
Source: https://docs.ainvest.com/reference/news/wires
reference/news/news.yaml GET /news/v1/wire/page/history
Returns latest news wires ordered by time latest first, supports pagination and filtering options.
The news wires, or newswire, is a near-realtime aggregated news feed curated by human financial professionals and enhanced by our AI models.
* The news are based on public news outlets
* Our AI generates and attaches an eye-catching cover image
* After that it identifies and tags any trading tickers mentioned in the content
* Then it determines the 'importance' of the news and marks accordingly so that API consumers could emphasize it to their end-users
The data is pushed very often, many times a minute. The endpoint supports filtering by stock symbol, industry or category. For performance reasons,
this endpoint does not expose content body, please use [info](/reference/news/wires-content) to get the content by id
# Wire content
Source: https://docs.ainvest.com/reference/news/wires-content
reference/news/news.yaml GET /news/v1/wire/info/{content_id}
Returns the news content body for a given news ID. For performance reasons, content body is not included in the news headline [page](/reference/news/wires) endpoint.
# US Congress trades
Source: https://docs.ainvest.com/reference/ownership/congress
reference/ownership/ownership.yaml GET /ownership/congress
Get trades by US politicians, including date, type of trade, approximate dollar value
Since 2012, the Stop Trading on Congressional Knowledge (STOCK) Act requires certain federal officials, including members of Congress,
to publicly disclose their financial transactions over \$1000 in those involving stocks, bonds, and some commodities.
This is done through the Periodic Transaction Report (OGE Form 278-T), which must be filed within 30 days of notification of the transaction, but no later than 45 days after the transaction.
Political figures on Capitol Hill often have access to information that could influence market movements before it becomes public. By following their trades through this API, you can:
* Monitor when senators purchase stocks in sectors before favorable legislation
* Identify House of Representatives members' trading patterns around regulatory announcements
* Analyze timing between committee hearings and politician stock transactions
* Identify politicians with consistently late filings (beyond the 45-day requirement)
# Insider trades
Source: https://docs.ainvest.com/reference/ownership/insider
reference/ownership/ownership.yaml GET /ownership/insider
Get insider trades as filed with SEC, including date, type of trade, number of shares and price
The federal securities laws require certain individuals (such as officers, directors, and those that hold more than 10% of any class of a company’s securities)
to report purchases, sales, and holdings of their company’s securities by filing Forms 3, 4, and 5.
When a person becomes an insider (for example, when they are hired as an officer or director), they must file a Form 3 to initially disclose his or her ownership of the company’s securities.
Form 3 must be filed within 10 days after the person becomes an insider.
In most cases, when an insider executes a transaction, he or she must file a Form 4.
With this form filing, the public is made aware of the insider’s various transactions in company securities, including the amount purchased or sold and the price per share.
Form 4 must be filed within two business days following the transaction date.
Transactions in a company’s common stock as well as derivative securities, such as options, warrants, and convertible securities, are reported on the form.
A Form 5 is generally due to the SEC no later than 45 days after the company’s fiscal year ends and is only required from an insider when at least one transaction,
because of an exemption or failure to earlier report, was not reported during the year.
For example, some transactions, such as certain purchases by an insider of less than \$10,000 in a six-month period,
don’t have to be reported on Form 4 when they occur but do have to be reported on Form 5.
This information is public, we collect the filed forms, parse them and expose as nicely structured json here.
# ETF holdings
Source: https://docs.ainvest.com/reference/securities/etf-holdings
reference/securities/securities.yaml GET /securities/etf/holdings
Get a list of holdings in an ETF. Also provides history of changes for known dates.
Currently returns data for top 10 holdings only
# ETF profile
Source: https://docs.ainvest.com/reference/securities/etf-profile
reference/securities/securities.yaml GET /securities/etf/profile
Get general information about an ETF, including its name, industry, aum, fee rates, dividend rates and other details.
# Securities search
Source: https://docs.ainvest.com/reference/securities/search
reference/securities/securities.yaml GET /securities/search
Search for US stocks by ticker symbol or company name. Returns a list of matching securities ordered by relevance.
```json Response example for ?query=Bank of America theme={null}
{
"data": {
"data": [
{
"ticker": "BAC",
"name": "Bank Of America",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BACpN",
"name": "Bank Of America Pref LL ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BMLpJ",
"name": "Bank Of America Pref 4 ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BACpB",
"name": "Bank Of America Pref GG ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BACpQ",
"name": "Bank Of America Pref QQ ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BMLpG",
"name": "Bank Of America Pref 1 ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BACpO",
"name": "Bank Of America Pref NN ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BACpL",
"name": "Bank Of America Pref L",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BACpP",
"name": "Bank Of America Pref PP ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BACpS",
"name": "Bank Of America Pref SS ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BMLpL",
"name": "Bank Of America Pref 5 ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BACpM",
"name": "Bank Of America Pref KK ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BACpE",
"name": "Bank Of America Pref E ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BMLpH",
"name": "Bank Of America Pref 2 ADR",
"security_tag": "stock",
"exchange": "NYSE"
},
{
"ticker": "BACpK",
"name": "Bank Of America Pref HH ADR",
"security_tag": "stock",
"exchange": "NYSE"
}
]
},
"status_code": 0,
"status_msg": "success"
}
```
# Stock dividends
Source: https://docs.ainvest.com/reference/securities/stock-dividends
reference/securities/securities.yaml GET /securities/stock/financials/dividends
Get dividends for a specified stock
ETFs are not supported yet
# Stock earning reports
Source: https://docs.ainvest.com/reference/securities/stock-earnings
reference/securities/securities.yaml GET /securities/stock/financials/earnings
Get earnings reports for a specified stock, including revenue, earnings per share, and links to relevant SEC documents and investor call recordings.
# Company financials
Source: https://docs.ainvest.com/reference/securities/stock-financials
reference/securities/securities.yaml GET /securities/stock/financials
Get financial metrics of a stock, including earnings per share, net profit, operating income, etc.
# Stock financial statements
Source: https://docs.ainvest.com/reference/securities/stock-statements
reference/securities/securities.yaml GET /securities/stock/financials/statements
Get financial statements for a specified stock, including income statements, balance sheet, and cash flow statements.
This API provides income statements, balance sheets, and cashflow statements. The data points are presented as name value pairs.
The names are consistent across all items. Not all reports have the same data points, in this case the name still presents in the array but the value is null.
### Income statements
| line |
| ------------------------------------------------------------------------ |
| 1. Revenue |
| --- 2. Sales and Services Revenue |
| --- 3. Financing Services Revenue |
| --- 4. Other Revenue |
| 5. Cost of Revenue |
| --- 6. Cost of Goods and Services |
| --- 7. Cost of Financing Services |
| --- 8. Other Cost |
| 9. Gross Profit |
| 10. Other Operating Income |
| 11. Operating Expenses |
| --- 12. Selling, General and Administrative Expenses |
| ------ 13. Selling and Marketing Expenses |
| ------ 14. General and Administrative Expenses |
| --- 15. Research and Development Expenses |
| --- 16. Loss on Bad Debts |
| --- 17. Loss on Impairment of Other Assets |
| --- 18. Loss on Disposal of Assets |
| --- 19. Other Operating Expenses |
| 20. Operating Income |
| 21. Non-Operating Income (Loss) |
| --- 22. Income (Loss) from Affiliates |
| ------ 23. Income (Loss) from Associates |
| ------ 24. Income (Loss) from Joint ventures |
| --- 25. Gain (Loss) on Other Investment |
| --- 26. Gain (Loss) on Change in Fair Value |
| --- 27. Gain (Loss) on Foreign Currency Exchange |
| --- 28. Other Non-Operating Income (Loss) |
| --- 29. Net Interest Expense |
| ------ 30. Interest Expense |
| ------ 31. Interest Income |
| 32. Pretax Income From Continuing Operations |
| 33. Income Tax Expense |
| --- 34. Current Income Tax |
| --- 35. Deferred Income Tax |
| --- 36. Income Tax Adjustments |
| 37. Net Income from Continuing Operations |
| 38. Income from Discontinued Operations |
| 39. Other Items Before Net Income |
| 40. Net Income |
| --- 41. Net Income Attributable to Minority Interests |
| --- 42. Net Income Attributable to Owners of the Company |
| ------ 43. Preferred Stock Dividends |
| ------ 44. Other Adjustments |
| ------ 45. Net Income Attributable to Common Stockholders |
| 46. Other Comprehensive Income |
| 47. Total Comprehensive Income |
| --- 48. Total Comprehensive Income Attributable to Minority Interests |
| --- 49. Total Comprehensive Income Attributable to Owners of the Company |
| 50. Basic EPS |
| --- 51. Basic EPS from Continuing Operations |
| --- 52. Basic EPS from Discontinued Operations |
| 53. Diluted EPS |
| --- 54. Diluted EPS from Continuing Operations |
| --- 55. Diluted EPS from Discontinued Operations |
### Cashflow statements
| line |
| ---------------------------------------------------------------------------------- |
| 1. Net Cash Flows from Operating Activities |
| --- 2. Net Income |
| --- 3. Depreciation and Amortization |
| --- 4. Stock-based Compensation |
| --- 5. Deferred Taxs |
| --- 6. Interest Income(expense) |
| --- 7. Impairment of Assets |
| --- 8. Change in Working Capital |
| ------ 9. Change in Accounts Receivable |
| ------ 10. Change in Inventories |
| ------ 11. Change in Accounts Payable |
| ------ 12. Change in Prepaid Expenses |
| ------ 13. Change in Contract liabilities |
| ------ 14. Change in Deferred Revenue |
| ------ 15. Change in Other Working Capital |
| --- 16. Other Non-cash Adjustments |
| --- 17. Net Cash from Discontinued Operating Activities |
| 18. Net Cash Flows from Investing Activities |
| --- 19. Change in PPE and Intangible Assets |
| ------ 20. Disposal of PPE and Intangible Assets |
| ------ 21. Purchase of PPE and Intangible Assets |
| --- 22. Change in Investments |
| ------ 23. Decrease in Investments |
| ------ 24. Increase in Investments |
| --- 25. Change in long-term Equity Investments |
| ------ 26. Change in Associates and Joint Ventures |
| ------ 27. Change in Subsidiaries |
| --- 28. Dividends Received |
| --- 29. Interest Received |
| --- 30. Other Investing Activities |
| --- 31. Net Cash from Discontinued Investing Activities |
| 32. Net Cash Flows from Financing Activities |
| --- 33. Dividends Paid |
| --- 34. Change in Debt |
| ------ 35. Issuance of Short-term Debt |
| ------ 36. Repayment of Short-term Debt |
| ------ 37. Issuance of long-term Debt |
| ------ 38. Repayment of long-term Debt |
| --- 39. Change in Capital Stock |
| ------ 40. Increase in Capital Stock |
| ------ 41. Decrease in Capital Stock |
| --- 42. Interest Paid |
| --- 43. Other Financing Activities |
| --- 44. Net Cash from Discontinued Financing Activities |
| --- 45. Effect of Foreign Exchange Rate Changes |
| --- 46. Other Accounts Affecting Net Increase in Cash and Cash Equivalents |
| 47. Net Increase in Cash and Cash Equivalents |
| 48. Cash and Cash Equivalents at Beginning of Period |
| --- 59. Other Accounts that Affect the Ending Balance of Cash and Cash Equivalents |
| 50. Cash and Cash Equivalents at End of Period |
### Balance sheets
| line |
| -------------------------------------------------------- |
| 1. Total Assets |
| 2. Total Current Assets |
| --- 3. Cash, Cash Equivalents and Short-term Investments |
| ------ 4. Cash and Cash Equivalents |
| ------ 5. Short-term Investments |
| --- 6. Restricted Deposits and Cash |
| --- 7. Receivables |
| ------ 8. Accounts and Notes Receivable |
| ------ 9. Income Taxes Receivable |
| ------ 10. Other Receivables |
| ------ 11. Amounts Due from Related Parties |
| --- 12. Inventories |
| ------ 13. Raw Materials |
| ------ 14. Work in Process |
| ------ 15. Finished Goods |
| ------ 16. Other Inventory |
| --- 17. Derivative Financial Assets(current) |
| --- 18. Prepaid Expenses(current) |
| --- 19. Assets Held for Sale |
| --- 20. Contract Assets(current) |
| --- 21. Other Current Assets |
| 22. Total Non-current Assets |
| --- 23. Property, Plant and Equipment, Net |
| ------ 24. Gross Property, Plant and Equipment |
| ------ 25. Accumulated Depreciation |
| --- 26. Long-term Investments and Receivables |
| ------ 27. Long-term Investments |
| ------ 28. Long-term Receivables |
| --- 29. Goodwill and Intangible Assets |
| ------ 30. Goodwill |
| ------ 31. Intangible Assets |
| --- 32. Investment Properties |
| --- 33. Derivative Financial Assets(non-current) |
| --- 34. Prepaid Expenses(non-current) |
| --- 35. Prepaid Pension Costs |
| --- 36. Contract Assets(non-current) |
| --- 37. Deferred Tax Assets |
| --- 38. Investments in Affiliates |
| ------ 39. Investments in Associates |
| ------ 40. Investments in Joint Ventures |
| --- 41. Other Non-current Assets |
| 42. Total liabilities |
| 43. Total Current Liabilities |
| --- 44. Short-term Debt |
| ------ 45. Short-term Borrowings |
| ------ 46. Short-term Lease Liabilities |
| ------ 47. Current Portion of Long-term Debt |
| --- 48. Amounts Due to Related Parties |
| ------ 49. Accounts and Notes Payable |
| ------ 50. Income taxes payable |
| ------ 51. Interest and Dividends Payable |
| ------ 52. Other Payables and Accruals |
| ------ 53. Amounts Due to Related Parties |
| --- 54. Derivative Financial Liabilities(current) |
| --- 55. Liabilities Held for Sale |
| --- 56. Advances from customers(current) |
| --- 57. Deferred Revenue(current) |
| --- 58. Contract Liabilities(current) |
| --- 59. Other Current Liabilities |
| 60. Total Non-current Liabilities |
| --- 61. Long-term debt |
| ------ 62. Long-term borrowings |
| ------ 63. Long-term Lease Liabilities |
| --- 64. Accrued Liabilities |
| --- 65. Pension Liabilities |
| ------ 66. Pensions |
| ------ 67. Other Post-ret Benefits |
| --- 68. Deferred Compensation |
| --- 69. Derivative Financial Liabilities(non-current) |
| --- 70. Deferred Tax Liabilities |
| --- 71. Advances from customers(non-current) |
| --- 72. Deferred Revenue(non-current) |
| --- 73. Contract Liabilities(non-current) |
| --- 74. Other Non-current Liabilities |
| 75. Total Equity |
| --- 76. Equity Attributable to Minority Interests |
| 77. Equity Attributable to Owners of the Company |
| --- 78. Preferred Equity |
| --- 79. Hybrid Capital |
| --- 80. Equity Attributable to Common Stockholders |
| ------ 81. Common Stock |
| ------ 82. Additional Paid in Capital |
| ------ 83. Retained Earnings |
| ------ 84. Treasury Stock |
| ------ 85. Accumulated Other Comprehensive Income |
| ------ 86. Other Equity of Common Stockholders |
| 87. Total Liabilities and Equity |
# Automation
Source: https://docs.ainvest.com/terminal/automations
Create recurring market monitors with natural language.
Automation turns a plain-language request into a monitor that runs repeatedly. Use it for price and volume conditions, market events, screeners, earnings, and other checks you do not want to repeat manually.
## Create a monitor
Open **Automation**, then select **New automation**. You can also start from an example.
Write the request in one sentence. Include the symbol, event or threshold, when it should be checked, and what the notification should contain.
AInvest interprets the request, plans the trigger conditions, and creates the monitor.
Open the monitor to verify its schedule, source, trigger condition, and next run.
## Manage a monitor
The Automation page shows monitors being created and those currently running. Open a monitor to view the original request, AI-generated condition, and run history. Use the available controls to run it, edit it, change its settings, or stop it.
Each AI run consumes Credits. More frequent monitors can use Credits more quickly.
# Changelog
Source: https://docs.ainvest.com/terminal/changelog
See recent AInvest Terminal releases and open the complete release history.
For the latest version, complete release notes, and full release history, visit the [AInvest Terminal changelog](https://www.ainvest.com/terminal/changelog/).
# Chat
Source: https://docs.ainvest.com/terminal/chat
Ask questions, choose how AInvest should work, and organize related conversations.
Chat is the main place to ask AInvest for market research, company analysis, comparisons, summaries, and follow-up work.
## Start a conversation
Select **New chat** from the sidebar.
Include the ticker or market, the relevant time period, and the question you want answered. Add supporting context when needed.
Select an available AIME model and adjust the reasoning level from faster to smarter.
Follow the working status, then check the answer, sources, and timestamps. Ask a follow-up question to refine the result.
## Use the composer
From the composer, you can add context, use voice input, choose a project, select a model, and adjust the reasoning level. Check the permission mode before sending requests that may use connected tools or data. You can stop a response while it is running.
## Home market overview
The Chat start screen provides a quick view of major indices, the global market heatmap, U.S. sectors, active stocks, and current news. Use it to identify a topic, then ask AInvest to investigate it in a new conversation.
## Projects and conversations
Use projects to keep conversations about the same company, strategy, or research goal together. Continue a recent conversation from the sidebar, or archive chats you no longer need from **Settings > Archived chats**.
Chat messages and any AI tools used during the conversation consume Credits.
# Credits and Rewards
Source: https://docs.ainvest.com/terminal/credits
Understand Credits, check usage, and earn or add more.
Credits are the usage balance for AI features in AInvest Terminal. Chat and any other action that calls AI consume Credits, including AI work in Trading Studio, Automation, and Extensions.
## Check your Credits
Open the account menu, then select **Usage**. The Usage page shows your current balance, Credits used during the selected period, individual Credit grants or packs, and their expiration dates when applicable. You can switch between 7, 30, and 90-day views.
## Earn Credits in Rewards
Open **Rewards** in the lower-left corner to see the tasks available to your account.
* Invite friends with your personal link or invitation code.
* Earn additional rewards when invited friends register, sign in to AInvest Terminal, or complete a qualifying purchase.
* Unlock milestone rewards by inviting the required number of friends.
* Share content you created with AInvest on an eligible social platform, then submit the post link for verification.
* Complete available social-channel tasks and claim the reward.
Open Rewards and review its requirements and current reward.
Follow the task action, such as copying an invitation link, following a channel, or publishing a post.
Provide verification when requested. Claim the Credits when the task becomes eligible.
## Add more Credits
Select **Credit Booster Packs** or **Upgrade** from the account menu to view the options currently available to your account. Booster packs add Credits without changing how you use Terminal.
Tasks, eligibility rules, reward amounts, prices, and expiration terms can change. Always follow the current details shown in Terminal.
# Extensions
Source: https://docs.ainvest.com/terminal/extensions
Manage plugins, specialized skills, and MCP connections.
Extensions expand what AInvest can do. Open **Extensions** from the sidebar to manage three types of capabilities.
| Type | What it adds |
| ------- | ---------------------------------------------------------------------------------------------------------- |
| Plugins | Product workflows such as Automation, Browser Use, and Trading Studio |
| Skills | Specialized instructions for financial research, screening, portfolio analysis, planning, and web research |
| MCP | Connections to external tools and data sources |
## Manage extensions
Switch between **Plugins**, **Skills**, and **MCP** at the top of the page.
Search by name or description and use the category filter when available. A checkmark identifies an installed item.
Use **Add** to install an available extension. For MCP, select **Add server** and enter the connection details provided by the service.
Describe your task in Chat or the relevant workspace. AInvest can use the installed capability when it matches your request.
Only connect services you trust, and review the access they receive. AI work performed through extensions consumes Credits.
# AInvest Terminal
Source: https://docs.ainvest.com/terminal/overview
Learn the core workflows in AInvest's desktop AI investing workspace.
AInvest Terminal combines AI conversations, financial research, live market workspaces, and recurring monitoring in one desktop app.
## Choose a workflow
Ask market questions, analyze ideas, and continue related work in projects.
Build a multi-panel financial workspace with AI and market components.
Manage plugins, financial skills, and MCP connections.
Create monitors that run repeatedly and notify you when conditions are met.
## Get started
Name the company, ticker, market, or event, then describe the result you need.
Use Chat for analysis, Trading Studio for visual workflows, and Automation for ongoing monitoring.
Check sources, timestamps, assumptions, and any proposed action before relying on the output.
## Account and settings
Open the account menu in the lower-left corner to manage your profile, view Credit usage, change language or appearance, and sign out.
Select **Settings** for model and provider options, investment memory, keyboard shortcuts, Browser use, AI Pet, and archived chats. Investment memory can reuse your investing preferences across Chat and Trading Studio, and can be disabled or reset at any time.
AI features use Credits. Open **Usage** to check your current balance, usage, and any expiration dates.
# Trading Studio
Source: https://docs.ainvest.com/terminal/trading-studio
Build and control a multi-panel financial workspace with AI.
Trading Studio is an AI financial workstation. Describe what you want to study, and AInvest can assemble the relevant market components on a flexible canvas.
## Build a workspace with AI
Open **Trading Studio** and select a template or tab, such as Stock Research, Day Trading, Screener, Market Research, Options, or Earnings.
Use the AI panel to name the symbol and explain what you want to monitor or compare.
AInvest adds and configures components on the canvas. Confirm the symbols, time ranges, filters, and data shown.
Ask AI for changes, or move, expand, replace, and close components directly on the canvas.
## Add market components
Open the component library, then click a component to add it to an empty location or drag it onto the canvas. Available components include charts, watchlists, quotes, market heatmaps, news, calendars, screeners, company and ownership data, options, portfolio views, P\&L, and trading tools.
Components can be arranged into multiple tabs and linked around the same symbol, allowing one workspace to combine price action, events, news, fundamentals, and portfolio context.
Market data and AI output may be delayed or incomplete. Verify the symbol, timestamp, account, and every order detail before making an investment or submitting a trade.
# Heat Map
Source: https://docs.ainvest.com/widgets/api-reference/heat-map
Interactive market-performance map grouped by symbol, sector, size, and percentage change.
Heat Map turns a market universe into an interactive visual overview. Tile size, grouping, and color help users understand where performance and market weight are concentrated before opening a specific security.
## Properties
### Common properties
| Name | Type | Required | Default | Description |
| ----------------- | ---------------------------- | -------- | ------------ | -------------------------------------------------------------------------- |
| `theme` | `"light" or "dark"` | No | `light` | Visual theme applied inside the widget iframe. |
| `locale` | `string` | No | `en` | Locale used by labels, formatting, and component copy when supported. |
| `colorPreference` | `"GreenForUp" or "RedForUp"` | No | `GreenForUp` | Controls whether green or red represents positive price movement. |
| `autoHeight` | `boolean` | No | `true` | Enables ResizeObserver-driven iframe height updates through `postMessage`. |
### Widget properties
| Name | Type | Required | Default | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------- | ------------------------------------------ |
| `marketType` | `"Stock" or "ETF" or "Crypto"` | No | `Stock` | Market tab and universe type. |
| `dataSource` | `"sp500" or "nasdaq100" or "nasdaq_composite" or "nyse_composite" or "all_stocks" or "dji" or "etf" or "crypto" or "crypto_ex_btc"` | No | `sp500` | Dataset used to build the heatmap. |
| `sizeBy` | `"market_cap" or "aum" or "mono_size"` | No | `market_cap` | Metric used to size each tile. |
| `colorBy` | `"change_pct_1h" or "change_pct_4h" or "change_pct_d" or "change_pct_24h" or "change_pct_w" or "change_pct_m" or "change_pct_3m" or "change_pct_6m" or "change_pct_ytd" or "change_pct_1y" or "pre_market_chg" or "post_market_chg" or "volatility_d" or "gap"` | No | `change_pct_d` | Metric used for tile color. |
| `groupBy` | `"None" or "sector" or "asset_class"` | No | `sector` | Grouping dimension for the heatmap layout. |
| `showTab` | `boolean` | No | `true` | Shows or hides the market type tabs. |
| `title` | `string` | No | \`\` | Optional title rendered by the widget. |
## Events
| Event | Payload | Description |
| ------------------ | ---------------------------------------------- | --------------------------------------- |
| `marketTypeChange` | `{ marketType: "Stock" or "ETF" or "Crypto" }` | Fired when the market type tab changes. |
## When to use Heat Map
* Market and sector overview pages where visual pattern recognition matters
* Index pages that need market-cap-weighted performance context
* Discovery dashboards where selecting a tile opens deeper analysis
* Editorial pages that explain broad participation or sector divergence
Use [Top List](/widgets/api-reference/top-list) when users need exact ranking, sorting, and tabular comparison.
## Core experience
The map should identify its universe, grouping dimension, tile-size metric, color metric, session, and last-update time. Keep a visible legend and display a numeric value inside or alongside each selectable tile.
Tile area and color must represent separate, clearly labeled metrics. Avoid making small tiles impossible to focus, read, or select.
## Data and visualization states
Support loading, empty-universe, no-filter-results, delayed-data, market-closed, entitlement, reconnecting, and error states. Keep the legend synchronized with the actual color scale after filters or metrics change.
If values are unavailable for part of the universe, use a neutral unavailable state rather than mapping missing data to zero performance.
## Responsive behavior
At smaller widths, reduce label density while preserving numeric values for focused or selected tiles. Provide a list or detail panel for tiles that are too small to label. Keep filters and the legend visible without creating horizontal page scrolling.
## Accessibility
* Color must not be the only way performance is communicated.
* Give each tile an accessible label containing symbol, group, and numeric value.
* Provide keyboard navigation and visible focus for selectable tiles.
* Use a color scale with sufficient contrast and a neutral midpoint.
* Offer an equivalent textual or tabular summary when required.
## Best practices
* Choose a familiar market universe and label it prominently.
* Keep the color range stable enough for meaningful comparison.
* Avoid excessive filters that leave only a few disconnected tiles.
* Pair tile selection with a quote or chart for further analysis.
* Test color contrast, missing data, small tiles, and empty filters.
## Related widgets
* [Top List](/widgets/api-reference/top-list) adds an exact ranking beside the visual overview.
* [Super Chart](/widgets/api-reference/super-chart) opens a selected tile in a detailed chart.
# Market Calendar
Source: https://docs.ainvest.com/widgets/api-reference/market-calendar
Scheduled earnings and market events with timing, estimates, actuals, and surprise context.
Market Calendar organizes scheduled events into a daily or weekly view. It is designed to help users understand when earnings, economic releases, dividends, splits, or other supported market catalysts are expected.
## Properties
### Common properties
| Name | Type | Required | Default | Description |
| ----------------- | ---------------------------- | -------- | ------------ | -------------------------------------------------------------------------- |
| `theme` | `"light" or "dark"` | No | `light` | Visual theme applied inside the widget iframe. |
| `locale` | `string` | No | `en` | Locale used by labels, formatting, and component copy when supported. |
| `colorPreference` | `"GreenForUp" or "RedForUp"` | No | `GreenForUp` | Controls whether green or red represents positive price movement. |
| `autoHeight` | `boolean` | No | `true` | Enables ResizeObserver-driven iframe height updates through `postMessage`. |
### Widget properties
| Name | Type | Required | Default | Description |
| ------------------ | ---------------------------- | -------- | ---------- | ----------------------------------- |
| `initialDataType` | `"earnings" or "economic"` | No | `earnings` | Event category shown on first load. |
| `initialViewMode` | `"day" or "week" or "month"` | No | `week` | Calendar view shown on first load. |
| `variant` | `"tiny" or "loose"` | No | `tiny` | Calendar density and spacing. |
| `hideDateSelector` | `boolean` | No | `false` | Hides the date selector controls. |
## Events
| Event | Payload | Description |
| ------------- | --------------------------------------- | ------------------------------------------------------------ |
| `symbolClick` | `{ symbol: string; exchange?: string }` | Fired when a security symbol inside an event row is clicked. |
## When to use Market Calendar
* Earnings hubs and scheduled-event pages
* Portfolio or watchlist tools that need upcoming catalysts
* Trading dashboards that separate pre-market and post-market events
* Editorial workflows that contextualize market-moving dates
## Core experience
Every event should communicate its date, event type, entity or symbol, applicable reporting period, session timing, and current status. Earnings events may include EPS and revenue estimates, actual values, and surprise calculations when available.
Use a clearly stated timezone for all dates and session labels. Distinguish confirmed values from estimates and pending reports.
## Data and event states
Support loading, empty-date, no-filter-results, upcoming, reported, postponed, cancelled, delayed-data, entitlement, and error states. When an actual value has not been reported, keep the field explicitly pending rather than substituting zero.
If event timing changes, show the latest status and avoid silently moving an event without updating its label.
## Responsive behavior
On smaller screens, group events by day and prioritize event name, symbol, timing, and status. Move secondary estimates or surprise metrics into an expandable detail view. Preserve date navigation without requiring horizontal page scrolling.
## Accessibility
* Do not rely on calendar position alone to communicate an event date.
* Provide accessible labels for date navigation and filter controls.
* Identify estimate, actual, surprise, and pending values in text.
* Make event rows reachable and actionable by keyboard.
* Use a descriptive iframe title and a visible timezone label.
## Best practices
* Default to the event type that matches the page's primary intent.
* State the timezone and visible date range near the top of the widget.
* Avoid combining unrelated event types when it reduces scannability.
* Preserve the user's date and filter state during data refreshes.
* Test weeks with no events, postponed reports, and missing estimates.
## Related widgets
* [News Wire](/widgets/api-reference/news-wire) pairs scheduled events with timely market coverage.
* [Top List](/widgets/api-reference/top-list) shows securities moving around major catalysts.
# News Wire
Source: https://docs.ainvest.com/widgets/api-reference/news-wire
Timely market headlines with related securities, timestamps, and live price context.
News Wire delivers a continuously updated stream of market headlines. It combines timestamped coverage with related symbols and price movement so users can quickly understand what changed and which securities may be affected.
## Properties
### Common properties
| Name | Type | Required | Default | Description |
| ----------------- | ---------------------------- | -------- | ------------ | -------------------------------------------------------------------------- |
| `theme` | `"light" or "dark"` | No | `light` | Visual theme applied inside the widget iframe. |
| `locale` | `string` | No | `en` | Locale used by labels, formatting, and component copy when supported. |
| `colorPreference` | `"GreenForUp" or "RedForUp"` | No | `GreenForUp` | Controls whether green or red represents positive price movement. |
| `autoHeight` | `boolean` | No | `true` | Enables ResizeObserver-driven iframe height updates through `postMessage`. |
### Widget properties
| Name | Type | Required | Default | Description |
| ----------------- | --------- | -------- | ------- | ------------------------------------------------------------------- |
| `pageSize` | `number` | No | `20` | Number of news items requested per page. Valid range: `1` to `100`. |
| `pollingEnabled` | `boolean` | No | `true` | Enables periodic refresh for new headlines. |
| `pollingInterval` | `number` | No | `30000` | Polling interval in milliseconds. Valid range: `5000` to `300000`. |
## Events
| Event | Payload | Description |
| --------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| `itemClick` | `{ newsId: string; title: string; sourceUrl: string; source?: string; publishTime: string or number }` | Fired when a news item is clicked. |
| `stockTagClick` | `{ symbol: string; exchange?: string; name?: string }` | Fired when a related stock tag is clicked. |
| `itemExposed` | `{ newsId: string; insertTime?: number }` | Fired when a news item is exposed. |
| `signInClick` | `{}` | Fired when the sign-in action is clicked. |
## When to use News Wire
* Trading workspaces where headline speed and ticker context matter
* Symbol pages filtered to company-specific coverage
* Market homepages combining stocks, crypto, and macro news
* Event pages that need timely coverage around scheduled catalysts
## Core experience
Each item should include a readable headline, timestamp, source or content identity where applicable, and related securities. Price movement is supporting context and should never replace the meaning of the headline.
Clearly identify the timezone and whether the feed is live, reconnecting, delayed, or filtered. Preserve already loaded headlines during a reconnect when possible.
## Content and connection states
Support loading, reconnecting, empty-filter, delayed-feed, entitlement, rate-limit, and error states. Do not remove already readable headlines during temporary connection loss.
If no headlines match the current filters, explain the filter state and provide a clear recovery path. Avoid presenting placeholder headlines as real market news.
## Responsive behavior
On narrow screens, prioritize timestamp, headline, and the most relevant symbol. Move secondary price context into a compact metadata row. Headlines should wrap naturally without creating nested horizontal scrolling.
## Accessibility
* Use descriptive link text based on the full headline.
* Include timezone information with timestamps.
* Ensure symbol and price metadata do not interrupt headline reading order.
* Preserve visible focus as new items arrive.
* Avoid aggressive live-region announcements for every headline update.
## Best practices
* Select a feed that matches the page's audience and market scope.
* Keep timestamps and related symbols visually consistent.
* Avoid auto-scrolling when new headlines arrive.
* Open external stories with predictable link behavior.
* Test reconnecting, no-results, rate-limit, and high-frequency update states.
## Related widgets
* [Quick Quote](/widgets/api-reference/quick-quote) adds current price and session context beside headlines.
* [Market Calendar](/widgets/api-reference/market-calendar) pairs real-time coverage with scheduled events.
# Quick Quote
Source: https://docs.ainvest.com/widgets/api-reference/quick-quote
Compact regular-session and extended-hours quote with essential trading statistics.
Quick Quote provides a focused snapshot of one security, including the latest price, price change, market session, extended-hours context, daily range, volume, and other supported trading statistics.
## Properties
### Common properties
| Name | Type | Required | Default | Description |
| ----------------- | ---------------------------- | -------- | ------------ | -------------------------------------------------------------------------- |
| `theme` | `"light" or "dark"` | No | `light` | Visual theme applied inside the widget iframe. |
| `locale` | `string` | No | `en` | Locale used by labels, formatting, and component copy when supported. |
| `colorPreference` | `"GreenForUp" or "RedForUp"` | No | `GreenForUp` | Controls whether green or red represents positive price movement. |
| `autoHeight` | `boolean` | No | `true` | Enables ResizeObserver-driven iframe height updates through `postMessage`. |
### Widget properties
| Name | Type | Required | Default | Description |
| ---------- | --------- | -------- | ------------- | ---------------------------------------------- |
| `symbol` | `string` | Yes | `AAPL:NASDAQ` | Active security in `SYMBOL:EXCHANGE` format. |
| `hideLogo` | `boolean` | No | `false` | Hides the AInvest logo area in the quote card. |
## When to use Quick Quote
* Symbol headers and compact stock-detail summaries
* Article, news, portfolio, or watchlist sidebars
* Multi-widget workspaces that need lightweight price context
* Pages where a full interactive chart would be unnecessarily heavy
Use [Super Chart](/widgets/api-reference/super-chart) when users need historical exploration, intervals, indicators, or drawing tools.
## Core experience
The primary quote should clearly identify the symbol, exchange, company, price, change, market session, and timestamp. When the market is closed, keep the latest regular-session close as the primary value and display pre-market or post-market values as labeled secondary information.
Statistics should use consistent units and abbreviations. Never mix delayed and real-time values without an explicit status label.
## Data and session states
Support loading, invalid-symbol, delayed-data, market-closed, extended-hours, entitlement, reconnecting, and error states. Preserve the last valid quote during brief reconnects and label it as potentially stale.
Price, change, and timestamp must refer to the same session. If extended-hours values are unavailable, hide the row rather than showing a misleading zero.
## Responsive behavior
At narrow widths, prioritize symbol, latest price, price change, market session, and timestamp. Secondary statistics may wrap into a compact grid or collapse behind a disclosure control. Avoid truncating the security symbol or price.
## Accessibility
* Give the iframe a descriptive title that includes the active widget name.
* Ensure updated prices remain readable without excessive screen-reader announcements.
* Pair positive and negative colors with signs, labels, or icons.
* Keep timestamps and session labels available to assistive technologies.
* Provide visible focus for clickable symbol and company elements.
## Best practices
* Use an exchange-qualified symbol when the production contract supports it.
* Show extended-hours information only when it is relevant and available.
* Reserve enough height for statistics to avoid layout shift.
* Keep the quote synchronized with the surrounding symbol page.
* Test market-open, market-closed, invalid-symbol, and reconnecting states.
## Related widgets
* [Super Chart](/widgets/api-reference/super-chart) adds historical and technical-analysis context.
* [News Wire](/widgets/api-reference/news-wire) shows timely headlines for the same security.
# Super Chart
Source: https://docs.ainvest.com/widgets/api-reference/super-chart
Advanced financial chart for price analysis, indicators, drawings, volume, and extended-hours context.
Super Chart brings AInvest's full market-analysis experience into an embeddable component. It is designed for workflows where users need to explore price history, compare intervals, apply technical studies, and inspect regular or extended-hours movement.
## Properties
### Common properties
| Name | Type | Required | Default | Description |
| ----------------- | ---------------------------- | -------- | ------------ | -------------------------------------------------------------------------- |
| `theme` | `"light" or "dark"` | No | `light` | Visual theme applied inside the widget iframe. |
| `locale` | `string` | No | `en` | Locale used by labels, formatting, and component copy when supported. |
| `colorPreference` | `"GreenForUp" or "RedForUp"` | No | `GreenForUp` | Controls whether green or red represents positive price movement. |
| `autoHeight` | `boolean` | No | `true` | Enables ResizeObserver-driven iframe height updates through `postMessage`. |
### Widget properties
| Name | Type | Required | Default | Description |
| -------- | -------------------------------------------------------------------- | -------- | ------------- | -------------------------------------------- |
| `symbol` | `string` | Yes | `AAPL:NASDAQ` | Active security in `SYMBOL:EXCHANGE` format. |
| `period` | `"day_1" or "week_1" or "month_1" or "min_1" or "min_5" or "hour_1"` | No | `day_1` | Initial chart period. |
## Events
| Event | Payload | Description |
| ------- | -------------------------------------- | -------------------------------------------- |
| `ready` | `{ symbol: string; exchange: string }` | Fired when the Super Chart runtime is ready. |
## When to use Super Chart
* Stock detail and research pages where technical analysis is the primary task
* Trading dashboards that need indicators, drawings, volume, and session context
* Symbol workspaces where chart changes should coordinate with quotes or news
* Educational or editorial pages that require an interactive historical-price view
For compact contexts where the latest price matters more than historical analysis, use [Quick Quote](/widgets/api-reference/quick-quote).
## Core experience
Super Chart should provide a clear symbol and exchange identity, visible interval state, readable OHLC values, volume context, and consistent positive or negative price colors. Technical studies and drawing tools should remain discoverable without overwhelming the chart canvas.
If extended-hours data is available, distinguish it visually from the regular session and label the applicable market session and timestamp.
## Data and market states
Support explicit loading, delayed-data, market-closed, empty-series, entitlement, reconnecting, and error states. During a reconnect, preserve the last valid chart when possible and show that the data may be stale.
Never display pre-market or post-market values as regular-session prices. Every delayed or non-regular session value should include a visible label and timestamp.
## Responsive behavior
Use a minimum container height of approximately `480px` for basic analysis and more space for full trading workspaces. On narrow screens, collapse secondary controls into menus, preserve symbol and interval controls, and keep the plot area interactive.
Avoid horizontal page scrolling. Tool menus and drawing controls should remain reachable by touch and keyboard.
## Accessibility
* Give the iframe a descriptive title that includes “AInvest Super Chart.”
* Provide keyboard access to symbols, intervals, studies, and drawing controls.
* Do not communicate price direction using color alone.
* Maintain sufficient contrast for grid lines, candles, labels, and focus states.
* Provide readable text alternatives for key price and session values.
## Best practices
* Place Super Chart in the primary content column rather than a narrow sidebar.
* Reserve container height before loading to prevent layout shift.
* Keep the active symbol synchronized with surrounding page context.
* Avoid preloading an excessive number of studies on first render.
* Test market-open, market-closed, delayed-data, and invalid-symbol scenarios.
## Related widgets
* [Quick Quote](/widgets/api-reference/quick-quote) adds compact quote and session context for the active symbol.
* [News Wire](/widgets/api-reference/news-wire) shows headlines related to the security being analyzed.
# Top List
Source: https://docs.ainvest.com/widgets/api-reference/top-list
Ranked market lists for gainers, losers, active stocks, new highs, and other discovery workflows.
Top List helps users discover securities through ranked market presets. It can surface gainers, losers, active stocks, new highs, pre-market movement, or another supported screening result in a compact, scannable table.
## Properties
### Common properties
| Name | Type | Required | Default | Description |
| ----------------- | ---------------------------- | -------- | ------------ | -------------------------------------------------------------------------- |
| `theme` | `"light" or "dark"` | No | `light` | Visual theme applied inside the widget iframe. |
| `locale` | `string` | No | `en` | Locale used by labels, formatting, and component copy when supported. |
| `colorPreference` | `"GreenForUp" or "RedForUp"` | No | `GreenForUp` | Controls whether green or red represents positive price movement. |
| `autoHeight` | `boolean` | No | `true` | Enables ResizeObserver-driven iframe height updates through `postMessage`. |
### Widget properties
| Name | Type | Required | Default | Description |
| ------------ | ------------------------------------------------------------------------------------------- | -------- | ------------- | ---------------------------------------------------- |
| `assetType` | `"stock" or "etf" or "crypto"` | Yes | `stock` | Asset universe used by the ranking list. |
| `listType` | `"top_gainers" or "top_losers" or "most_active" or "best_performing" or "worst_performing"` | No | `top_gainers` | Ranking preset shown in the list. |
| `defaultTab` | `"overview" or "valuation" or "performance" or "dividends" or "technical"` | No | `overview` | Initial metrics tab. |
| `rowCount` | `number` | No | `50` | Number of rows requested. Valid range: `1` to `200`. |
## Events
| Event | Payload | Description |
| ---------- | ------------------------------------------------------ | ------------------------------------ |
| `rowClick` | `{ symbol: string; exchange?: string; name?: string }` | Fired when a ranking row is clicked. |
## When to use Top List
* Market homepages that need a fast view of leading or unusual securities
* Pre-market and post-market discovery workflows
* Trading dashboards where selecting a row opens deeper symbol analysis
* Editorial pages that need a live ranking beside market commentary
Use [Heat Map](/widgets/api-reference/heat-map) when the goal is broad visual pattern recognition rather than an exact rank order.
## Core experience
Every list should identify its preset, market, session, ranking metric, and last-update time. Keep symbol, price, and the primary ranking value visible at all supported widths. Sorting and row selection must not obscure the meaning of the active preset.
When the selected session is closed, retain the latest valid ranking and label the session instead of presenting the list as live.
## Data and ranking states
Support loading, empty-result, market-closed, delayed-data, reconnecting, entitlement, and rate-limit states. If a preset returns no securities, explain whether the result is caused by filters, session timing, or data availability.
Rank changes should not cause disruptive row movement while the user is reading or interacting. Apply stable update behavior and preserve the selected row when possible.
## Responsive behavior
On small screens, keep symbol, price, and the ranking metric visible. Move secondary columns into an expandable row or detail view instead of forcing horizontal scrolling. Maintain comfortable tap targets for row selection and preset controls.
## Accessibility
* Use a semantic table or equivalent accessible grid structure.
* Announce the active preset and sort order.
* Provide row labels that include symbol, company name, rank, and primary metric.
* Do not rely on red and green alone to communicate gains or losses.
* Preserve visible keyboard focus during live ranking updates.
## Best practices
* Choose one primary ranking preset that matches the page's user intent.
* Show a clear session label for pre-market, regular, and post-market data.
* Limit visible rows to the space available and avoid nested scrolling where possible.
* Pair row selection with a chart or quote when deeper analysis is expected.
* Test empty filters, thinly traded sessions, and rapid ranking updates.
## Related widgets
* [Super Chart](/widgets/api-reference/super-chart) opens the selected security in a full analysis chart.
* [Heat Map](/widgets/api-reference/heat-map) adds a visual view of the same market universe.
# Watchlist
Source: https://docs.ainvest.com/widgets/api-reference/watchlist
Personalized security list for tracking symbols, prices, movement, and market context.
Watchlist helps users monitor selected securities in one place. It is designed for portfolio-adjacent workflows, market tracking, and symbol lists that need quick price context before opening deeper analysis.
## Properties
### Common properties
| Name | Type | Required | Default | Description |
| ----------------- | ---------------------------- | -------- | ------------ | -------------------------------------------------------------------------- |
| `theme` | `"light" or "dark"` | No | `light` | Visual theme applied inside the widget iframe. |
| `locale` | `string` | No | `en` | Locale used by labels, formatting, and component copy when supported. |
| `colorPreference` | `"GreenForUp" or "RedForUp"` | No | `GreenForUp` | Controls whether green or red represents positive price movement. |
| `autoHeight` | `boolean` | No | `true` | Enables ResizeObserver-driven iframe height updates through `postMessage`. |
### Widget properties
| Name | Type | Required | Default | Description |
| --------------- | ------------------- | -------- | ------- | ------------------------------------------------------------------------- |
| `styleVariant` | `"tiny" or "loose"` | No | `tiny` | Watchlist density and row spacing. |
| `activeGroupId` | `string` | No | \`\` | Watchlist group to open by default. Leave empty to use the default group. |
| `hideTabs` | `boolean` | No | `false` | Hides the watchlist group tabs. |
## Events
| Event | Payload | Description |
| ---------- | ------------------------------------ | -------------------------------------- |
| `rowClick` | `{ symbol: string; market: string }` | Fired when a watchlist row is clicked. |
## When to use Watchlist
* Portfolio, account, or research dashboards that need a saved symbol list
* Market workspaces where users repeatedly return to the same securities
* Sidebars that coordinate a selected symbol with charts, quotes, or news
* Pages that need compact price movement across multiple user-selected names
Use [Top List](/widgets/api-reference/top-list) when the list should be generated from a ranking preset rather than a saved or curated symbol set.
## Core experience
Each row should identify the symbol, company or asset name, latest price, price change, market session, and timestamp. Keep the selected symbol clear when Watchlist drives a surrounding chart, quote, or news component.
## Data and market states
Support loading, empty-list, invalid-symbol, delayed-data, market-closed, entitlement, reconnecting, and error states. If a list is empty, provide a direct recovery path instead of showing inactive rows.
## Responsive behavior
On narrow screens, prioritize symbol, price, change, and session. Secondary columns can collapse into a detail row or compact metadata area. Avoid horizontal page scrolling.
## Accessibility
* Use row labels that include symbol, company name, price, and movement.
* Do not rely on color alone for positive and negative changes.
* Preserve visible focus for row actions and selected symbols.
* Keep price updates readable without excessive live announcements.
* Give the iframe a descriptive title that includes “AInvest Watchlist.”
## Best practices
* Keep the default symbol list short enough to scan.
* Preserve row order while users are reading live updates.
* Synchronize row selection with related widgets when used in a dashboard.
* Test empty lists, invalid symbols, delayed data, and reconnecting states.
## Related widgets
* [Super Chart](/widgets/api-reference/super-chart) opens the selected security in a full analysis chart.
* [Quick Quote](/widgets/api-reference/quick-quote) shows compact quote details for the selected symbol.
# Changelog
Source: https://docs.ainvest.com/widgets/changelog
Track AInvest Widgets documentation and integration contract updates.
This changelog records material changes to the Widgets documentation, iframe integration, public configuration, authentication model, and component behavior.
## Unreleased
### Added
* Added a dedicated `Widgets` navigation tab to the AInvest Mintlify documentation structure.
* Added Documentation pages for Getting Started and Changelog.
* Added API Reference pages for Super Chart, Watchlist, Top List, Quick Quote, Market Calendar, Heat Map, and News Wire.
* Added working preview iframes for all seven widgets.
* Added common properties, widget-specific properties, and supported event callbacks supplied by the widget implementation.
### Pending production integration
* Confirm the browser-safe credential and domain restriction model.
* Confirm error codes, versioning, and market-data entitlement behavior.
Use a dated release heading only after a change is deployed to the production documentation site.
# Getting Started
Source: https://docs.ainvest.com/widgets/getting-started
Plan, configure, and integrate your first AInvest Widget.
AInvest Widgets are embeddable financial components for charts, quotes, market discovery, scheduled events, market visualization, and news. Each API Reference page combines product guidance with a developer-provided configurator iframe.
## Before you begin
Prepare the following before integrating a production widget:
* The domain or application where the widget will appear
* The component and minimum container size required by the page layout
* A browser-safe Widget credential approved for the intended domains
* A plan for loading, empty, delayed-data, authorization, and reconnecting states
Never expose an existing `sk-...` server API key in browser code, an iframe URL, a mobile bundle, or a public repository.
## Integration flow
Use the component guide below to select the widget that matches the user's primary task.
Open the component's API Reference page. Use the embedded configurator to select data, appearance, dimensions, and supported behaviors.
Copy the implementation produced by the configurator. The final loader URL, attributes, and framework examples are supplied by the production Widget service.
Test the widget at desktop and mobile breakpoints, verify domain authorization, and exercise all loading and failure states before release.
## Choose the right component
| User need | Recommended widget |
| --------------------------------------------------- | --------------------------------------------------------- |
| Technical analysis and historical price exploration | [Super Chart](/widgets/api-reference/super-chart) |
| Track a saved or curated set of securities | [Watchlist](/widgets/api-reference/watchlist) |
| Discover leading, active, or unusual securities | [Top List](/widgets/api-reference/top-list) |
| Show a compact security snapshot | [Quick Quote](/widgets/api-reference/quick-quote) |
| Track earnings and scheduled market events | [Market Calendar](/widgets/api-reference/market-calendar) |
| Understand broad market or sector performance | [Heat Map](/widgets/api-reference/heat-map) |
| Follow timely market-moving headlines | [News Wire](/widgets/api-reference/news-wire) |
## Plan the container
Widgets should follow the width of their parent container. Give the container an explicit height so the page remains stable while the iframe loads. Avoid nesting widgets inside containers that change size continuously or hide overflow needed for menus and tooltips.
For multi-widget dashboards, use a responsive CSS Grid or Flexbox layout. Stack components vertically at smaller breakpoints and keep the primary analysis component above supporting context.
## Production checklist
* Confirm the production iframe origin, loader, and credential contract with engineering.
* Allow the required iframe origin in Content Security Policy and frame restrictions.
* Restrict browser credentials to approved production and preview domains.
* Use a descriptive `title` for every iframe and preserve keyboard navigation.
* Reserve sufficient height to prevent layout shift during initialization.
* Verify market-closed, delayed-data, empty, authorization, rate-limit, and reconnecting states.
* Test theme contrast, mobile density, localization, and timestamp clarity.
## Next steps
Track documentation changes and pending production integrations.
Explore a live widget preview, its properties, and integration guidance.