Rate Limits

Diffusal enforces rate limits on REST and public WebSocket endpoints to protect the platform and ensure fair usage. Authenticated users with API keys receive higher limits on supported REST flows based on their tier.

Tier System

REST rate limits are tiered based on authentication status and trading volume.

Column definitions:

• Orders/min — Rate limit for trading and account mutation endpoints (/api/mm/*, /api/portfolio/*, /api/strategies/*, /api/rfq/*)
• Data/min — Rate limit for market data endpoints (/api/markets/*)

REST Rate Limits

Public Market Data Endpoints

Public endpoints like /api/markets/pairs, /api/markets/ticker/:symbol, and /api/markets/orderbook/:symbol are rate-limited by IP at 600 requests/min for unauthenticated users.

To receive higher limits on public endpoints, include your API key headers in the request. The server will resolve your tier and apply the corresponding Data/min limit instead:

curl https://api.testnet.diffusal.xyz/api/markets/pairs \
  -H "X-API-Key: dfsl_your_key_id" \
  -H "X-API-Timestamp: $(date +%s%3N)" \
  -H "X-API-Signature: your_hmac_signature"

If the API key headers are present but invalid (expired, wrong signature, revoked key), the request falls back to IP-based limits silently — it does not return a 401 error. This matches the behavior of major exchanges.

Authenticated Endpoints

Endpoints requiring authentication (/api/mm/*, /api/portfolio/*, /api/strategies/*, /api/rfq/*, /api/account/*) use the Orders/min limit keyed by your API key or wallet address.

Rate Limit Response Headers

Authenticated requests include rate limit headers in the response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 595
X-RateLimit-Reset: 1709827200

HTTP 429 Responses

When a rate limit is exceeded, the server returns:

HTTP/1.1 429 Too Many Requests
{
  "code": "resource_exhausted",
  "message": "rate limit exceeded"
}

WebSocket Rate Limits

Current public WebSocket limits:

Connection Rate Limit

New public WebSocket connections are rate-limited per IP. If you exceed the connection limit, the connection is silently closed.

Message Rate Limit

Inbound messages on an active public WebSocket connection are rate-limited. If you exceed the message limit, the server responds with an error but keeps the connection open:

{
  "error": {
    "code": 4029,
    "msg": "message rate limit exceeded"
  },
  "id": 0
}

Your client can back off and resume sending messages after the window resets (60 seconds).

Subscription Limit

Each public WebSocket connection has a maximum number of concurrent subscriptions. Attempting to subscribe beyond the limit returns:

{
  "error": {
    "code": 4029,
    "msg": "subscription limit exceeded (max 25)"
  },
  "id": 1
}

The public docs route documents only the public websocket surface. Contributor-only realtime authentication and any non-public websocket tiers are intentionally omitted here.

API Keys

Creating an API Key

API keys are created through the dashboard or the REST API. You must be authenticated with a SIWE session first.

# Create a new API key with trade + read scopes
curl -X POST https://api.testnet.diffusal.xyz/api/keys \
  -H "Authorization: Bearer your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"label": "Trading Bot", "scopes": ["read", "trade"]}'

Response:

{
  "keyId": "dfsl_abc123...",
  "secret": "hex_encoded_secret...",
  "label": "Trading Bot",
  "scopes": ["read", "trade"]
}

Important: The secret is only returned once at creation time. Store it securely.

Managing API Keys

Authenticating with API Keys

Include these three headers in every authenticated request:

Generating the signature:

import { createHmac } from "crypto";

const timestamp = Date.now().toString();
const signature = createHmac("sha256", apiSecret)
  .update(timestamp)
  .digest("hex");

import hmac, hashlib, time

timestamp = str(int(time.time() * 1000))
signature = hmac.new(
    api_secret.encode(), timestamp.encode(), hashlib.sha256
).hexdigest()

The timestamp must be within 30 seconds of the server's current time.

Available Scopes

Dashboard

The Diffusal dashboard provides a visual interface for API key management:

1. Connect wallet — Sign in with your wallet using SIWE
2. Navigate to Settings → API Keys — View and manage your keys
3. Create Key — Select scopes and generate a new key pair
4. Copy Secret — Save the secret immediately (shown only once)
5. Revoke/Rotate — Revoke compromised keys or rotate secrets

The dashboard also displays your current rate limit tier, 30-day trading volume, and real-time usage metrics.

See Also

• Authentication
• WebSocket Streams
• API Reference