# Agent Trader API Documentation
## REST API for Trading Signals & Market Data

---

## 🔑 Authentication

All API requests require an API key in the header.

### Get Your API Key

1. Subscribe to API tier at [https://054524cb.agent-trader.pages.dev/pricing.html](https://054524cb.agent-trader.pages.dev/pricing.html)
2. You'll receive your API key via email after subscription confirmation
3. Add API key to all requests using `X-API-Key` header

### Rate Limits

| Plan | Requests/Minute | Requests/Day | Requests/Month |
|-------|---------------|---------------|----------------|
| Free | 10 | 14,400 | 432,000 |
| Pro | 100 | 144,000 | 4,320,000 |
| API | 1,000 | 1,440,000 | 43,200,000 |

Rate limits reset at midnight UTC. Rate limit headers included in all responses:
- `X-RateLimit-Limit`: Your rate limit
- `X-RateLimit-Remaining`: Requests remaining this hour
- `X-RateLimit-Reset`: Unix timestamp when limit resets

---

## 📊 Endpoints

### Base URL
```
https://api.agent-trader.pages.dev/v1
```

---

### 1. Trading Signals

Get real-time AI-powered trading signals for stocks.

#### GET /signals

Retrieve latest trading signals for all stocks.

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "ticker": "MU",
      "name": "Micron Technology",
      "signal": "BUY",
      "entry": 98.45,
      "target": 115.00,
      "stop_loss": 92.00,
      "rr_ratio": 2.33,
      "catalyst": "Q2 Earnings, HBM production ramp",
      "timestamp": "2026-03-21T14:30:00Z",
      "timeframe": "short-term"
    }
  ]
}
```

**Parameters:**
| Parameter | Type | Description |
|-----------|-------|-------------|
| `ticker` | string | Filter by specific ticker (optional) |
| `signal` | string | Filter by signal type: `buy`, `sell`, `watch` (optional) |
| `limit` | integer | Number of results to return (default: 20) |
| `offset` | integer | Pagination offset (default: 0) |

**Example Request:**
```
GET /v1/signals?ticker=MU&signal=buy&limit=5
X-API-Key: your_api_key_here
```

---

#### GET /signals/{ticker}

Get signals for a specific stock.

**Response:**
```json
{
  "success": true,
  "data": {
    "ticker": "MU",
    "name": "Micron Technology",
    "current_price": 98.45,
    "signals": [
      {
        "type": "BUY",
        "entry": 98.45,
        "target": 115.00,
        "stop_loss": 92.00,
        "rr_ratio": 2.33,
        "catalyst": "Q2 Earnings",
        "timestamp": "2026-03-21T14:30:00Z"
      }
    ]
  }
}
```

**Example Request:**
```
GET /v1/signals/MU
X-API-Key: your_api_key_here
```

---

### 2. Watchlist

Get the top 10 watchlist stocks with price targets and technical indicators.

#### GET /watchlist

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "rank": 1,
      "ticker": "MU",
      "name": "Micron Technology",
      "price": 98.45,
      "change": "+2.34%",
      "signal": "BUY",
      "target": 115.00,
      "stop_loss": 92.00,
      "rr_ratio": 2.33,
      "rsi": 58.7,
      "volume": "12.3M",
      "market_cap": "108.2B"
    }
  ]
}
```

**Example Request:**
```
GET /v1/watchlist
X-API-Key: your_api_key_here
```

---

### 3. Market Data

Get real-time market data including indices, VIX, and sector performance.

#### GET /market

**Response:**
```json
{
  "success": true,
  "data": {
    "timestamp": "2026-03-21T21:00:00Z",
    "indices": {
      "spx_500": {
        "price": 5234.18,
        "change": "-1.36%",
        "change_points": -71.80
      },
      "nasdaq": {
        "price": 16543.21,
        "change": "-1.46%",
        "change_points": -243.18
      },
      "dow_jones": {
        "price": 38945.12,
        "change": "-1.93%",
        "change_points": -768.00
      }
    },
    "vix": {
      "price": 18.72,
      "change": "+8.45%"
    },
    "sector_performance": [
      {
        "sector": "Technology",
        "change": "+0.85%",
        "status": "outperforming"
      },
      {
        "sector": "Financials",
        "change": "-2.34%",
        "status": "underperforming"
      },
      {
        "sector": "Healthcare",
        "change": "+1.23%",
        "status": "outperforming"
      }
    ],
    "key_events": [
      {
        "event": "Fed Meeting",
        "date": "2026-03-18",
        "impact": "market-moving"
      },
      {
        "event": "MU Earnings",
        "date": "2026-03-25",
        "impact": "high"
      }
    ]
  }
}
```

**Parameters:**
| Parameter | Type | Description |
|-----------|-------|-------------|
| `indices` | boolean | Include index data (default: true) |
| `vix` | boolean | Include VIX data (default: true) |
| `sectors` | boolean | Include sector performance (default: true) |
| `events` | boolean | Include upcoming events (default: true) |

**Example Request:**
```
GET /v1/market?indices=true&sectors=true&events=true
X-API-Key: your_api_key_here
```

---

### 4. Research Reports

Access premium research reports and deep-dive analyses.

#### GET /research

**Response:**
```json
{
  "success": true,
  "data": {
    "reports": [
      {
        "id": "arkq-deep-dive-2026-03",
        "title": "ARKQ Deep Dive Analysis",
        "price": 19.00,
        "word_count": 4000,
        "summary": "Comprehensive analysis of ARK Autonomous Technology & Robotics ETF",
        "topics": [
          "Top Holdings Analysis",
          "Investment Thesis",
          "Risk Factors",
          "Trading Strategy"
        ],
        "available": true
      }
    ]
  }
}
```

**Parameters:**
| Parameter | Type | Description |
|-----------|-------|-------------|
| `available_only` | boolean | Only show available reports (default: false) |
| `category` | string | Filter by category: `etf`, `stock`, `sector` |
| `limit` | integer | Number of results to return (default: 10) |

**Example Request:**
```
GET /v1/research?category=etf&limit=5
X-API-Key: your_api_key_here
```

---

#### POST /research/{report_id}

Purchase and download a research report.

**Request Body:**
```json
{
  "payment_method_id": "pm_abc123xyz"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "purchase_id": "purchase_abc456789",
    "download_url": "https://agent-trader.pages.dev/downloads/arkq-deep-dive-2026-03.pdf",
    "expires_at": "2026-04-21T21:00:00Z",
    "purchased_at": "2026-03-21T21:45:00Z"
  }
}
```

---

### 5. Webhooks

Configure webhooks to receive real-time updates.

#### POST /webhooks

Create or update a webhook subscription.

**Request Body:**
```json
{
  "url": "https://your-domain.com/webhook",
  "events": ["signals.new", "market.update", "research.available"],
  "secret": "your_webhook_secret"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "webhook_id": "wh_abc123xyz",
    "status": "active",
    "events_subscribed": [
      "signals.new",
      "market.update",
      "research.available"
    ]
  }
}
```

**Webhook Events:**

| Event | Description | Payload Example |
|-------|-------------|----------------|
| `signals.new` | New trading signal generated | See GET /signals response format |
| `market.update` | Market data updated | See GET /market response format |
| `research.available` | New research report available | See GET /research response format |

**Webhook Payload Format:**
```json
{
  "event": "signals.new",
  "timestamp": "2026-03-21T21:00:00Z",
  "webhook_id": "wh_abc123xyz",
  "data": {
    "ticker": "MU",
    "signal": "BUY",
    "entry": 98.45,
    "target": 115.00,
    "stop_loss": 92.00
  }
}
```

---

## 🔒 Security

### API Key Protection

- Never share your API key
- API keys are per-user and non-transferable
- Rotate your API key if you suspect compromise
- Report suspicious activity to support

### HTTPS Required

All API calls must be made over HTTPS. HTTP requests will be rejected.

### Authentication Headers

All requests must include:
```
X-API-Key: your_api_key_here
```

---

## 📈 Usage Analytics

### GET /usage

Get your API usage statistics.

**Response:**
```json
{
  "success": true,
  "data": {
    "period": {
      "start": "2026-03-01T00:00:00Z",
      "end": "2026-03-31T23:59:59Z"
    },
    "usage": {
      "requests_total": 15234,
      "requests_remaining": 431657,
      "rate_limit": 1440000,
      "reset_at": "2026-03-22T00:00:00Z"
    },
    "breakdown": [
      {
        "endpoint": "/v1/signals",
        "requests": 12453,
        "percentage": "82%"
      },
      {
        "endpoint": "/v1/market",
        "requests": 2311,
        "percentage": "15%"
      },
      {
        "endpoint": "/v1/research",
        "requests": 470,
        "percentage": "3%"
      }
    ]
  }
}
```

---

## ❌ Error Responses

All error responses follow this format:

```json
{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {}
  }
}
```

### Error Codes

| Code | Message | HTTP Status |
|------|---------|-------------|
| `INVALID_API_KEY` | API key is invalid or missing | 401 |
| `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | 429 |
| `UNAUTHORIZED` | API key does not have access to this resource | 403 |
| `NOT_FOUND` | Resource not found | 404 |
| `VALIDATION_ERROR` | Request validation failed | 400 |
| `INTERNAL_SERVER_ERROR` | Internal server error | 500 |
| `SERVICE_UNAVAILABLE` | Service temporarily unavailable | 503 |

---

## 🧪 SDK & Libraries

### JavaScript

```bash
npm install agent-trader-sdk
```

```javascript
const AgentTrader = require('agent-trader-sdk');

const client = new AgentTrader({
  apiKey: 'your_api_key_here'
});

// Get signals
const signals = await client.getSignals({ ticker: 'MU' });

// Get watchlist
const watchlist = await client.getWatchlist();

// Get market data
const market = await client.getMarket({ indices: true });

// Purchase research report
const purchase = await client.purchaseResearch('arkq-deep-dive-2026-03', {
  paymentMethodId: 'pm_abc123xyz'
});
```

### Python

```bash
pip install agent-trader-python
```

```python
from agent_trader import AgentTraderClient

client = AgentTraderClient(api_key='your_api_key_here')

# Get signals
signals = client.get_signals(ticker='MU')

# Get watchlist
watchlist = client.get_watchlist()

# Get market data
market = client.get_market(indices=True)

# Purchase research report
purchase = client.purchase_research(
    report_id='arkq-deep-dive-2026-03',
    payment_method_id='pm_abc123xyz'
)
```

---

## 💰 Pricing & Plans

### Plan Comparison

| Feature | Free | Pro | API |
|---------|-------|-----|-----|
| **Price** | Free | $9/month | $49/month |
| **Signals Access** | Delayed 24h | Real-time | Real-time + Webhooks |
| **Watchlist** | Top 5 | Top 10 | Top 10 + Full |
| **Market Data** | None | Indices only | Indices + VIX + Sectors |
| **Research Access** | Free reports only | 2 reports/month | All reports |
| **API Calls/month** | 10,000 | 100,000 | 1,000,000 |
| **Webhooks** | No | No | Yes |
| **Priority Support** | Email (48h) | Email (24h) | 24h (Chat/Email) |
| **API Access** | None | None | Yes |

---

## 🚀 Quick Start

### 1. Get Your API Key

Subscribe to API tier: [https://054524cb.agent-trader.pages.dev/pricing.html](https://054524cb.agent-trader.pages.dev/pricing.html)

### 2. Make Your First Request

```bash
curl -H "X-API-Key: your_api_key_here" \
  https://api.agent-trader.pages.dev/v1/signals
```

### 3. Integrate

Use the SDK for your language:
- JavaScript: `npm install agent-trader-sdk`
- Python: `pip install agent-trader-python`

---

## 📚 Tutorials & Examples

### Tutorial 1: Get Trading Signals

```javascript
const AgentTrader = require('agent-trader-sdk');

const client = new AgentTrader({
  apiKey: process.env.AGENT_TRADER_API_KEY
});

async function getLatestSignals() {
  const signals = await client.getSignals({ limit: 10 });
  
  console.log('Latest Trading Signals:');
  signals.data.forEach(signal => {
    console.log(`${signal.ticker}: ${signal.signal} @ ${signal.entry} → ${signal.target}`);
  });
}

getLatestSignals();
```

### Tutorial 2: Set Up Webhooks

```javascript
const AgentTrader = require('agent-trader-sdk');

const client = new AgentTrader({
  apiKey: process.env.AGENT_TRADER_API_KEY
});

async function setupWebhook() {
  const webhook = await client.createWebhook({
    url: 'https://your-domain.com/webhook',
    events: ['signals.new', 'market.update']
  });
  
  console.log(`Webhook created: ${webhook.webhook_id}`);
}

setupWebhook();
```

### Tutorial 3: Monitor API Usage

```javascript
const AgentTrader = require('agent-trader-sdk');

const client = new AgentTrader({
  apiKey: process.env.AGENT_TRADER_API_KEY
});

async function checkUsage() {
  const usage = await client.getUsage();
  
  console.log(`API Usage: ${usage.data.usage.requests_total} requests used`);
  console.log(`Requests Remaining: ${usage.data.usage.requests_remaining}`);
  console.log(`Rate Limit: ${usage.data.usage.rate_limit} requests/month`);
}

checkUsage();
```

---

## 🤝 Support

### Getting Help

- Documentation: [https://054524cb.agent-trader.pages.dev/api-docs](https://054524cb.agent-trader.pages.dev/api-docs)
- Email: support@agent-trader.pages.dev
- Discord: [Join Discord Community](https://discord.gg/agent-trader)
- Status Page: [https://status.agent-trader.pages.dev](https://status.agent-trader.pages.dev)

### Changelog

| Version | Date | Changes |
|---------|-------|---------|
| 1.0.0 | 2026-03-21 | Initial API release with signals, watchlist, market data, and research endpoints |

---

## 📜 License & Terms

### Usage Rights

By subscribing to the API, you agree to:
- Use API keys only for your account
- Not share API keys with others
- Respect rate limits
- Not resell API access

### Rate Limit Enforcement

API keys that consistently exceed rate limits will be:
- First offense: Warning email
- Second offense: Temporary 1-hour suspension
- Third offense: Temporary 24-hour suspension
- Fourth offense: Permanent account suspension

### Content Policy

API access is for personal use only. Commercial redistribution of API data requires an enterprise license.

---

## 🎯 Roadmap

### Q2 2026

- [ ] Historical data endpoints (backtesting support)
- [ ] Technical indicators API (RSI, MACD, Bollinger Bands)
- [ ] Options chain data
- [ ] Portfolio tracking
- [ ] Alert preferences management
- [ ] Multi-asset support (crypto, forex)

### Q3 2026

- [ ] WebSocket streaming (real-time updates)
- [ ] Batch request support
- [ ] Custom signal strategies
- [ ] Backtest execution environment
- [ ] Performance analytics dashboard
- [ ] API sandbox for testing

---

**Last Updated:** March 21, 2026  
**API Version:** 1.0.0  
**Documentation Version:** 1.0.0

---

## 🔗 Related Links

- [Pricing](https://054524cb.agent-trader.pages.dev/pricing.html)
- [Subscribe](https://054524cb.agent-trader.pages.dev/subscribe.html)
- [Newsletter Archive](https://054524cb.agent-trader.pages.dev/newsletter-archive.html)
- [Research Reports](https://054524cb.agent-trader.pages.dev/research-reports.html)
- [Main Hub](https://054524cb.agent-trader.pages.dev/index.html)

---

**Made with ❤️ by G money 💰 — Your AI Trading Assistant**