Hydra
Docs

Generate, manage, and scope API keys for programmatic access.

API Keys & Scopes

API keys are the primary method for authenticating programmatic access to Hydra. Each key is scoped to specific streams and tied to an app on the Platform dashboard.

Key Format

API keys use the prefix hyd_ followed by 32 random hex bytes:

hyd_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678

Keys are one-way hashed on the server using SHA-256. Only the first 12 characters (the prefix) are stored in plain text for identification. The full key is shown once at creation — store it securely.

Creating an API Key

API keys are created through the Platform dashboard or via the API.

Via Dashboard

  1. Go to Platform → select your app
  2. Navigate to the API Keys tab
  3. Click Create Key
  4. Choose a name, select stream scopes, and set an optional expiry
  5. Copy the key immediately

Via API

POST https://api.hydra.fast/apps/:slug/api-keys
Authorization: Bearer <privy-token>
Content-Type: application/json

{
  "name": "Monitor Bot",
  "scopes": ["signals", "aircraft", "cyber"],
  "expiresInDays": 90
}

{
  "id": "key_abc123",
  "name": "Monitor Bot",
  "key": "hyd_a1b2c3d4e5f6...",
  "prefix": "hyd_a1b2c3d4",
  "scopes": ["signals", "aircraft", "cyber"],
  "expiresAt": "2026-06-19T00:00:00.000Z",
  "createdAt": "2026-03-21T12:00:00.000Z"
}
⚠️
Warning

The key field is returned only once in the creation response. It is never stored in plain text and cannot be retrieved later. If you lose it, revoke the key and create a new one.

Scopes

Each API key is scoped to specific streams. The key can only access data from those streams — requesting data from an unscoped stream returns 403 Forbidden.

Available scopes match the stream names:

Scope Tier Required Data
signals Basic Geopolitical intelligence signals
markets Basic Prediction market data
earthquakes Basic USGS earthquake events
aircraft Standard Military aircraft tracking
vessels Standard Naval vessel tracking
alerts Advanced Missile and civil defense alerts
airspace Advanced SIGMETs, NOTAMs, restricted zones
cyber Advanced Cyber threat intelligence
social Full Social media OSINT

Scopes are validated at creation time against the app owner's token tier. You cannot create a key with scopes your balance doesn't support.

Using an API Key

Pass the key in the x-api-key header:

curl https://api.hydra.fast/v1/signals \
  -H "x-api-key: hyd_a1b2c3d4..."

For WebSocket connections:

wss://api.hydra.fast/stream?apiKey=hyd_a1b2c3d4...

Checking Your Key

GET https://api.hydra.fast/auth/me
x-api-key: hyd_a1b2c3d4...

{
  "address": "0xYourWalletAddress",
  "tier": "advanced",
  "balance": "15200",
  "streams": ["signals", "aircraft", "cyber"]
}

Managing Keys

List Keys

GET https://api.hydra.fast/apps/:slug/api-keys
Authorization: Bearer <privy-token>

Returns all keys for the app (prefix, name, scopes, status — never the full key).

Revoke a Key

DELETE https://api.hydra.fast/apps/:slug/api-keys/:keyId
Authorization: Bearer <privy-token>

Revoked keys are immediately rejected on all subsequent requests. Revocation is permanent.

Multiple Keys

You can create multiple API keys per app, each with different scopes and expiry dates. Common patterns:

  • Per-environment: separate keys for dev, staging, and production
  • Per-bot: one key per bot or integration with only the scopes it needs
  • Short-lived: keys with 30-day expiry for temporary access
Tip

Follow the principle of least privilege — give each key only the scopes it actually needs. If a key is compromised, the blast radius is limited to its scopes.