# Attena API - Complete Documentation

## Overview
Attena is a comprehensive prediction market search engine that indexes over 60,000 markets from major platforms including Kalshi and Polymarket. Our API provides real-time search capabilities across sports, cryptocurrency, weather, politics, and geopolitics prediction markets.

## Base URL
https://attena-api.fly.dev

## Authentication
- Anonymous usage: 30 requests per minute
- API key usage: 300 requests per minute
- Contact support for API keys

## Endpoint: Search Markets

### URL
GET /api/search/

### Parameters
- **q** (required): Search query string
- **limit** (optional): Number of results to return (default: 10, max: 50)
- **offset** (optional): Number of results to skip for pagination (default: 0)

### Response Schema
```json
{
  "query": "string - the search query",
  "results": [
    {
      "id": "string - unique market identifier",
      "title": "string - market question/title",
      "category": "string - main category (sports, crypto, weather, politics, geopolitics)",
      "subcategory": "string - specific subcategory (nba, btc, etc.)",
      "league": "string - specific league/competition if applicable",
      "event_date": "string - ISO 8601 date when event occurs",
      "source": "string - market platform (kalshi, polymarket)",
      "market_id": "string - platform-specific market ID",
      "yes_price": "number - current YES price (0-1 for probability)",
      "no_price": "number - current NO price (0-1 for probability)", 
      "volume": "number - trading volume",
      "rank": "number - search relevance rank",
      "source_url": "string - direct link to market on platform",
      "close_time": "string - ISO 8601 date when market closes",
      "bracket_count": "number - number of outcome brackets",
      "outcome_label": "string - outcome description"
    }
  ],
  "total_count": "number - total matching results",
  "search_tier": "string - search quality tier", 
  "timing_ms": "number - response time in milliseconds"
}
```

### Categories and Subcategories

**Sports**
- nba: NBA basketball games, playoffs, championships
- nfl: NFL games, Super Bowl, playoffs  
- nhl: NHL hockey games, Stanley Cup
- f1: Formula 1 races, championships

**Crypto**
- btc: Bitcoin price predictions, halvings
- eth: Ethereum price, upgrades, ETF approvals
- sol: Solana ecosystem developments
- xrp: Ripple/XRP regulatory outcomes
- doge: Dogecoin price movements

**Weather**
- Temperature records, seasonal predictions
- Hurricane and storm forecasts
- Climate change indicators

**Politics**  
- Election outcomes, candidate predictions
- Policy passage probabilities
- Approval ratings, polling

**Geopolitics**
- International conflicts and resolutions
- Trade agreements, sanctions
- Diplomatic outcomes

### Example API Responses

#### Query: "Trump 2024 election"
```json
{
  "query": "Trump 2024 election",
  "results": [
    {
      "id": "trump-2024-republican-nomination",
      "title": "Will Donald Trump win the 2024 Republican nomination?",
      "category": "politics",
      "subcategory": "election",
      "league": null,
      "event_date": "2024-07-15T00:00:00Z",
      "source": "kalshi",
      "market_id": "PRES-24-GOP",
      "yes_price": 0.85,
      "no_price": 0.15,
      "volume": 1250000,
      "rank": 1,
      "source_url": "https://kalshi.com/events/PRES-24-GOP",
      "close_time": "2024-07-14T23:59:59Z",
      "bracket_count": 2,
      "outcome_label": "Republican Nomination Winner"
    }
  ],
  "total_count": 15,
  "search_tier": "high",
  "timing_ms": 45
}
```

#### Query: "Lakers championship"  
```json
{
  "query": "Lakers championship",
  "results": [
    {
      "id": "lakers-nba-championship-2024",
      "title": "Will the Lakers win the 2024 NBA Championship?",
      "category": "sports", 
      "subcategory": "nba",
      "league": "NBA",
      "event_date": "2024-06-20T00:00:00Z",
      "source": "polymarket",
      "market_id": "0x1234567890abcdef",
      "yes_price": 0.12,
      "no_price": 0.88,
      "volume": 850000,
      "rank": 1,
      "source_url": "https://polymarket.com/event/lakers-championship",
      "close_time": "2024-06-19T23:59:59Z", 
      "bracket_count": 2,
      "outcome_label": "Championship Winner"
    }
  ],
  "total_count": 8,
  "search_tier": "high", 
  "timing_ms": 32
}
```

### Additional Example Queries

**Crypto Markets:**
- "Bitcoin price $100k 2024" - BTC price predictions
- "Ethereum ETF approval" - ETF regulatory outcomes  
- "Solana vs Ethereum market cap" - Blockchain comparisons
- "Dogecoin reaches $1" - Meme coin predictions
- "Crypto market crash 2024" - Market movement predictions

**Sports Markets:**
- "Chiefs Super Bowl repeat" - NFL championship repeats
- "Ohtani MVP 2024" - Baseball awards predictions  
- "Warriors playoff miss" - NBA playoff predictions
- "Max Verstappen championship" - F1 driver championships
- "Stanley Cup upset" - NHL playoff predictions

**Weather/Climate:**
- "Hurricane season 2024 active" - Seasonal weather patterns
- "Hottest summer record" - Temperature records
- "California drought continues" - Climate predictions
- "Arctic ice minimum" - Environmental indicators

**Political Markets:**  
- "Biden approval rating 50%" - Presidential approval
- "Congressional control 2024" - Election outcomes
- "Supreme Court retirement" - Judicial predictions
- "Government shutdown 2024" - Policy outcomes

**Geopolitical Markets:**
- "Ukraine conflict resolution" - International conflicts
- "China Taiwan escalation" - Regional tensions  
- "Russia sanctions lifted" - Economic policy
- "NATO expansion" - Alliance developments
- "Trade war resolution" - Economic relations

### Rate Limits
- Anonymous users: 30 requests per minute
- Authenticated users: 300 requests per minute  
- Burst allowance: 50 requests in 10 seconds
- Rate limit headers included in all responses

### Error Responses
- 400 Bad Request: Invalid query parameters
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Server-side issues

## MCP Server (Model Context Protocol)

Attena provides an MCP server for native AI agent integration. Instead of writing HTTP requests, agents can connect directly and use prediction market search as a tool.

### SSE Endpoint
https://attena-api.fly.dev/mcp

### Available Tools

**attena_search_markets**
- query (string): Natural language search query
- limit (int, default 10): Max results (1-50)
- Returns: Markdown-formatted search results with odds, volume, and links

**attena_trending_markets**
- category (string, optional): Filter by category (sports, crypto, weather, politics, geopolitics)
- limit (int, default 10): Max results (1-50)
- Returns: Markdown-formatted trending markets sorted by volume

### Claude Desktop Configuration
```json
{
  "mcpServers": {
    "attena": {
      "url": "https://attena-api.fly.dev/mcp"
    }
  }
}
```

### Cursor / VS Code Configuration
Add to your MCP settings:
```json
{
  "mcpServers": {
    "attena": {
      "url": "https://attena-api.fly.dev/mcp"
    }
  }
}
```

### Best Practices
- Use specific keywords for better results
- Combine category terms with specific events
- Use date ranges for time-sensitive markets
- Implement proper rate limiting in your applications
- Cache responses when appropriate

### Contact & Support
For API keys, enhanced rate limits, or integration support:
- Website: https://attena.xyz
- Email: support@attena.xyz
- Documentation: https://attena.xyz/docs