Authentication

Every authenticated request carries Authorization: Bearer <token>. The token is either an sk_live_* API key (machine partners) or an OAuth 2.1 access token (hosted apps that act on behalf of a user). Sandbox and production share the same host + the same sk_live_ prefix — capability is differentiated by the key's tier flag. HMAC request-signing exists on the roadmap for enterprise partners but is not open to standard integrations today.

Overview

Scheme	Use case	Header(s)	Status
API Key (Bearer)	Machine-to-machine, creator bots, aggregators	Authorization: Bearer sk_live_…	Live
OAuth 2.1 + PKCE	Hosted apps acting on behalf of a user	Authorization: Bearer <access_token>	Live
HMAC request-signing	Enterprise partners with dedicated ops provisioning	PAX-ADDRESS / PAX-TIMESTAMP / PAX-NONCE / PAX-SIGNATURE	Enterprise · ops-provisioned

1. API Key (Bearer)

Send your sk_live_* key as a Bearer token. No signing. Rate-limited per key. Same header the OAuth flow uses — the router decides based on prefix.

curl https://api.predictasiax.com/v1/balance \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE"

Minting a key

Fastest path: hit /sandbox/ or POST /v1/sandbox-keys — no auth, tier self_serve, $10/order + $100/day caps, sandbox and production share the same host so no environment swap is needed later. See Getting Started for the end-to-end flow. Long-lived production keys are minted from the Builder Portal after your app is approved (Request access → Portal → Settings → API Keys → Mint new key).

Every successful mint returns the raw api_key exactly once. It is stored server-side only as sha256(key + PAX_HMAC_PEPPER) — if you lose it, rotate.

Environments & tiers

Every sk_live_* key carries a tier flag that controls its capabilities and rate limits — enforced server-side on every request:

Tier	Capability	Rate multiplier
self_serve SANDBOX	Simulated fills at mid-price, $10 per-order + $100 daily notional caps. Zero real-money risk.	1× baseline
read_live LIVE	Auto-graduated production tier — reached at $100 30-day attributed volume. Real-money trading with tier-native limits.	1× baseline
trade_capped LIVE	Real-money trading with per-order + daily notional ceilings.	1× baseline
trade_full LIVE	Unrestricted real-money trading, MM-tier order sizes.	1× baseline
genesis LIVE	Inaugural cohort — early access to unreleased endpoints, custom bursts.	10× baseline
partner / institutional	Signed agreement — dedicated infra, co-marketing, negotiated fee splits.	up to 20× (negotiable per contract)

Mismatched credentials return 401 WRONG_ENV_KEY.

2. OAuth 2.1 + PKCE

For hosted apps that act on behalf of a PredictAsiaX user. Full flow lives at connect.predictasiax.com: authorize → callback with code + PKCE code_verifier → POST /oauth/token → receive access_token (short-lived) + refresh_token (rotating).

curl https://api.predictasiax.com/v1/balance \
  -H "Authorization: Bearer <access_token>"

Access tokens expire; refresh with the standard OAuth 2.1 rotating refresh flow. Reuse of a refresh token revokes the whole family (REFRESH_TOKEN_REUSED).

3. HMAC (enterprise · ops-provisioned)

Reserved for enterprise partners who need per-request signing beyond a Bearer token. The path exists in the auth middleware but is not open on the current live surface — any HMAC-shaped credential returns 401 AUTH_INVALID with a directive to use Bearer. Contact ops through your enterprise agreement to have the signing secret provisioned into the HMAC KV.

Header	Value
PAX-ADDRESS	Your key_id (e.g. sk_live_ABC123).
PAX-TIMESTAMP	UNIX seconds epoch (not milliseconds). Must be within ±300s (5 min) of server clock — outside window returns TIMESTAMP_SKEW.
PAX-NONCE	Random unique-per-request string. Nonces are cached 600s; replay returns NONCE_REUSED.
PAX-SIGNATURE	Hex-encoded HMAC-SHA256(secret, signingString) where signingString = method + "\n" + path + "\n" + ts + "\n" + nonce + "\n" + sha256Hex(body).

The scheme is documented so enterprise partners can prepare receiver code; the endpoint will begin accepting HMAC once ops has provisioned apisec:<key_id> in the KV binding.

WebSocket authentication

The WS endpoint at wss://predictasiax.com/ws accepts anonymous connections for public streams (ticker, orderbook, fast_tick, markets_snapshot). To subscribe to private streams (account, deposit, trade_executed, etc.), send an AUTH command after connect. Command names are uppercase per AsyncAPI — see Downloads → AsyncAPI.

wscat -c wss://predictasiax.com/ws

> {"op":"AUTH","token":"sk_live_ABC123"}
< {"type":"authenticated","user_id":"u_..."}

> {"op":"SUBSCRIBE","params":["account","trade_executed"]}

You can pass either an sk_live_* API key or an OAuth access token as token — the server accepts both.

Rotating a key

API keys mint through the Portal or (for apps) via POST /v1/apps/{id}/rotate-secret. Webhook signing secrets rotate via POST /v1/webhooks/{id}/rotate-secret — see /webhook-signing for the 24h dual-signature grace behavior.