3 min read

Overview

If you’re building a QuickNode add-on that makes use of JSON-RPC methods, then this guide is for you. In it, we’ll cover how QuickNode creates and shares the identifiers used for billing, as well as how we use these IDs during the request/response cycle for a given RPC method from your add-on.

Understanding QuickNode ID’s

We create a single ID for each customer on QuickNode, which takes the form of a Sha256 hash. During the add-on provisioning process, we share this ID with you, so you can store which customers should get access to which services you provide. It comes over in the payload for provisioning, updating, and de-provisioning, as discussed in the How Provisioning Works for Marketplace Partners article.

The ID is unique to a customer, who may have several installs of your add-on, which are billed on an account basis.

Request/Response Lifecycle

We’ve created a diagram for your convenience which is below, but when a request comes into QuickNodes infrastructure, this is how we handle it for RPC add-ons at a high level:

1. Customer sends request with RPC method(s).
2. QuickNode sends over JSON-RPC request with custom headers for quicknode id.
3. Partner verifies customer is authorized to make request, services request and returns response.
4. QuickNode bundles partner response into appropriate slot to return to customer.

On your side as a partner, you should focus on confirming that the add-on is still active for the customer and then servicing the response as quickly as possible. QuickNode will enforce the add-on plan's Request Per Seconds Limit (RPS Limit) and Monthly Requests Limit for customers, if you have set them up.

Condition set by you	Enforcement by QuickNode
Both RPS and Monthly Limits are set	Enforces both limits
Only RPS Limit is set	Enforces only the RPS Limit
Only Monthly Requests Limit is set	Enforces only the Monthly Requests Limit
No limits are set	No enforcement

With that in mind, we’re going to look specifically at the custom headers we send.

Headers

Whenever we send a request to your upstream, you should absolutely examine this header:

X-QUICKNODE-ID: 969d539bf782b561aeff148b2a94cc3705720f3d38e147e475912e53b4e96a85

Logs for Simplified Debugging

You can now access Logs for your RPC endpoints, helping you troubleshoot issues more effectively. If you encounter an issue with your RPC calls, simply check the logs in your QuickNode dashboard to identify and resolve problems quickly. Learn more about log history limits on our pricing page.

Note - Any incoming requests that include X-QN-TESTING in the headers are from the QuickNode development team or testing tools.

This ID represents a single paying customer, which you should have stored in your database when we sent our provisioning request.

We will also send a `X-INSTANCE-ID` header that represents the endpoints id.

You can also expect a chain (one of the following) in the `X-QN-CHAIN` header:

algorand
aptos
arbitrum
arbitrum-nova
avalanche
base
bitcoin
bnb-smart-chain
celo
ethereum
fantom
flow
gnosis
harmony
near
optimistic-ethereum
optimistic-ethereum
palm
polkadot
polygon
polygon-zkevm
scroll
solana
stacks
stellar
tron
xrp-ledger
zksync

Finally we also send over the network (one of the following) in the `X-QN-NETWORK` header:

algorand-betanet
algorand-mainnet
algorand-testnet
aptos-mainnet
aptos-testnet
arbitrum-goerli
arbitrum-mainnet
arbitrum-testnet
avalanche-mainnet
avalanche-testnet
base-goerli
base-mainnet
base-sepolia
bsc
bsc-testnet
btc
btc-testnet
celo-mainnet
dot-mainnet
ethereum-goerli
fantom
flow-mainnet
flow-testnet
harmony-mainnet
harmony-testnet
kovan
mainnet
matic
matic-testnet
near-mainnet
near-testnet
nova-mainnet
optimism
optimism
optimism-goerli
optimism-kovan
optimism-sepolia
palm-mainnet
palm-testnet
rinkeby
ropsten
scroll-mainnet
scroll-testnet
solana-devnet
solana-mainnet
solana-testnet
stacks-mainnet
stacks-testnet
stellar-mainnet
stellar-testnet
tron-mainnet
xdai
xrp-mainnet
xrp-testnet
zkevm-mainnet
zkevm-testnet
zksync-mainnet
zksync-sepolia
zksync-testnet

That’s it! If you have any questions, please reach out to us.

Subscribe to our newsletter for more articles and guides on Web3 and blockchain. If you have any questions or need further assistance, feel free to join our Discord server or provide feedback using the form below. Stay up to date with the latest by following us on Twitter (@QuickNode) and our Telegram announcement channel.

We ❤️ Feedback!

Let us know if you have any feedback or requests for new topics. We'd love to hear from you.