Custom Rate Limits

Custom rate limits give you precise control over API key usage, protecting endpoints from abuse and managing usage across multiple projects.

Syndica's credential-level rate limiting solves two critical problems for Solana developers: preventing theft and misuse of publicly exposed RPC credentials, and managing rate limits across separate projects or services within a single account. Without custom rate limits, stolen API keys can be exploited for unauthorized activities, and traffic spikes from one project can impact others sharing the same account limits.

Custom rate limits provide:

• Prevent Unwanted Usage: Protect publicly exposed API keys from theft and misuse
• Project-Level Management: Allocate rate limits across separate services and environments
• Granular Control: Set limits at the credential level or for specific RPC methods
• IP-Based Restrictions: Apply different limits per IP address

Rate Limit Scopes

Custom rate limits can be configured at multiple levels, providing flexibility in how you control API key access. These custom limits operate within your account's default rate limits based on your plan.

Credential-Wide Limits

Credential-wide limits apply to all traffic using an API key, regardless of which methods are called. These are useful for setting an overall cap on an API key's usage.

Use cases:

• Allocating a portion of your account's total RPS to a specific service or environment
• Preventing a single API key from consuming all available rate limit capacity
• Setting baseline limits before adding method-specific restrictions

Method-Specific Limits

Method-specific limits allow you to set different rate limits for individual RPC methods or subscription types. This provides the finest level of control over API key usage.

Use cases:

• Restricting a front-end API key to only the methods your application needs
• Setting lower limits for resource-intensive methods like getProgramAccounts
• Allowing higher limits for lightweight methods like getBlockhash

Per-IP Limits

Per-IP limits apply rate restrictions individually to each unique client IP address rather than aggregating across all traffic.

Use cases:

• Protecting publicly exposed front-end credentials by limiting each user's request rate
• Preventing a single client from monopolizing your rate limit allocation
• Detecting and mitigating abuse from specific IP addresses

Configuration Guide

Custom rate limits are configured during the API key creation or editing process. Navigate to the API Keys page from your Stack's homepage to get started.

Check Account Limits

Before configuring custom rate limits, review your account-wide limits on the Account Limits page. Custom rate limits cannot exceed your plan's maximum rates.

For RPC Services (solana-mainnet/solana-devnet)

Custom RPC request limits

Credential-Wide Limits:

Set overall RPS limit and limit per IP address to control total traffic using this credential.

Set limits for all methods

Method-Specific Limits:

Click "Add RPC Method" or "Add Subscription Method" to set limits for individual methods.

Set limits for specific RPC methods

When adding method-specific limits:

1. Select the method from the dropdown
2. Enter Total Rate Limit: Overall requests per second for this method
3. Enter Rate Limit Per IP: Requests per second per IP address (optional)
4. Click Add and repeat for additional methods

Method-specific limits override credential-wide limits for the configured methods. Unspecified methods use credential-wide limits or account-wide limits as fallback.

For ChainStream

Set limits for ChainStream

Similar to RPC services, you can set credential-wide and method-specific limits for ChainStream subscriptions.

ChainStream Requirements

Ensure ChainStream is enabled on your account before configuring limits.

WebSocket Connection Limits

WebSocket connection limits

Control the maximum number of WebSocket connections allowed by the credential:

• Maximum WebSocket Connections: Overall connection limit for the credential
• Maximum Connections Per IP: Limit connections from a single IP address

Connection Limit Rules

• Setting either value to zero blocks all WebSocket traffic
• Connection limits must be below your account maximum
• Applies to both Solana WebSocket methods and ChainStream

Examples

Example 1: Protecting a Front-End RPC Endpoint

Consider a simple React application using web3.js to display information about a user's wallet, such as token balances and recent transactions. If you're new to making RPC calls, see Make Your First RPC Call for a tutorial. The application requires these RPC methods:

• getAccountInfo
• getTokenAccountsByOwner
• getTokenAccountBalance
• getSignaturesForAddress
• getTransaction

Once an RPC URL or API key is exposed in front-end source code, it can be easily copied and exploited for unauthorized activities like NFT mints or other resource-intensive operations. You can create an API key with configuration that prevents unwanted usage while allowing legitimate traffic.

Step 1: Configure Origin Restrictions

The first step is restricting the API key to only serve requests where the header includes your domain. You can also use a wildcard to match your subdomain pattern (e.g., *.example.com).

Configure origin domain restrictions

Step 2: Disable WebSocket (If Not Needed)

If your application doesn't require WebSocket connections, you can disable them by setting the maximum WebSocket connections to 0.

Disable WebSocket connections

Step 3: Set Method-Specific Limits

Restrict the API key to only the methods your front-end requires, and set per-IP limits appropriate for a single user. This ensures that if the key is compromised, its utility is significantly diminished.

Configure method-specific per-IP limits

With this configuration, RPC calls from the front-end will operate seamlessly for users adhering to the expected traffic pattern. If the API key is compromised, its utility is significantly diminished—it's restricted to a limited set of methods and low per-IP RPS rates.

Example 2: Managing Multiple Services Under One Account

You need to run both a front-end application and a back-end service that share your account's global rate limits. Your account-wide limit is 300 RPS, and your back-end service consistently uses up to 50 RPS.

Without custom rate limits, a traffic spike in one service can cause rate-limiting for the other, potentially impacting your critical back-end service. Allocate your account's total RPS across different services to ensure that a traffic spike in one doesn't impact the other.

Step 1: Calculate Your Rate Limit Budget

Determine how to allocate your account's total rate limit across different services. For example, if your account limit is 300 RPS and your back-end consistently uses 50 RPS, allocate 250 RPS to your front-end to ensure neither service impacts the other.

Step 2: Configure Front-End API Key

Set a credential-wide RPS limit to cap the total traffic from all clients using this key.

Set credential-wide RPS limit for front-end

Step 3: Configure Back-End API Key

For your back-end service, start by restricting the credential to only accept requests from your back-end server's IP address.

Restrict API key to specific IP address

Then set method-specific limits for only the RPC methods your back-end requires. For example, if it only needs getAccountInfo:

Configure method-specific limit for getAccountInfo

If your back-end uses ChainStream, configure subscription limits for the specific methods needed:

Configure ChainStream subscription limits

With this configuration, your front-end and back-end services won't interfere with each other's rate limits. As you add more services, you can adjust the limits on existing credentials as needed. This approach can also manage limits across development environments, user groups, or deployments.

FAQ and Troubleshooting

How do I know if I'm hitting rate limits?

Rate limit responses return HTTP 429 status codes. You can monitor your usage in the RPC Analytics dashboard. See Observability to learn how to inspect logs and metrics when diagnosing throttling, review Rate Limits and plans/pricing for plan-specific limits, or configure custom rate limits per API key.

Are there rate limits for WebSocket subscriptions?

Yes. Each plan defines ceilings for active WebSocket connections, total subscriptions, and per-method concurrency, plus optional per-IP enforcement. Review the WebSocket limits table for your tier, check plans/pricing for current allowances, and use custom rate limits to set credential-specific caps (connections, subscriptions, or per-method) when you need finer control.

Can I have multiple subscriptions on one WebSocket connection?

Yes. A single connection can host hundreds of subscriptions (Standard Mode: up to 100 per connection; Scale Mode: up to 600). Each *Subscribe call returns a numeric ID—store it so you can *Unsubscribe later and keep the connection within limits. Reuse connections when possible to avoid extra handshakes, but remove idle subscriptions so they do not count toward your plan's method-specific caps (see Rate Limits and plans/pricing for details). If a connection closes, reconnect once and resubscribe using the IDs you tracked.

What's the difference between WebSocket subscriptions and ChainStream?

Standard WebSocket subscriptions connect directly to whichever validator your connection reaches and expose the base Solana RPC methods (slotSubscribe, logsSubscribe, accountSubscribe, etc.). That keeps them lightweight and available on every plan, but you own the operational work: detecting missed slots, replaying signatures, managing ordering, and reconciling state when the validator you hit lags or restarts.

ChainStream is a separate endpoint (wss://solana-mainnet.chainstream.syndica.io/api-key/...) that fans out each subscription across multiple validators. The service delivers the earliest notification using a "fastest wins" strategy, backfills if a source misses data, and deduplicates events before they reach your client. It also unlocks capabilities standard WebSockets do not provide:

• transactionsSubscribe, blockSubscribe, and encodedBlockSubscribe for full transaction/block payload streaming.
• Rich account filtering via all, oneOf, and exclude matchers plus the verified flag for multi-validator confirmation.
• Built-in delivery guarantees so you no longer maintain resend buffers or custom analytics.

ChainStream requires Scale Mode or higher (see plans/pricing); standard WebSockets work on all plans.

How many concurrent ChainStream streams can I have?

Scale Mode includes one ChainStream subscription, and you can add up to nine additional subscriptions ($0.14/hour each) for a total of ten concurrent streams per account. Each subscription maps to one WebSocket connection that can host multiple event subscriptions. Configure custom rate limits for ChainStream per API key as needed, and review plans/pricing for the current limits by tier.

Related Resources

• API Keys Overview - Learn about API key management
• Rate Limits Reference - View default rate limits by plan
• Error Handling - Handle rate limit errors in your code
• Observability - Monitor your API usage
• Account Limits - View your current limits