Rate Limits

Rate limiting is two-tier. Every request first passes a per-wallet (or per-IP) request budget, and order-flow requests additionally pass a per-instrument order-rate limit. A request that exceeds either tier is rejected with a JSON-RPC error — nothing is queued. Read your live budgets at any time with public/getRateLimits.

Tier 1 — Request budget (per wallet)

Every method carries a rate-limit class (shown on each method’s page in the API Reference tab). The class selects which per-wallet budget the request decrements. Authenticated traffic is keyed by wallet; unauthenticated/public traffic is keyed by IP.

Class	Applies to	Budget it decrements
`non_matching`	Read/query methods and non-order mutations (the default)	Per-wallet non-matching budget
`matching`	Order-placing / matching methods	Per-wallet matching budget
`endpoint`	A method with its own dedicated per-method budget	Per-`(wallet, method)` budget
`custom`	Methods that apply their own limiting logic	Method-specific

Across the 100 JSON-RPC methods the classes are distributed:

non_matching

92 methods

matching

5 methods

endpoint

1 method

custom

2 methods

matching (5)

order, replace, cancel, cancel_by_instrument, cancel_by_nonce. All order-flow writes share one per-wallet matching budget, regardless of how many connections or session keys the wallet has open.

endpoint (1)

cancel_all — decrements its own per-(wallet, method) budget so a bulk cancel doesn’t consume the shared matching budget.

custom (2)

cancel_by_label and public/get_all_live_instruments opt out of the uniform dispatch and apply their own logic. cancel_by_label decrements the matching budget when scoped to a single instrument, otherwise a dedicated per-method budget; public/get_all_live_instruments is a public read with no per-request decrement, bounded only by the per-IP request and connection limits.

Budgets are wallet-scoped, not per-subaccount or per-session-key. All concurrent connections and session keys belonging to one wallet share a single budget. Public, pre-authentication traffic is limited per source IP, along with a cap on simultaneous WebSocket connections per IP.

Budget & window semantics

A request budget is a fixed window. The number of points available in each window is:

points_per_window = TPS × window_seconds

Every request costs one point; there is no per-method weight table. When the window elapses the budget resets. Because it is a fixed window (not a sliding one), a client can briefly emit up to two windows’ worth of requests across a window boundary.

Tier 2 — Per-instrument order-rate limit

Order-flow requests (order, replace, cancel, …) pass a second limiter: a per-instrument token bucket, keyed by (wallet, instrument).

The refill rate is a per-second TPS chosen by asset type — one value for perps and spot, another for options.
The bucket’s capacity (its burst allowance) is refill_rate × burst_multiplier.
Unlike the request budget’s fixed window, the bucket refills continuously, so it does not permit a window-boundary double-burst.

An order-placement request is limited twice: once by the matching request budget and once by the per-instrument bucket. A rejection can come from either tier, and both surface the same error code (see below), so a rejection alone does not tell you which tier tripped. The per-instrument limits are not reported by public/getRateLimits.

Concrete limits

All limits are deployment-specific and read from configuration at startup — code defaults, testnet, and mainnet differ. Treat the values below as a mainnet reference snapshot, not a contract, and always read your live budget with public/getRateLimits — the authoritative, live source for your budget.

Limiter	Scope	Mainnet reference
Non-matching budget	Per wallet	5 TPS → 25 points / 5s window
Matching budget	Per wallet	1 TPS → 5 points / 5s window
`cancel_all` budget	Per `(wallet, method)`	1 TPS → 5 points / 5s window
Public request budget	Per IP	5 TPS → 25 points / 5s window
Concurrent WebSocket clients	Per IP	4
Per-instrument bucket — perps / spot	Per `(wallet, instrument)`	refill 1 token/s, capacity 5
Per-instrument bucket — options	Per `(wallet, instrument)`	refill 1 token/s, capacity 5

Runtime introspection

public/getRateLimits returns your live request budgets. It is itself a non_matching method, so calling it costs one non-matching point. It takes no parameters.

import { DeriveClient } from '@derivexyz/derive-ts';

// public/getRateLimits is a keyless public method — no wallet or login needed.
const client = new DeriveClient({ network: 'mainnet' });

// No SDK wrapper: use the typed send() escape hatch. Takes no params.
const limits = await client.send('public/getRateLimits', null);
console.log(limits.remaining_matching, limits.remaining_non_matching);

# Coming soon.

// Coming soon.

curl -X POST https://api.derive.xyz/v3/public/getRateLimits \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "public/getRateLimits",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "remaining_matching": {
      "remainingPoints": 5,
      "msBeforeNext": 0,
      "consumedPoints": 0,
      "isFirstInDuration": true
    },
    "remaining_non_matching": {
      "remainingPoints": 24,
      "msBeforeNext": 3120,
      "consumedPoints": 1,
      "isFirstInDuration": false
    },
    "remaining_per_endpoint": {
      "cancel_all": {
        "remainingPoints": 5,
        "msBeforeNext": 0,
        "consumedPoints": 0,
        "isFirstInDuration": true
      }
    },
    "remaining_connections": {
      "remainingPoints": 3,
      "msBeforeNext": 0,
      "consumedPoints": 1,
      "isFirstInDuration": false
    }
  }
}

remaining_matching

object

required

Live state of the per-wallet matching budget.

remaining_non_matching

object

required

Live state of the per-wallet non-matching budget.

remaining_per_endpoint

map<string, object>

required

Per-method budgets, keyed by method name (e.g. cancel_all).

remaining_connections

object

Live state of the per-IP concurrent-connection limiter. Present on WebSocket only.

Each budget object carries:

remainingPoints

integer

required

Points (tokens) left in the current window.

msBeforeNext

integer

required

Milliseconds until the next request is allowed; 0 when a request may go through now.

consumedPoints

integer

required

Points consumed in the current window.

isFirstInDuration

boolean

required

Whether this is the first request in the current window.

getRateLimits exposes only the request-budget tier. The per-instrument token buckets are not reported, so perp/option instrument limits cannot be discovered at runtime.

Rejection error codes

When a request exceeds a limit it is rejected — never queued — with a JSON-RPC error. Codes -32000 through -32099 are reserved for rate-limit errors. See Error codes for the full catalogue.

Code	Message	Raised by
`-32000`	`Rate limit exceeded`	Per-wallet / per-IP request budget or the per-instrument bucket. The `data` field carries a `Retry after {ms} ms` hint.
`-32100`	`Number of concurrent websocket clients limit exceeded`	Per-IP connection-count limiter. The WebSocket receives a `connectionLimitExceeded:` text frame and is then closed.

Rejection

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32000,
    "message": "Rate limit exceeded",
    "data": "Retry after 3120 ms"
  }
}

Back off using msBeforeNext from getRateLimits or the Retry after {ms}{" "} ms hint on a -32000 rejection. Because order flow is limited by both the matching request budget and the per-instrument bucket, spread order flow across instruments and keep a margin below your reported budget.

Get Started

Authentication & Keys

Trading Concepts

Permissionless Vaults

WebSocket

Reference

Tier 1 — Request budget (per wallet)

non_matching

matching

endpoint

custom

Budget & window semantics

Tier 2 — Per-instrument order-rate limit

Concrete limits

Runtime introspection

Rejection error codes

​Tier 1 — Request budget (per wallet)

non_matching

matching

endpoint

custom

​Budget & window semantics

​Tier 2 — Per-instrument order-rate limit

​Concrete limits

​Runtime introspection

​Rejection error codes

Tier 1 — Request budget (per wallet)

Budget & window semantics

Tier 2 — Per-instrument order-rate limit

Concrete limits

Runtime introspection

Rejection error codes