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

# US Stock Analyst

> Create US stock reports from financials, filings, news, and sentiment.

[View on GitHub ->](https://github.com/AIsa-team/agent-skills/tree/main/us-stock-analyst)

**Equity research reports for agents.** Pull financials, news, filings, sentiment, and model synthesis into one US stock analysis workflow.

## Install

First, install the AIsa CLI if you have not already:

```bash theme={null}
npm install -g @aisa-one/cli
```

Then install the skill:

```bash theme={null}
aisa skills install us-stock-analyst
```

## What can agents do with it?

<CardGroup cols={2}>
  <Card title="Equity reports" icon="file-invoice-dollar">
    Create structured analysis for US-listed stocks.
  </Card>

  <Card title="Filing context" icon="file-lines">
    Use SEC filings and company disclosures.
  </Card>

  <Card title="Sentiment synthesis" icon="comments">
    Add news and social signal context.
  </Card>

  <Card title="Investment memo" icon="clipboard-list">
    Summarize risks, catalysts, and watch items.
  </Card>
</CardGroup>

## 🔥 What Can You Do?

### Investment Research

```
"Analyze NVDA: financial metrics, analyst estimates, insider trades, 
news sentiment, and AI-powered valuation"
```

### Portfolio Monitoring

```
"Track my portfolio (AAPL, MSFT, GOOGL): daily updates on metrics, 
news, and sentiment changes"
```

### Earnings Analysis

```
"Full Tesla Q4 earnings analysis: results vs estimates, guidance, 
price reaction, analyst updates"
```

### Competitor Analysis

```
"Compare AMD vs NVDA: financials, growth, valuation, market sentiment"
```

### Screening & Discovery

```
"Find tech stocks with P/E < 30, revenue growth > 20%, 
and positive insider activity"
```

## Quick Start

```bash theme={null}
export AISA_API_KEY="your-key"
```

***

## Core Capabilities

### 📊 Financial Data (MarketPulse APIs)

**Real-time Financial Metrics**

```bash theme={null}
curl "https://api.aisa.one/apis/v1/financial/financial-metrics/snapshot?ticker=AAPL" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

Returns: Market cap, P/E ratio, revenue, EPS, profit margin, ROE, debt/equity, and more.

**Historical Stock Prices**

```bash theme={null}
# Daily prices for last 30 days
curl "https://api.aisa.one/apis/v1/financial/prices?ticker=AAPL&start_date=2025-01-01&end_date=2025-01-31&interval=day&interval_multiplier=1" \
  -H "Authorization: Bearer $AISA_API_KEY"

# 5-minute intraday data
curl "https://api.aisa.one/apis/v1/financial/prices?ticker=AAPL&start_date=2025-02-07&end_date=2025-02-07&interval=minute&interval_multiplier=5" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

**Financial Statements**

```bash theme={null}
# All statements (income, balance, cash flow)
curl "https://api.aisa.one/apis/v1/financial/financial_statements/all?ticker=AAPL" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

**Analyst Estimates**

```bash theme={null}
# EPS forecasts and ratings
curl "https://api.aisa.one/apis/v1/financial/analyst/eps?ticker=AAPL&period=annual" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

**Insider Trading**

```bash theme={null}
# Track insider buy/sell activity
curl "https://api.aisa.one/apis/v1/financial/insider/trades?ticker=AAPL" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

**Institutional Ownership**

```bash theme={null}
# See who owns the stock
curl "https://api.aisa.one/apis/v1/financial/institutional/ownership?ticker=AAPL" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

**SEC Filings**

```bash theme={null}
# Access 10-K, 10-Q, 8-K filings
curl "https://api.aisa.one/apis/v1/financial/sec/filings?ticker=AAPL" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

***

### 📰 News & Research

**Company News**

```bash theme={null}
curl "https://api.aisa.one/apis/v1/financial/news?ticker=AAPL&limit=10" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

**Web Search (News & Articles)**

```bash theme={null}
curl -X POST "https://api.aisa.one/apis/v1/scholar/search/web?query=AAPL+stock+analysis&max_num_results=10" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

**Academic Research**

```bash theme={null}
curl -X POST "https://api.aisa.one/apis/v1/scholar/search/scholar?query=semiconductor+industry+analysis&max_num_results=5" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

***

### 🐦 Social Sentiment

**Twitter Search**

```bash theme={null}
curl "https://api.aisa.one/apis/v1/twitter/tweet/advanced_search?query=\$AAPL&queryType=Latest" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

***

### 📺 Video Content

**YouTube Search (Earnings Calls, Analysis)**

```bash theme={null}
curl "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=AAPL+earnings+call&gl=us&hl=en" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

***

### 🤖 AI Analysis (Multi-Model)

**LLM Gateway (OpenAI Compatible)**

```bash theme={null}
curl -X POST "https://api.aisa.one/v1/chat/completions" \
  -H "Authorization: Bearer $AISA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {
        "role": "system",
        "content": "You are a professional equity analyst."
      },
      {
        "role": "user",
        "content": "Analyze Apple stock investment prospects"
      }
    ],
    "temperature": 0.3,
    "max_tokens": 2000
  }'
```

**Supported Models:**

* GPT-4, GPT-4 Turbo (OpenAI)
* Claude 3 Opus, Sonnet, Haiku (Anthropic)
* Gemini 1.5 Pro, Ultra (Google)
* Qwen Max, Plus (Alibaba)
* DeepSeek V2 (DeepSeek)
* Grok (xAI)

***

## Python Client

```bash theme={null}
# Basic analysis
python3 scripts/stock_analyst.py analyze --ticker AAPL

# Standard analysis with multiple models
python3 scripts/stock_analyst.py analyze --ticker NVDA --depth standard --models gpt-4 claude-3-opus

# Deep analysis (all data sources)
python3 scripts/stock_analyst.py analyze --ticker TSLA --depth deep

# Quick screening
python3 scripts/stock_analyst.py analyze --ticker MSFT --depth quick

# Save report to file
python3 scripts/stock_analyst.py analyze --ticker GOOGL --output report.json
```

***

## Analysis Depth Options

| Mode         | Time  | Cost        | Data Sources                                 |
| ------------ | ----- | ----------- | -------------------------------------------- |
| **quick**    | \~10s | \$0.01-0.02 | Metrics, News, Twitter, Basic AI             |
| **standard** | \~20s | \$0.02-0.05 | + Analyst Estimates, Insider Trades, YouTube |
| **deep**     | \~30s | \$0.05-0.10 | + Statements, Institutional, SEC, Research   |

***

## API Reference

| Category              | Endpoint                                | Method | Cost        |
| --------------------- | --------------------------------------- | ------ | ----------- |
| **Financial Metrics** | `/financial/financial-metrics/snapshot` | GET    | \$0.002     |
| **Stock Prices**      | `/financial/prices`                     | GET    | \$0.001     |
| **News**              | `/financial/news`                       | GET    | \$0.001     |
| **Statements**        | `/financial/financial_statements/*`     | GET    | \$0.002     |
| **Analyst Estimates** | `/financial/analyst/eps`                | GET    | \$0.002     |
| **Insider Trades**    | `/financial/insider/trades`             | GET    | \$0.001     |
| **Institutional**     | `/financial/institutional/ownership`    | GET    | \$0.001     |
| **SEC Filings**       | `/financial/sec/filings`                | GET    | \$0.001     |
| **Web Search**        | `/scholar/search/web`                   | POST   | \$0.001     |
| **Scholar Search**    | `/scholar/search/scholar`               | POST   | \$0.002     |
| **Twitter**           | `/twitter/tweet/advanced_search`        | GET    | \$0.0004    |
| **YouTube**           | `/youtube/search`                       | GET    | \$0.002     |
| **LLM**               | `/v1/chat/completions`                  | POST   | Token-based |

Every response includes `usage.cost` and `usage.credits_remaining`.

***

## Example Output

```json theme={null}
{
  "ticker": "NVDA",
  "analysis_date": "2025-02-07T10:30:00Z",
  
  "investment_summary": "NVIDIA maintains dominant position in AI chip market with strong data center revenue growth. Recent Blackwell launch positions company for continued expansion...",
  
  "key_metrics": {
    "market_cap": 1780500000000,
    "pe_ratio": 68.5,
    "revenue": 60922000000,
    "revenue_growth": 1.26,
    "profit_margin": 0.489,
    "roe": 1.152
  },
  
  "sentiment_analysis": {
    "sentiment": "bullish",
    "confidence": "high",
    "key_themes": ["AI dominance", "Data center growth", "Blackwell launch"],
    "summary": "Overwhelmingly positive sentiment following Q4 earnings beat"
  },
  
  "valuation": {
    "assessment": "fairly_valued",
    "price_target_12m": 850.00,
    "reasoning": "Premium valuation justified by AI market leadership and strong growth trajectory"
  },
  
  "data_sources": {
    "Financial Metrics": "Available",
    "Stock News": 10,
    "Analyst Estimates": "Available",
    "Insider Trades": 15,
    "Twitter": "Available",
    "YouTube": 5
  }
}
```

***

## Pricing

**Analysis Costs:**

* Quick: \$0.01-0.02 per stock
* Standard: \$0.02-0.05 per stock
* Deep: \$0.05-0.10 per stock

**Comparison:**

* Bloomberg Terminal: \$2,000/month
* FactSet: \$1,000/month
* Traditional Analyst Report: \$50-500 each
* **AIsa Stock Analyst: \$0.02-0.10 each** ✨

**Cost Breakdown:**

```
Standard Analysis ($0.02-0.05):
├── Financial Metrics: $0.002
├── Stock Prices: $0.001
├── Company News: $0.001
├── Analyst Estimates: $0.002
├── Insider Trades: $0.001
├── Twitter: $0.0004
├── YouTube: $0.002
└── LLM Analysis: $0.01-0.04
```

***

## Use Cases

### 1. Investment Research

Screen and analyze stocks before investing:

```python theme={null}
analyst.analyze_stock("NVDA", depth="deep")
```

### 2. Portfolio Monitoring

Daily updates on your holdings:

```python theme={null}
for ticker in ["AAPL", "MSFT", "GOOGL"]:
    report = analyst.analyze_stock(ticker, depth="quick")
```

### 3. Earnings Season

Comprehensive earnings analysis:

```python theme={null}
analyst.analyze_stock("TSLA", depth="standard")
# Check estimates, actual results, guidance, reaction
```

### 4. Insider Tracking

Monitor insider activity:

```python theme={null}
report = analyst.analyze_stock("META", depth="standard")
print(report['raw_data']['insider_trades'])
```

### 5. Sentiment Analysis

Track market perception:

```python theme={null}
report = analyst.analyze_stock("COIN", depth="standard")
print(report['sentiment_analysis'])
```

***

## Compliance

**Disclaimer (Always Included):**

> This analysis is for informational purposes only and should not be
> considered personalized investment advice. Please conduct your own
> research and consult with licensed financial advisors before making
> investment decisions.

**Regulatory Compliance:**

* SEC Rule 15c2-1 (not investment advice)
* FINRA regulations (informational only)
* GDPR data privacy compliant

***

## Get Started

1. Sign up at [aisa.one](https://aisa.one)
2. Get your API key
3. Add credits (pay-as-you-go, minimum \$5)
4. Set environment variable: `export AISA_API_KEY="your-key"`
5. Run analysis: `python scripts/stock_analyst.py analyze --ticker AAPL`

***

## Full API Documentation

* **API Reference**: [https://aisa.one/docs/api-reference](https://aisa.one/docs/api-reference)
* **Complete Docs**: [https://aisa.one/docs/llms.txt](https://aisa.one/docs/llms.txt)
* **Support**: [support@aisa.one](mailto:support@aisa.one)
* **Discord**: [https://discord.gg/aisa](https://discord.gg/aisa)

***

## About AIsa

**AIsa** - Unified API infrastructure for AI agents.

Single API Key. Pay-Per-Use. Agent-Native.

* Website: [https://aisa.one](https://aisa.one)
* Documentation: [https://aisa.one/docs](https://aisa.one/docs)

## Get started

1. Sign up at [aisa.one](https://aisa.one) (new accounts start with \$2 free credit).
2. Generate an API key from the console.
3. Set your key and install the skill:
   ```bash theme={null}
   export AISA_API_KEY="your-key"
   npm install -g @aisa-one/cli
   aisa skills install us-stock-analyst
   ```
4. Start a new agent session so the runtime loads the updated skill instructions.

## Related

<CardGroup cols={3}>
  <Card title="MarketPulse" icon="chart-line" href="/agent-skills/marketpulse">
    Deep financial and filing data.
  </Card>

  <Card title="Stock & Crypto Analysis" icon="file-chart-line" href="/agent-skills/stock-analysis">
    General asset analysis workflow.
  </Card>

  <Card title="Financial API reference" icon="code" href="/api-reference/financial/get_analyst-estimates">
    Underlying financial endpoint docs.
  </Card>
</CardGroup>