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

# Authentication

> Get your API key and start making requests

## Get your API key

Generate a free API key instantly — no signup required:

```bash theme={null}
curl -X POST "https://app.eventgraph.ai/api/v1/keys?name=my-app&email=you@example.com"
```

**Response:**

```json theme={null}
{
  "data": {
    "key": "eg_live_a1b2c3d4e5f6...",
    "key_prefix": "eg_live_a1b2...",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-app",
    "email": "you@example.com",
    "tier": "free",
    "daily_limit": 1000,
    "monthly_limit": 10000
  },
  "meta": {
    "warning": "Store this key securely. It will not be shown again."
  },
  "timestamp": "2025-01-15T12:00:00Z"
}
```

<Warning>
  Your API key is shown **once** in the response. We only store a hash — the key cannot be retrieved later. Save it immediately.
</Warning>

## Using your key

Pass the key in the `X-API-Key` header:

```bash theme={null}
curl "https://app.eventgraph.ai/api/v1/markets?page_size=5" \
  -H "X-API-Key: eg_live_a1b2c3d4e5f6..."
```

Or as a query parameter (not recommended for production):

```bash theme={null}
curl "https://app.eventgraph.ai/api/v1/markets?api_key=eg_live_a1b2c3d4e5f6..."
```

## API endpoints

### Free tier

| Method | Endpoint          | Description                        |
| ------ | ----------------- | ---------------------------------- |
| `POST` | `/api/v1/keys`    | Generate a new API key             |
| `GET`  | `/api/v1/status`  | API health and data freshness      |
| `GET`  | `/api/v1/markets` | List markets across all platforms  |
| `GET`  | `/api/v1/events`  | List events with filtering         |
| `GET`  | `/api/v1/search`  | Search events and markets by title |

### Pro tier (\$49/mo)

Everything in Free, plus:

| Method | Endpoint                       | Description                         |
| ------ | ------------------------------ | ----------------------------------- |
| `GET`  | `/api/v1/arbitrage`            | Cross-platform spread opportunities |
| `GET`  | `/api/v1/compare`              | Side-by-side market comparison      |
| `GET`  | `/api/v1/markets/{id}/history` | Historical price data               |
| `GET`  | `/api/v1/usage`                | Your API usage stats                |

### Enterprise (custom)

All endpoints, unlimited rate limits, dedicated support.

## Rate limits

| Plan                    | Requests / day | Requests / month | Rate / minute |
| ----------------------- | -------------- | ---------------- | ------------- |
| **Free** (\$0)          | 1,000          | 10,000           | 30            |
| **Pro** (\$49/mo)       | 50,000         | 500,000          | 300           |
| **Enterprise** (custom) | Unlimited      | Unlimited        | 1,000         |

When you exceed limits, the API returns `429 Too Many Requests`:

```json theme={null}
{
  "error": "daily_limit_exceeded",
  "message": "Daily limit of 1,000 requests reached. Resets at midnight UTC.",
  "limit": 1000,
  "used": 1000,
  "tier": "free",
  "upgrade_url": "https://eventgraph.ai/pricing"
}
```

## Key management

### List your keys

```bash theme={null}
curl "https://app.eventgraph.ai/api/v1/keys" \
  -H "X-API-Key: eg_live_a1b2c3d4e5f6..."
```

### Revoke a key

```bash theme={null}
curl -X DELETE "https://app.eventgraph.ai/api/v1/keys/{key_id}" \
  -H "X-API-Key: eg_live_a1b2c3d4e5f6..."
```

## Plans

<CardGroup cols={3}>
  <Card title="Free" icon="code">
    * 1,000 requests / day
    * 10,000 requests / month
    * Markets, events, search, status
    * All platforms: Polymarket, Kalshi, Limitless, Opinion
    * Community support
  </Card>

  <Card title="Pro — $49/mo" icon="rocket">
    * 50,000 requests / day
    * 500,000 requests / month
    * Arbitrage detection + comparison
    * Historical price data
    * Usage analytics
    * Priority support (24h SLA)
  </Card>

  <Card title="Enterprise — Custom" icon="building">
    * Unlimited requests
    * All endpoints
    * Custom rate limits
    * Dedicated support
    * SLA guarantee
  </Card>
</CardGroup>

## Upgrade to Pro

<CardGroup cols={2}>
  <Card title="Upgrade via App — $49/mo" icon="rocket" href="https://app.eventgraph.ai/pricing">
    Open the pricing page and click **Upgrade to Pro**. Enter your email or existing API key — you'll be redirected to Stripe checkout instantly.
  </Card>

  <Card title="Upgrade via API" icon="code" href="/api-reference/checkout">
    Already have a key? Call `POST /api/v1/checkout` with your key in the header to get a Stripe checkout URL back.
  </Card>
</CardGroup>

### Programmatic upgrade

```bash theme={null}
curl -X POST "https://app.eventgraph.ai/api/v1/checkout" \
  -H "X-API-Key: eg_live_your_free_key"
```

Response:

```json theme={null}
{
  "checkout_url": "https://checkout.stripe.com/pay/cs_live_...",
  "session_id": "cs_live_..."
}
```

Open `checkout_url` in a browser to complete payment. Your API key is **automatically upgraded to Pro** after the Stripe session completes — no key rotation needed.