Advanced Concepts

Request Affinity

Usually requests are balanced across nodes to ensure reliability and minimize latencies, however, it can sometimes be useful to have sequential RPC requests go to the same node for a "sequentially consistent" view of the network.

In order to ensure that sequential RPC requests go to the same node, Syndica offers the X-Syndica-Affinity header, which allows fine-grained control on how to route RPC requests.

An example use-case for this level of control 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.

info

Leaving X-Syndica-Affinity unset and allowing the default behavior is almost always what you want, this will cause default routing which makes no guarantees but is optimized for best performance and reliability. This is the same behavior as setting X-Syndica-Affinity to default.

Key

Setting the X-Syndica-Affinity header value to key will ensure that all requests with the same string value in the X-Syndica-Affinity-Key header will be processed by the same RPC client. If the X-Syndica-Affinity-Key header is not present, then all requests from the same public IP will be processed by the same RPC node. 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: 'some string'" \
-d '{"jsonrpc":"2.0","id":"1", "method":"getHealth"}'

This is an advanced feature and is meant for very specific use cases and must be used

with care. You must ensure the public IPs or X-Syndica-Affinity-Key values (if set) are distributed across all requests being made, requests that are not properly distributed will be rate limited. :::

Node

All RPC calls within the API request body will be processed by the same RPC node, this is useful to have all RPC calls within a batch request be processed on the same node.

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":"getHealth"}'