Skip to main content

How We Proxy RPC Requests for Marketplace Partners

Updated on
Mar 21, 2023

10 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 to create an RPC Add-on for Marketplace” 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.

Request/Response Marketplace Cycle

On your side as a partner, you should be doing a lookup to confirm that the add-on is still active for the customer in question, they have not exceeded any plan limits and then servicing the response as quickly as possible.

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

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. You should make sure that there is no expiration date that has passed for this customer id and that the customer has not exceeded their allocated requests for the plan they selected.

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:

palm
bnb-smart-chain
avalanche
celo
optimistic-ethereum
algorand
polygon
arbitrum
solana
gnosis
fantom
ethereum
harmony
bitcoin
stacks
arbitrum-nova
near

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

palm-testnet
palm-mainnet
bsc
avalanche-mainnet
avalanche-testnet
celo-mainnet
optimism
algorand-mainnet
algorand-testnet
algorand-betanet
matic
matic-testnet
arbitrum-mainnet
solana-mainnet
solana-testnet
solana-devnet
xdai
fantom
mainnet
btc
rinkeby
optimism-goerli
optimism-kovan
bsc-testnet
btc-testnet
harmony-testnet
arbitrum-goerli
stacks-mainnet
harmony-mainnet
arbitrum-testnet
nova-mainnet
ropsten
ethereum-goerli
kovan
stacks-testnet
near-testnet
near-mainnet

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

We <3 Feedback!

If you have any feedback or questions on this guide, let us know here! We’d love to hear from you!

Share this guide