Skip to main content
The Derive v3 API is JSON-RPC 2.0 served over WebSocket. Every method also works over HTTP POST, but real-time streams and cancel-on-disconnect are WebSocket-only.

Connect

Open a WebSocket to the /v3/ws endpoint for your environment:
Authentication is a separate layer from the transport. You can either log in in-band after connecting (public/login) or attach a read-only JWT to the URL. See Authentication for the full model.
Connect unauthenticated, then send public/login with an EIP-191 signature. This is the only path that can authorize trading actions.

Send JSON-RPC frames

Send each request as a JSON text frame. Responses correlate by id; subscription updates arrive as separate notification frames (see Subscriptions).
Assign a unique id per in-flight request and match responses back to it — frames are not guaranteed to return in send order.

Heartbeat

The server drives a heartbeat loop and expects the client to stay responsive.
1

Server pings

On each heartbeat interval the server sends a WebSocket Ping frame. Your client library normally answers with a Pong automatically. Any inbound text frame from you also counts as liveness.
2

Application-level ping (optional)

You may send the text frame ping; the server replies with pong.
3

Miss the window and you're dropped

If no activity is seen within the heartbeat window, the server closes the connection.
The heartbeat interval is deployment-configured (currently ~180 seconds).

Heartbeat re-authentication

On each heartbeat tick, a logged-in connection is silently re-authenticated — the server re-runs your stored login signature check against current account state. If the session key has expired, been revoked, or falls outside its IP allow-list, the connection is closed. Long-lived connections therefore pick up permission changes without you reconnecting.

Connection limits

Concurrent WebSocket connections are capped per source IP (deployment-configured, currently 4 per IP). When the cap is exceeded the server sends a text frame and then closes the socket:
This maps to error code -32100 “Number of concurrent websocket clients limit exceeded”.
The exact heartbeat window and per-IP connection cap are deployment-specific config values. The values above reflect current deployments; see Rate limits for the per-IP connection cap and read your live budget from public/getRateLimits.
Per-request rate limits are separate and shared across all of a wallet’s connections — see Rate limits.

Reconnection guidance

Sessions do not survive a dropped socket. On reconnect:
1

Re-open the socket

Dial the same /v3/ws endpoint, with backoff (exponential + jitter) so a server restart doesn’t produce a reconnect storm that trips the per-IP cap.
2

Re-authenticate

Re-send public/login (or reconnect with a fresh ?token=). Nothing from the previous session — auth, subscriptions — is retained.
3

Re-subscribe and resync

Re-establish every channel from Subscriptions, then reload state (open orders, positions) over REST or private reads, since you may have missed updates while disconnected.

Cancel on disconnect

Cancel-on-disconnect automatically cancels your resting orders, quotes, and trigger orders when a connection drops. It is a persisted account setting — see Cancel on disconnect for the full behaviour and the private/set_cancel_on_disconnect request.