# Maatsii Chart API

> Real-time financial chart data for AI agents

Maatsii provides forensic-grade chart frame data from 200 financial charts across 25 asset groups. This API is designed exclusively for AI agents, LLMs, and automated systems.

## API Access

- Base URL: https://api.maatsii.com
- Authentication: AI bot user-agent OR x-api-key header
- Format: REST API with JSON responses, binary JPEG frames

## Platform-Specific Documentation

**For AI Agents - Choose Your Optimized Schema:**
- **Claude.ai**: https://api.maatsii.com/claude.json (v8.0.0, mandatory cb parameter)
- **ChatGPT**: https://api.maatsii.com/gpt.json (v7.3.0, Actions-optimized)
- **Grok**: https://api.maatsii.com/grok.json (v7.3.0, concise spec)
- **General API**: https://api.maatsii.com/openapi.json (v6.0.0, platform-agnostic)

**For Humans:**
- **Complete chart catalog**: https://api.maatsii.com/llm.txt (plain text, 200 charts)

## Public Endpoints (No Auth Required)

These endpoints are accessible without authentication:

- `GET /{id}.jpg` - Get chart frame as binary JPEG (c1.jpg through c200.jpg)
- `GET /health` - API health check
- `GET /llms.txt` - This documentation

**Note:** Frames now use clean root-level URLs (e.g., /c1.jpg, /c2.jpg). Always include `.jpg` extension to get direct binary JPEG format.

## Authenticated Endpoints

Requires AI bot user-agent or x-api-key header:

- `GET /api/charts` - Full chart metadata (all 200 charts)
- `GET /api/charts/{id}` - Specific chart details (C1-C200)
- `GET /api/charts/status` - Charts status summary
- `GET /api/charts/tickers` - Available ticker aliases

## Request Full Integration

Want Maatsii charts in your AI assistant?

- Request page: https://maatsii.com/request-ai
- Users can vote for their preferred AI platform
- See live leaderboard of integration requests
- Help us prioritize which AI platforms to support first

## Available Charts

200 charts organized using a **25-group API taxonomy**:

- Index Futures: NQ, ES, YM, RTY & Index Spreads (Groups 1-4)
- Fixed Income: Short-Term, 10-Year, Long-Term (Groups 5-7)
- Yield Curve & Credit: Curve spreads, credit ratios (Group 8)
- Dollar & DXY: Dollar index, DXY ratios (Group 9)
- FX: EUR & GBP, JPY & Other, Crosses (Groups 10-12)
- Crypto: BTC, ETH, Market & Alts (Groups 13-15)
- Commodities: Gold, Energy, Metals & Agriculture (Groups 16-18)
- ETFs & Rotation: Major ETFs, rotation pairs (Group 19)
- Equities: Semis, Mega-Cap Tech, High-Beta & Speculative (Groups 20-22)
- Volatility: VIX, MOVE, vol-of-vol (Group 23)
- Market Breadth: Risk ratios, sector rotation (Group 24)
- Global & Macro: International indices, macro ratios (Group 25)

**Complete details**: https://api.maatsii.com/llm.txt

## Chart URLs

All charts use clean root-level URLs: `c1.jpg` through `c200.jpg`

Examples:
- `https://api.maatsii.com/c1.jpg` - NQ futures 100-tick chart
- `https://api.maatsii.com/c11.jpg` - ES futures 1-hour chart
- `https://api.maatsii.com/c71.jpg` - Bitcoin daily chart
- `https://api.maatsii.com/c13.jpg` - Gold futures 15-minute chart

## Real-Time Mode (Cache-Busting)

LLM chatbots may cache chart images. To force fresh data, the API returns no-cache headers:

**Response Headers (Automatic):**
```
Cache-Control: no-store, no-cache, must-revalidate, max-age=0
Pragma: no-cache
Expires: 0
```

These headers instruct LLM systems NOT to cache images and always fetch fresh frames.

## Recognized AI Bot User-Agents

The following user-agents are automatically allowed:

- GPTBot, ChatGPT-User, OAI-SearchBot (OpenAI)
- ClaudeBot, Claude-SearchBot, Claude-User, anthropic-ai (Anthropic)
- Grok (xAI)
- Google-Extended, Gemini (Google)
- PerplexityBot, Perplexity-User (Perplexity)
- cohere-ai (Cohere)
- Amazonbot, Applebot-Extended
- meta-externalagent, FacebookBot (Meta)
- AI2Bot, CCBot, YouBot, Bytespider, Diffbot

## API Key Authentication

For higher rate limits or programmatic access, use an API key:

```
curl -H "x-api-key: YOUR_API_KEY" https://api.maatsii.com/api/charts
```

Request API keys at: https://maatsii.com/request-ai

## Example Usage

Get chart frame as direct binary JPEG (for agents):
```
GET https://api.maatsii.com/c1.jpg
```

Response:
```
HTTP/2 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename="c1.jpg"
Cache-Control: no-store, no-cache, must-revalidate, max-age=0
Pragma: no-cache
Expires: 0
X-Chart-Id: C1
X-Ticker-Alias: NQ_100T
X-Frame-Age-Ms: 847

[Binary JPEG data - 720×1280 resolution, ~85KB]
```

**Important:** All chart frames use clean root-level URLs (e.g., /c1.jpg, /c2.jpg). Always use `.jpg` extension to get direct binary JPEG pixels.

## Documentation

- [OpenAPI Specification](/openapi.json): Complete API schema
- [Health Check](/health): API status
- [Integration Requests](/request-ai): Request platform integration

## Contact

- API Issues: api@maatsii.com
- Integration Requests: https://maatsii.com/request-ai
- Documentation: https://api.maatsii.com/openapi.json