Skip to main content

How to Build a Marketplace Add-On

Updated on
Oct 09, 2025
All
QuickNode Product
Marketplace
Marketplace Partner

9 min read

Overview​

This guide provides a step-by-step walkthrough of the technical process for building, testing, and preparing any type of add-on for the QuickNode Marketplace. It is the central technical resource for developers who are ready to begin implementation.

What You Will Do​


  • Learn about developing an add-on for QuickNode Marketplace
  • Prepare specific configuration details you need for the submission form
  • Implement a required health check endpoint
  • Test your add-on locally to ensure it's ready for submission

Prerequisites​

This guide assumes you have already completed the initial onboarding steps. Before you begin, you should have:


  1. A QuickNode Marketplace Partner account. If you don't have a partner account, please follow the steps in our Getting Started with the Marketplace guide to apply for one.
  2. Chosen Your Add-on Type. You should know whether you are building a JSON-RPC, REST, or External add-on.
  3. Chosen an Authentication Method. You should be familiar with the available options and have a plan for which to implement. For a detailed review, see our Authentication guide.
Already Have an Existing API or Service?

If you have an existing service that you want to list on the Marketplace, the process is more about integration than building from scratch. You can follow a more direct path through this guide.

Your primary focus will be on:

  • Choosing the Right Authentication Method: You can likely use a simpler method like Header-Based Authentication if your API already uses keys, or No Authentication if it's a public service. Review our Authentication guide to confirm the best fit.
  • Preparing Configuration Details: Collect the required URLs, parameters, and other details for your add-on type.
  • Marketing & Business Details: Head over to the Marketing & Business Details guide to prepare your listing information such as title, description, screenshots, icon assets, and pricing plans.

Step 1: Set Up Your Development Environment​

You can build your add-on in any language or framework you prefer, as long as it meets Marketplace requirements (authentication, health check, and provisioning flows if applicable). QuickNode doesn’t lock you into a specific stack, so choose the tools you’re most comfortable with.

For developers who want a head start, we provide starter templates that already include:

  • Provisioning API authentication method (HTTP Basic Auth already included to protect the provisioning endpoints)
  • A health check endpoint
  • A dashboard view with Single Sign-On (SSO) using JSON Web Tokens (JWT)
  • Sample implementation of custom RPC methods

Available starter repositories:

These templates are primarily designed around RPC method add-ons. If you’re building a REST or External add-on, you can still use them for reference, or implement your own stack as long as you follow the required patterns.

Installing the QuickNode Marketplace CLI​

The QuickNode Marketplace CLI is an essential tool for simulating requests from QuickNode to your local development server.

It allows you to test your add-on’s functionality directly in your local development environment or on a server, including:

  • Health check endpoint
  • Provisioning endpoints (if applicable)
  • RPC methods (if applicable, including different plans, networks, chains, etc.)
  • SSO implementation for the dashboard view

To install the CLI, follow these steps:


  1. Clone the repository.
git clone https://github.com/quiknode-labs/qn-marketplace-cli.git
cd qn-marketplace-cli

  1. Install go if you don’t have it already. You can use Homebrew on macOS or Linux, or download the binary from the Go website.
brew install go

  1. Build the CLI.
go build -o bin/qn-marketplace-cli

  1. Navigate to the bin directory and run the CLI.
cd go/bin/
./qn-marketplace-cli help

Step 2: Implement Your Add-on's Core Logic​

This is where you will write the primary code for your service. Below, you will find implementation guidance for each add-on type, as well as a list of the specific details you should prepare for the submission form.

RPC Add-on​

A JSON-RPC add-on extends QuickNode’s functionality with custom RPC methods. Your server will handle JSON-RPC 2.0 request payloads. These add-ons allow developers to create specialized JSON-RPC endpoints (e.g., qn_fetchTokenBalance) that can perform tasks that go beyond standard JSON-RPC methods.


Advanced Topic: How RPC Requests are Proxied

For a deeper understanding of how QuickNode's infrastructure processes and forwards requests to your service, see our detailed guide: How We Proxy RPC Requests.

Example Implementation​

Your code must parse the incoming request, identify the method, execute your logic, and return a valid JSON-RPC 2.0 response.

// Example JSON-RPC handler in Express.js
router.post('/rpc', async (request, response) => {
    // Process the request directly - no auth needed
    const { method, params } = request.body
    
    // Your service logic here
    const result = processRequest(method, params)
    
    response.json({
        jsonrpc: '2.0',
        result: result,
        id: request.body.id
    })
})

Based on your choice of authentication method, you may need to implement additional logic to validate incoming requests. Check out our Authentication & Provisioning guide for more details and examples.

Information to Prepare for Submission​

As you build, keep the following configuration details handy for the submission form:

  • Method Name: The name of your custom method (e.g., qn_fetchTokenBalance).

  • Parameter Details: For each parameter your method accepts, you will need:

    • Name (e.g., address)
    • Data Type (e.g., string)
    • Sample Value (e.g., 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B)
    • Description (e.g., The user's Ethereum address.)

  • Upstream Service URL: The full URL where your RPC service is hosted (e.g., https://api.yourservice.com/rpc).

  • Max Retries: The number of times QuickNode should retry a request upon failure.

Step 3: Implement a Health Check Endpoint​

QuickNode actively monitors your add-on’s availability using a health check endpoint. You are required to provide an endpoint (e.g., /healthcheck or /healthz) that returns the current operational status of your service.

Your health check endpoint must be publicly accessible and not require any authentication. QuickNode will send a simple GET request to this URL.

If your service is healthy, the endpoint must return a 200 OK HTTP response code with the following JSON body:

{
  "status": "ok"
}

Any response other than 200 OK will be considered a service degradation, and QuickNode will temporarily stop allowing new users to install your add-on until the issue is resolved. Our starter repositories provide a health check endpoint that you can use as a starting point.

Step 4: Configure Authentication​

Securing your add-on is critical. Based on the method you chose during the prerequisite phase, you will now implement it in your code.

As mentioned, our starter codes come pre-configured with the Provisioning APIs method. If you are using a different method, you will need to add the logic to validate credentials. See the Authentication guide for sample implementations.

If your add-on does not require authentication, you can skip this step.

Step 5: Implement a Dashboard (Optional)​

Although not required, you can provide a dashboard for your add-on. A dashboard can give customers a place to view analytics, manage settings, or access premium features.

  • External add-ons almost always require a dashboard, since users often need an interface for API keys, analytics, or custom services.

  • RPC and REST add-ons don’t need a dashboard, but you may still offer one if you’d like to provide added value (e.g., query history, usage monitoring, onboarding instructions).

Dashboards use SSO with JWTs to authenticate users. Basically, QuickNode signs a JWT with user details and sends it to your dashboard URL, where you verify it and log the user in.

For a complete walkthrough of building and integrating a dashboard, see the related course section. Also, check out our How SSO Works for Marketplace Partners guide for more details.

Step 6: Test Your Add-on with the CLI​

Before submitting, use the Marketplace CLI to simulate requests from QuickNode and test your add-on locally.

You can explore all available commands by running:

./qn-marketplace-cli help

or get help for a specific command by running:

./qn-marketplace-cli <command> --help

Testing the Health Check​

Verify that your health check endpoint is publicly accessible and returns 200 OK.

./qn-marketplace-cli healthcheck --url http://localhost:3030/healthcheck

Testing the Provisioning API​

If you implemented Provisioning APIs, use the pudd command to confirm that all lifecycle flows are working.

./qn-marketplace-cli pudd \
  --base-url http://localhost:3030 \
  --basic-auth <base64-encoded-credentials>

Replace <base64-encoded-credentials> with your Base64-encoded username:password. For example, username:password encodes to dXNlcm5hbWU6cGFzc3dvcmQ=.

Testing RPC Methods​

If your add-on exposes JSON-RPC methods, test that requests and parameters are handled correctly.

./qn-marketplace-cli rpc \
  --rpc-url http://localhost:3030/rpc \
  --rpc-method qn_fetchTokenBalance \
  --rpc-params "[\"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\"]" \
  --basic-auth <base64-encoded-credentials> \
  --plan starter \
  --chain=ethereum \
  --network=mainnet

Testing SSO (Dashboard Integration)​

If your add-on includes a dashboard, test the SSO login flow with a signed JWT.

./qn-marketplace-cli sso \
  --url http://localhost:3030/provision \
  --jwt-secret <sso-jwt-secret> \
  --basic-auth <base64-encoded-credentials> \
  --plan starter \
  --name "Sergen" \
  --org "My Org" \
  --email test@test.com

If you need to expose your local server for testing, use a tunneling tool like ngrok. Replace http://localhost:3030 with your ngrok URL in the CLI commands.

Next Steps: Preparing for Launch​

You have now successfully built and tested your add-on locally. Your code is complete, and your integration is ready for the next phase.

The next step is to prepare your add-on’s marketing and business details, including its title, description, screenshots, and icon assets. These elements ensure your add-on is clearly presented and appealing to potential customers in the Marketplace.

To continue, head over to the Marketing & Business Details guide, where you’ll learn best practices for creating a compelling listing that aligns with QuickNode’s Marketplace standards.

We ❤️ Feedback!

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

Written by

Sergen Uysal

Last updated on
Share this guide