Authentication

All API endpoints (except /healthz, /readyz, and POST /v1/keys) require an API key.

Passing the key

Two methods are supported:

Header (recommended)
Query parameter

curl -H "x-api-key: pn_live_YOUR_KEY" https://api.polynode.dev/v1/markets

curl "https://api.polynode.dev/v1/markets?key=pn_live_YOUR_KEY"

For WebSocket connections, use the query parameter:

wss://ws.polynode.dev/ws?key=pn_live_YOUR_KEY

Key format

API keys use the prefix pn_live_ followed by a random string. Legacy keys with qm_live_ prefix are also accepted.

Account-level usage

All active API keys owned by the same account contribute to one shared monthly usage total. Creating, renaming, rotating, or using multiple keys does not create separate allowances or reset usage. The usage dashboard is authenticated by your signed-in account; you do not submit a raw API key to view it. See Monthly usage allowances for the exact meters and included plan capacity.

Generating a key

curl -s -X POST https://api.polynode.dev/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

Field	Type	Description
`name`	string (optional)	Label for the key. Defaults to “unnamed”.

Key generation is rate limited to 1 per IP per day.

The raw API key is returned only once. It cannot be retrieved after creation — store it securely.

Security

API keys are SHA-256 hashed before storage. The raw key is never persisted.
All traffic should use HTTPS in production.
Rotate keys by generating a new one and decommissioning the old one.

Error responses

Status	Error	Fix
401	Missing or invalid API key	Include your key as `x-api-key` header or `?key=` param
403	Invalid or inactive API key	Verify your key is correct, or generate a new one
429	Rate limit exceeded	Reduce request frequency. Free tier: 60 req/min

Getting Started

Guides

Passing the key

Key format

Account-level usage

Generating a key

Security

Error responses

​Passing the key

​Key format

​Account-level usage

​Generating a key

​Security

​Error responses

Passing the key

Key format

Account-level usage

Generating a key

Security

Error responses