Quickstart

We will be creating two endpoints

1. Start Verification
2. Process Verification

Import the library

import { ReclaimProofRequest } from '@reclaimprotocol/js-sdk';

Part 1 : Start Verification Endpoint

Init

const reclaimProofRequest = await ReclaimProofRequest.init(
    process.env.RECLAIMPROTOCOL_APP_ID,
    process.env.RECLAIMPROTOCOL_APP_SECRET,
    'ff4d7afe-4b78-4795-9429-d20df2deaad7' // Example. Replace with provider ID
)

• You can get the RECLAIMPROTOCOL_APP_ID and RECLAIMPROTOCOL_APP_SECRET using this guide
• The PROVIDER_ID is the proof you want the user to generate. You can see all the available providers here. If you are just testing the flow, you can use the provider id ff4d7afe-4b78-4795-9429-d20df2deaad7.

Success Callback

reclaimProofRequest.setAppCallbackUrl(url, true);
// true : sets contentType to JSON

This is the endpoint to which the proofs will be submitted after the verification - this is where you will process the verification. We will define this endpoint in the next section.

Set Context

You can set context to the proof request that helps identify the request when you receive it back in the callback once the proof is generated.

const address = "unique-user-id"; 
const message = "some meta data for processing on callback";
reclaimProofRequest.setContext(address, message)

• address : this is usually a unique identifier for the user. This could be an email address, a wallet address, or just a session id generated on your system. Set the variable you'd need to identify the user in the callback endpoint, when the proof is sent to your backend.
• message : this is an open field where you can add any other information that you want passed around from the build request to the callback endpoint. You can stringify jsons here for convenience.

Both context address and context message are tamper resistant. Even if the user tries to edit one byte, the proof verification will fail.

Open verification

After configuring your verification request in ReclaimProofRequest object on your NodeJs backend, you can export entire config as a JSON string and send it to your frontend.

const exportedProofRequestJsonString = reclaimProofRequest.toJsonString();

This can be used to create a ReclaimProofRequest using same SDK on frontend where you can trigger a web-based verification or you can use this config to start an in-app verification journey using our in-app SDK.

Option A: Web Frontend Web verification journey

To continue on web frontend, with @reclaimprotocol/js-sdk in your frontend dependencies, you have to import reclaim's proof request json string to make ReclaimProofRequest on frontend

const reclaimProofRequest = ReclaimProofRequest.fromJsonString(configJson);

In SDK, ReclaimProofRequest provides a triggerReclaimFlow() method that automatically handles the verification process for web-based verification across different platforms and devices. This method intelligently chooses the best verification method based on the user's environment.

How to use triggerReclaimFlow()

The triggerReclaimFlow() method supports two verification modes via verificationMode:

• 'portal' (default): Opens a new reclaim web page for remote browser verification. Opens reclaim web page in a new tab by default, or embeds reclaim web page in an iframe when target is provided.
• 'app': Opens Reclaim's Verifier app to do verification on client mobile device.

The method returns a FlowHandle that lets you close the flow programmatically:

1. Portal flow (default) — opens in new tab

const handle = await reclaimProofRequest.triggerReclaimFlow();
handle.tab;    // Window reference to the opened tab
handle.close(); // close tab and stop polling

2. Embedded — portal loads inside a DOM element as an iframe

const handle = await reclaimProofRequest.triggerReclaimFlow({
  target: document.getElementById('reclaim-container')
});
handle.iframe; // HTMLIFrameElement reference
handle.iframe?.style.height = '700px'; // customize the iframe
handle.close(); // remove iframe and stop polling

3. Verifier app flow

const handle = await reclaimProofRequest.triggerReclaimFlow({ verificationMode: 'app' });
handle.close(); // stop polling

Option B: In App Verification Flow

If you have an app, you can integrate one of reclaim's in-app SDK for embedding reclaim's entire verification experience in your native app.

This is available for Android, iOS, React Native, Flutter & Capacitor. To learn more, go to InApp Integration docs.

You can follow start verification documentation for each platform to learn more about integrating with them. For example, React Native.

Store the Provider Version

  const { providerId, providerVersion } = reclaimProofRequest.getProviderVersion();

• Store (providerId, providerVersion) corresponding to this user's uuid that you stored in address. You will need this providerVersion

More options

Part 2 : Process Verification endpoint

Be sure to expose this endpoint over the public internet. If testing locally, use Ngrok

Verify Proofs

import { verifyProof } from '@reclaimprotocol/js-sdk';

The easiest way is to use getProviderVersion() which returns the provider ID and exact version used in the session — pass it directly as the config:

const proofs = await request.json();
const providerVersion = reclaimProofRequest.getProviderVersion();
const { isVerified, data, error } = await verifyProof(proofs, providerVersion);
if (isVerified) {
  console.log("Proof is valid");
} else {
  console.log("Proof is invalid, reason:", error);
}

Or, by manually providing the provider details:

const { isVerified, data } = await verifyProof(proofs, {
  providerId: PROVIDER_ID,
  providerVersion: "1.0.0", // The exact provider version used in the session
  allowedTags: ["ai"] // Optionally allow patches from ai
});

Or, with a known hash:

const { isVerified, data, error } = await verifyProof(proofs, { hashes: ['0xAbC...'] });

You can get the provider version:

• [ Recommended ] Storing the provider version when initiating the verification.
• You can also hardcode the expected provider version by picking the latest version from the developer tool.

Continue Business Logic

const { context, extractedParameters } = data[0];
// Note if there are multiple proofs, you will have to iterate over data[]

• context.address & context.message: Same as address and message set in Set Context. Use this to map user to verification.
• extractedParameters : JSON object of all the data that has been extracted and verified. You can see the structure of each provider's response in the Provider Explorer.

More options

Source code

• Sample implementation