authentication

The gexbot API uses API Keys for request authentication.

Authorization Header & User-Agent

Include your API Key in the Authorization HTTP header for all authenticated requests. The API also requires a descriptive User-Agent header.

Authorization: Bearer <YOUR_API_KEY>
User-Agent: <YOUR_APP_NAME>/1.0

Example Request

BASE_URL="<your host and version>"

curl -X GET "$BASE_URL/SPX/classic/gex_full" \
  -H "Authorization: Bearer gexbot_custom_abcdef123456" \
  -H "User-Agent: MyTradingApp/1.0" \
  -H "Accept: application/json"

Public vs. Authenticated Endpoints

• Public Endpoints: GET /tickers, GET /tickers/quant and GET /{package}/categories are open and unauthenticated. Every request still requires the User-Agent header.
• Package-Gated Endpoints: Endpoints under /{ticker}/classic/*, /{ticker}/state/* and /{ticker}/orderflow/* require an active subscription that includes the package.
• All Paid Tiers: The end-of-day report GET /hist/eod/{ticker} and the futures conversion GET /futures/conversion are available to Classic, State, Orderflow and Quant. A Research API key cannot call them.
• Quant-Tier Endpoints: Bulk historical downloads (/hist/{ticker}/{package}/{category}/{date}), option expiration lookups (/options/{ticker}/expiries), and WebSocket streaming negotiation (POST /negotiate) require an active Quant Tier subscription.
• Research Endpoints: /research/* require a Research API key. You can create one only with the active Research add-on.
• API Key Formats:
  • A custom gexbot API key has the format gexbot_custom_<43 characters> (for example Bearer gexbot_custom_<secret>). A platform-integration key uses the platform name in place of custom.
  • A Research API key has the format research_<43 characters>. Research API endpoints (/research/*) accept only this key.
  • API keys are product-specific and not interchangeable.

Identify the Authenticated Account

Use GET /whoami to verify an API key and inspect its access. The response includes the account's subscription levels, add-ons, entitlements, permissions, account flags, and masked API key metadata. A gexbot API key or a gexbot research API key can call this endpoint, even when the plan does not include REST data access. A key for another product, such as a skewbot key, receives 403 Forbidden. Session cookies cannot authenticate the request.

Request

curl "https://api.gex.bot/whoami" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "User-Agent: <YOUR_APP_NAME>/1.0" \
  -H "Accept: application/json"

Headers

Response

A successful response sets Cache-Control: no-store. It never returns the API key secret.

{
  "_id": "0123456789abcdef01234567",
  "role": "user",
  "level": [
    "orderflow"
  ],
  "max_level": "orderflow",
  "addons": [],
  "entitlements": {
    "gexbot": {
      "level": "orderflow",
      "addons": []
    },
    "skewbot": {
      "active": false,
      "tier": null
    }
  },
  "permissions": [
    "app_access",
    "api_rest_access",
    "api_websocket_access"
  ],
  "account": {
    "commercial": false,
    "commercial_delegate": false,
    "display_use": false,
    "child": false,
    "managed": false,
    "delegated": false
  },
  "api_key": {
    "id": "gexbot_custom_...AbCd",
    "label": "custom_key",
    "product": "gexbot",
    "integration": "custom",
    "created_at": "2025-01-15T14:30:00Z"
  },
  "created": "2025-01-10T12:00:00Z"
}

Status Codes