# MarsEdge API Documentation

Base URL: `https://marsedge.vip`

Machine-readable schema: https://marsedge.vip/openapi.json

## Authentication

Use either header form with a valid Pro API key:

```http
X-API-Key: pk_live_xxx
```

```http
Authorization: Bearer pk_live_xxx
```

## Endpoints

### GET /api/health

Public health and service-status response.

### GET /api/keys/verify

Requires an API key. Returns whether the key is valid together with `userId`, `plan`, `maskedKey` and `lastUsedAt`.

### GET /api/probboard/latest

Returns the latest full probability board. Guest access is supported with rate limits; authenticated plans may receive faster refresh entitlements.

Important response fields include:

- `plan`, `refreshMs`, `updatedAt`, `servedAt`
- `dataAgeMs`, `latencyLevel`, `isStale`
- `items[].symbol`
- `items[].p_up_pct`, `items[].p_down_pct`
- `items[].up_bid`, `items[].up_ask`
- `items[].down_bid`, `items[].down_ask`
- `items[].up_token_id`, `items[].down_token_id`
- `items[].rem_secs`

### GET /api/probboard/stream

VIP Pro real-time Server-Sent Events endpoint. Requires a signed-in Pro session or valid Pro API key. Board updates use the `board` event type.

## curl

```bash
curl -H "X-API-Key: pk_live_xxx" https://marsedge.vip/api/keys/verify
curl -H "X-API-Key: pk_live_xxx" https://marsedge.vip/api/probboard/latest
curl -N -H "X-API-Key: pk_live_xxx" https://marsedge.vip/api/probboard/stream
```

## Usage notes

- Respect the `refreshMs` entitlement and HTTP 429 retry information.
- Treat probability estimates as model output, not guaranteed outcomes.
- Never expose an API key in client-side public code, logs or prompts shared with third parties.