Skip to content

Quickstart: Your First Eligibility Check

Goal: Get a complete, working eligibility verification app running in less than 15 minutes.

This guide will walk you through cloning a starter repository, configuring your keys, claiming a test credential, and running a minimal Next.js application that uses the Eligibility SDK to verify a user's credentials.

Prerequisites

  • Node.js v18 or later.

  • A GitHub account with a Personal Access Token (classic) that has the read:packages scope.

  • A compatible identity wallet (e.g., Keyper, Privado) to act as the user. This wallet must be empty to start, so you can see the full issuance flow.

Step 1: Clone the Starter Kit

We've created a pre-configured Next.js starter kit with the basic backend and frontend structure already in place.

Open your terminal and clone the repository:

git clone https://github.com/redbellynetwork/eligibility-sdk-quickstart.git
cd eligibility-sdk-quickstart

Step 2: Configure NPM and Install Dependencies

The starter kit uses GitHub Packages for the @redbellynetwork scope. To install it, you must tell NPM how to find the package and how to authenticate.

  1. Create the .npmrc file: Inside the `eligibility-sdk-quickstart``` directory you cloned, create a new file named .npmrc.
  2. Add Configuration: Copy and paste the following lines into the .npmrc file. This tells NPM where to find packages under the @redbellynetwork name.
# Replace YOUR_GITHUB_TOKEN with your actual token
@redbellynetwork:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
  1. Install Packages: Now, run the installation. You will need to provide your GitHub Personal Access Token to authenticate.
npm i @redbellynetwork/eligibility-sdk

Step 3: Configure Your Environment

Your application needs a few secret keys to function.

  1. Copy the example environment file:
cp env.local.example .env.local

  1. Edit .env.local: You need to fill in two values:

  2. REDBELLY_API_KEY: Your API key for the verifier service. Contact support if you don't have one.

  3. ALLOWED_ISSUER_DID: The DID of the credential issuer you trust. For this Quickstart, we'll use the Redbelly Testnet issuer.

Your file should look like this:

# .env.local

# Your secret API key provided by the Redbelly team
REDBELLY_API_KEY="your_api_key_goes_here"

# The DID of the issuer we trust for this example
ALLOWED_ISSUER_DID="did:receptor:redbelly:testnet:31K82iKCtE6ciDc7oAr3T5EpjZb4S1EFM7c4xJaWkM2"
SENDER_DID="did:receptor:redbelly:testnet:31Jz2omB1fL33eGkuwi8vXKuxfS3XTck7X58XWuovE" # The DID of the sender (your application)

Step 4: Run the Application

The starter kit is configured to run both the backend verifier and the frontend application at the same time.

npm run dev

This will:

  • Start the Next.js at http://localhost:3000.

Step 5: Start ngrok Tunnel

Since the SDK relies on callbacks from the mobile wallet, your local http://localhost:3000 server isn’t directly accessible. To make it reachable, you’ll need to start an ngrok tunnel:

ngrok http 3000

You will see an output like:

Forwarding    https://randomstring.ngrok.io -> http://localhost:3000

This command will generate a secure public URL (for example: https://randomstring.ngrok.io).

Copy this URL — it will act as your base URL during the flow. When the wallet scans the QR code, it will use this URL to call back into your local application.

Step 6: Get Your Test Credentials

Before you can prove your eligibility, your digital wallet needs to hold the right credentials. For this test, you'll get a sample "KYC Verified" credential from our demo issuer.

  1. In your browser, navigate to our Demo Credential Faucet: (under development)

  2. Click the "Claim Test KYC Credential" button. A QR code will appear.

  3. Open your Keyper Wallet and scan the QR code.

  4. Your wallet will show you the details of the credential you are about to receive. Approve the request to add it to your wallet.

Your wallet now holds a test credential signed by the same Testnet Issuer you configured back in Step 3.

Step 7: Perform a Verification

Now, let's return to your running application at https://randomstring.ngrok.io.

  1. Click the "Verify Eligibility" button. A QR code modal will appear.

  2. Open your Keyper Wallet and scan this new QR code.

  3. Your wallet will now ask you to approve sharing proof that you hold a valid KYC credential. It will not share the credential itself.

  4. Once you approve, the modal on the webpage will close, and a "Success!" message will appear, showing the claims you just verified.

Congratulations! You have successfully completed the full issuance and verification flow using the Redbelly Eligibility SDK.

Next Steps

  • Explore the Code: Dive into the /app/api/proxy/route.ts (the secure backend proxy) and /app/pages.tsx (the frontend client) files in the starter kit to see how they work.

  • Learn the Core Concepts: Read our Receptor documentation page to understand the "why" behind the technology.

  • Deep Dive: Use the other pages in this documentation to learn about advanced configuration, error handling, and more.