Skip to main content

Request Affinity

Request affinity allows you to control how Syndica routes sequential RPC requests across nodes. By default, requests are load-balanced across nodes for optimal performance and reliability, but certain use cases benefit from sequential consistency—ensuring requests go to the same node.

Automatic Key Affinity​

Syndica automatically applies key affinity to the following methods, covering the most common request patterns where sequential consistency is needed:

  • isBlockhashValid
  • getLatestBlockhash
  • sendTransaction
  • simulateTransaction

You don't need to use affinity headers for these methods—they already route to the same node automatically based on your request context. This ensures blockhash validation and transaction simulation happen on consistent state.

When to Use Request Affinity​

Use explicit affinity headers only when you need sequential consistency for other methods. An example use case is when using the getSlot RPC method. Sending repeated getSlot requests to the same RPC node will always return a value greater than or equal to the previous one, as slot numbers continually increment. However, sending these requests to different RPC nodes can result in receiving a slot number lower than the previous one due to discrepancies in slot generation between nodes, with some nodes potentially lagging behind others.

Default Behavior

Leaving X-Syndica-Affinity unset allows the default behavior, which is optimized for best performance and reliability. This is the same as setting X-Syndica-Affinity to default. Use default routing unless you have a specific need for sequential consistency.

Affinity Modes​

Syndica supports three affinity modes via the X-Syndica-Affinity header:

  • default - Standard load balancing (recommended for most use cases)
  • key - Route requests by a custom key or IP address
  • node - Route all calls in a batch request to the same node

Default Mode​

Standard load-balanced routing with no affinity guarantees. This is the recommended mode for most applications.

curl https://solana-mainnet.api.syndica.io/ \
-X POST \
-H "Content-Type: application/json" \
-H "X-Syndica-Api-Key: <YOUR_API_KEY>" \
-d '{"jsonrpc":"2.0","id":"1", "method":"getHealth"}'

Key Affinity​

Setting X-Syndica-Affinity to key ensures all requests with the same X-Syndica-Affinity-Key value are processed by the same RPC node. If X-Syndica-Affinity-Key is not provided, requests from the same public IP address are routed to the same node.

The X-Syndica-Affinity-Key must be a UTF-8 string that is 40 bytes or less in size.

curl https://solana-mainnet.api.syndica.io/ \
-X POST \
-H "Content-Type: application/json" \
-H "X-Syndica-Api-Key: <YOUR_API_KEY>" \
-H "X-Syndica-Affinity: key" \
-H "X-Syndica-Affinity-Key: my-session-id-12345" \
-d '{"jsonrpc":"2.0","id":"1", "method":"getSlot"}'
Use with Care

Key affinity is an advanced feature for very specific use cases. You must ensure public IPs or X-Syndica-Affinity-Key values are distributed across all requests being made. Requests that are not properly distributed will be rate limited.

Node Affinity​

Setting X-Syndica-Affinity to node ensures all RPC calls within a single batch request are processed by the same RPC node. This is useful when you need consistency across multiple calls in one request.

curl https://solana-mainnet.api.syndica.io/ \
-X POST \
-H "Content-Type: application/json" \
-H "X-Syndica-Api-Key: <YOUR_API_KEY>" \
-H "X-Syndica-Affinity: node" \
-d '[
  {"jsonrpc":"2.0","id":"1", "method":"getSlot"},
  {"jsonrpc":"2.0","id":"2", "method":"getBlockHeight"}
]'

Rate Limiting with Affinity​

When using key affinity, requests are subject to additional rate limiting to ensure fair resource distribution:

  • Max key affinity RPS per key: Limits requests per second for each unique affinity key
  • Distribution requirement: Keys must be distributed across your traffic to avoid concentrated load on single nodes

See the Rate Limits page for specific limits by plan tier.

FAQ and Troubleshooting​

Why am I getting inconsistent results between calls?

This can happen when requests hit different nodes with slightly different states. To ensure consistency:

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.

What's the difference between processed, confirmed, and finalized?

These are commitment levels that balance data freshness with reliability:

  • Processed: Latest data, lowest latency, may be subject to rollbacks.
  • Confirmed: Majority-validated, minimal rollback risk, moderate latency.
  • Finalized: Guaranteed by network finality, ~13 second latency.

Most applications use confirmed as the default balance between speed and reliability.

What You Can Do Next​