API_EXAMPLES.md

# API Usage Examples

This document provides practical examples for testing each API endpoint.

## 1. Health Check

**Request:**
```bash
curl http://localhost:5000/health
```

**Response:**
```json
{
  "status": "ok"
}
```

---

## 2. Get Market Information

**Request:**
```bash
curl -X POST http://localhost:5000/api/market-info \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://polymarket.com/event/will-biden-pardon-hunter-biden"
  }'
```

**Response:**
```json
{
  "id": "...",
  "question": "Will Biden pardon Hunter Biden?",
  "conditionId": "...",
  "clobTokenIds": ["..."],
  "firstTokenId": "..."
}
```

---

## 3. Convert EST to Unix

**Request:**
```bash
curl -X POST http://localhost:5000/api/time/est-to-unix \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "2025-11-15 14:30:00"
  }'
```

**Response:**
```json
{
  "unix_timestamp": 1763210400,
  "est_datetime": "2025-11-15 14:30:00 EST"
}
```

---

## 4. Convert Unix to EST

**Request:**
```bash
curl -X POST http://localhost:5000/api/time/unix-to-est \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": 1763210400
  }'
```

**Response:**
```json
{
  "unix_timestamp": 1763210400,
  "est_datetime": "2025-11-15 14:30:00 EST"
}
```

---

## 5. Get Price History

**Request:**
```bash
curl -X POST http://localhost:5000/api/price-history \
  -H "Content-Type: application/json" \
  -d '{
    "token_id": "52607315900507156846622820770453728082833251091510131025984187712529448877245",
    "start_time": "2025-11-14 10:00:00",
    "end_time": "2025-11-14 16:00:00",
    "fidelity": 60,
    "granularity": 60
  }'
```

**Response:**
```json
{
  "token_id": "...",
  "start_unix": 1234567890,
  "end_unix": 1234567900,
  "start_time": "2025-11-14 10:00:00 EST",
  "end_time": "2025-11-14 16:00:00 EST",
  "fidelity": 60,
  "granularity": 60,
  "raw_history_count": 50,
  "timeseries_count": 360,
  "raw_history": [
    {"t": 1234567890, "p": 0.45}
  ],
  "timeseries": [
    {"timestamp": 1234567890, "price": 0.45}
  ]
}
```

---

## 6. Analyze Correlations (LLM)

**Request:**
```bash
curl -X POST http://localhost:5000/api/analyze-correlations \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Will the Federal Reserve cut interest rates in December 2025?"
  }'
```

**Response:**
```json
{
  "question": "Will the Federal Reserve cut interest rates in December 2025?",
  "correlated": [
    {
      "ticker": "TLT",
      "reason": "Long-term Treasury bonds typically rise when interest rates are cut"
    },
    {
      "ticker": "XLF",
      "reason": "Financial sector stocks often react positively to rate cuts"
    }
  ],
  "inversely_correlated": [
    {
      "ticker": "DXY",
      "reason": "US Dollar typically weakens when Fed cuts rates"
    },
    {
      "ticker": "BND",
      "reason": "Bond yields fall with rate cuts, causing inverse price movement"
    }
  ]
}
```

---

## 7. Fetch Asset Prices

**Request:**
```bash
curl -X POST http://localhost:5000/api/fetch-asset-prices \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "AAPL",
    "start_time": "2025-11-14 10:00:00",
    "end_time": "2025-11-14 16:00:00",
    "interval": "1h"
  }'
```

**Response:**
```json
{
  "ticker": "AAPL",
  "start_time": "2025-11-14 10:00:00",
  "end_time": "2025-11-14 16:00:00",
  "interval": "1h",
  "data_points": 6,
  "timeseries": [
    {"timestamp": 1234567890, "price": 150.25},
    {"timestamp": 1234571490, "price": 151.30}
  ]
}
```

---

## 8. Full Analysis (Complete Workflow)

This is the **main endpoint** that combines all the functionality.

**Request:**
```bash
curl -X POST http://localhost:5000/api/analyze-full \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://polymarket.com/event/will-biden-pardon-hunter-biden",
    "start_time": "2025-11-01 00:00:00",
    "end_time": "2025-11-14 23:59:59",
    "granularity": 60
  }'
```

**Response:**
```json
{
  "market_info": {
    "id": "...",
    "question": "Will Biden pardon Hunter Biden?",
    "token_id": "..."
  },
  "time_range": {
    "start": "2025-11-01 00:00:00",
    "end": "2025-11-14 23:59:59",
    "start_unix": 1234567890,
    "end_unix": 1234567900,
    "granularity": 60
  },
  "polymarket_data": [
    {"timestamp": 1234567890, "price": 0.45}
  ],
  "polymarket_data_normalized": [
    {"timestamp": 1234567890, "price": 0.45, "original_price": 0.45}
  ],
  "correlated_assets": [
    {
      "ticker": "SPY",
      "reason": "...",
      "correlation": 0.75,
      "data_points": 150,
      "timeseries": [...],
      "normalized_timeseries": [...],
      "success": true
    }
  ],
  "inversely_correlated_assets": [
    {
      "ticker": "GLD",
      "reason": "...",
      "correlation": -0.65,
      "data_points": 150,
      "timeseries": [...],
      "normalized_timeseries": [...],
      "success": true
    }
  ]
}
```

---

## Testing with Python

You can also test using Python's `requests` library:

```python
import requests
import json

# Full analysis example
url = "http://localhost:5000/api/analyze-full"
data = {
    "url": "https://polymarket.com/event/will-biden-pardon-hunter-biden",
    "start_time": "2025-11-01 00:00:00",
    "end_time": "2025-11-14 23:59:59",
    "granularity": 60
}

response = requests.post(url, json=data)
result = response.json()

print(json.dumps(result, indent=2))
```

---

## Notes

1. **Time Format**: All times should be in EST format: `"YYYY-MM-DD HH:MM:SS"`
2. **Granularity**: Specified in minutes (60 = hourly, 1 = minute-by-minute)
3. **Intervals**: For yfinance: `"1m"`, `"5m"`, `"15m"`, `"30m"`, `"1h"`, `"1d"`
4. **Correlations**: Range from -1 (perfect inverse) to +1 (perfect positive)
5. **Data Limitations**: 
   - 1-minute data only available for last 7 days
   - Polymarket CLOB API may have rate limits
   - Some tickers may not have data for all time periods