Integrate Claimr widget into your dApp

If your dApp already connects the user’s wallet, the Claimr widget can use that wallet instead of asking the user to connect again. Your app stays in charge of the wallet: the widget asks, and your code decides how to connect, sign, and send transactions. This setup is ideal for dApps that use custom or anonymous wallet layers, such as embedded wallet providers or flows that require privacy. The user connects once, at the level of your app, and never sees a second wallet prompt from the widget. In this tutorial, you will:

Configure the campaign to sign users in with their wallet.
Load the widget in dApp mode.
Answer the widget’s wallet requests with your app’s wallet.
Keep the widget’s session in sync when the wallet disconnects or changes.

The code examples use React with wagmi and RainbowKit. The same approach works with any wallet library and framework: only the calls inside the handler change.

Prerequisites

A React app that already connects wallets with wagmi and RainbowKit, and renders inside WagmiProvider and RainbowKitProvider.
The Claimr widget set up with the shared loader, a provider, and a widget component, as described in Integrate Claimr into a React app. For Next.js or Vue, follow Next.js or Vue and Nuxt instead.

Configure the campaign

Open the sign-in options

In the Claimr admin panel, open your campaign, click Settings in the left-hand menu, then select Sign-in options.

Set the sign-in parameters

Require login to start a task: users must sign in with their wallet before they can begin any task. Claimr needs this to link actions to a wallet address.
Require token to start campaign (optional): users need a specific token to access the campaign.
Wallet change is disabled (optional): prevents users from switching wallets mid-session.
Disable users merge (optional): stops Claimr from merging user identities across sign-in methods.

Configure wallet sign-in

Select Wallet in the Select sign-in services field, select your blockchain in the Chains field, and enter a message in the Wallet message field. Users see this message when they sign, so describe why they are signing.

Add platform: 'dapp' to the loader configuration in your Claimr provider. This tells the widget to send wallet operations to your app instead of looking for a wallet extension on its own.

loadClaimr({
  organization: import.meta.env.VITE_CLAIMR_ORGANIZATION,
  campaign: import.meta.env.VITE_CLAIMR_CAMPAIGN,
  container: CLAIMR_CONTAINER_ID,
  autoresize: true,
  platform: 'dapp',
});

If you embed the script tag directly instead of using the loader, add data-platform="dapp" to it.

Answer wallet requests

The widget asks your app for wallet operations through one callback, on_wallet_request. It receives an object with an op field, and must return a result or throw an error:

`op`	Receives	Return
`connect`	`namespaces`: the chains the widget can act on, in preference order	`{ address, chain }`
`sign_message`	`address`, `message`	`{ signature }`
`send_transaction`	`chain_id`, `address`, `request`, `contract`, `method`, `args`, `abi`, `fee`	`{ hash }`
`disconnect`	None	`{}`

Throwing tells the widget the operation failed, and the widget shows the error right away instead of waiting. Create a component that assigns the handler with your wagmi hooks:

src/claimr/ClaimrWalletBridge.tsx

import { useEffect, useRef } from 'react';
import { useConnectModal } from '@rainbow-me/rainbowkit';
import { useAccount, useChainId, useDisconnect, useSignMessage, useSwitchChain, useWriteContract } from 'wagmi';
import type { Abi, Address } from 'viem';
import { getClaimr, type ClaimrWalletRequest } from '../lib/claimr';

/** Answers the widget's wallet requests with the wallet your app already manages. Render once. */
export function ClaimrWalletBridge() {
  const { address } = useAccount();
  const chainId = useChainId();
  const { openConnectModal } = useConnectModal();
  const { signMessageAsync } = useSignMessage();
  const { writeContractAsync } = useWriteContract();
  const { switchChainAsync } = useSwitchChain();
  const { disconnect } = useDisconnect();

  useEffect(() => {
    const handler = async (request: ClaimrWalletRequest) => {
      switch (request.op) {
        case 'connect':
          if (address) return { address, chain: String(chainId) };
          openConnectModal?.();
          throw new Error('The user has not connected a wallet yet');
        case 'sign_message':
          return { signature: await signMessageAsync({ message: request.message }) };
        case 'send_transaction': {
          const target = Number(request.chain_id);
          if (target !== chainId) await switchChainAsync({ chainId: target });
          const hash = await writeContractAsync({
            abi: request.abi as Abi,
            address: request.contract as Address,
            functionName: request.method,
            args: request.args,
            chainId: target,
          });
          return { hash };
        }
        case 'disconnect':
          disconnect();
          return {};
      }
    };

    // The handler closes over the latest wallet state, so reassign it when that state changes.
    const claimr = getClaimr();
    if (claimr) claimr.on_wallet_request = handler;
  }, [address, chainId, openConnectModal, signMessageAsync, writeContractAsync, switchChainAsync, disconnect]);

  // Log the widget out when the wallet disconnects or changes. Comparing with the previous address
  // skips the page load, when wagmi briefly reports no address while it reconnects.
  const previousAddress = useRef(address);
  useEffect(() => {
    if (previousAddress.current && previousAddress.current !== address) getClaimr()?.logout();
    previousAddress.current = address;
  }, [address]);

  return null;
}

Render it inside your Claimr provider once the script has loaded, so that window.claimr exists when the handler is assigned:

const { loaded } = useClaimr();

return <>{loaded && <ClaimrWalletBridge />}</>;

send_transaction carries the transaction twice. request is the pre-encoded EIP-1193 call, and contract, method, args, and abi describe the same call at the ABI level. The example rebuilds the call with wagmi’s writeContractAsync. If your wallet library sends raw EIP-1193 requests, send request instead.

Sign the user in from your app (optional)

With on_wallet_request in place, the widget asks for a signature when the user signs in inside the widget. If your app already runs its own sign-in step, you can sign the user in to Claimr at the same moment with connect_wallet:

import { nanoid } from 'nanoid';
import { useAccount, useChainId, useSignMessage } from 'wagmi';
import { getClaimr } from '../lib/claimr';

function buildSignMessage(statement: string, domain: string, refId?: string) {
  let message = `${statement}\n\nURI:\n${domain}\n\n`;
  if (refId) message += `Referral ID:\n${refId}\n\n`;
  message += `Nonce:\n${nanoid(16)}\n\nIssued At:\n${new Date().toISOString()}`;
  return message;
}

export function useClaimrSignIn() {
  const { address } = useAccount();
  const chainId = useChainId();
  const { signMessageAsync } = useSignMessage();

  return async () => {
    if (!address) return;
    const refId = new URLSearchParams(window.location.search).get('ref') ?? undefined;
    const message = buildSignMessage('Sign in to My dApp quests', window.location.origin, refId);
    const signature = await signMessageAsync({ message });
    getClaimr()?.connect_wallet(address, signature, message, chainId);
  };
}

connect_wallet is safe to call before the widget finishes loading: the loader keeps the wallet and passes it on when the campaign loads. The loader also remembers the wallet address across page loads.

How it works

When the user opens the app:

Your app loads, and the Claimr provider loads the widget script in dApp mode.
ClaimrWalletBridge assigns on_wallet_request.
The widget renders inside its container.

When the user signs in to the widget:

The widget sends a connect request. Your handler returns the connected address, or opens the RainbowKit modal if no wallet is connected.
The widget sends a sign_message request with its sign-in message. Your handler signs it with the user’s wallet.
Claimr verifies the signature and signs the user in.

When a task needs an on-chain action, such as minting an NFT:

The widget sends a send_transaction request.
Your handler switches the chain if needed, sends the transaction, and returns its hash.
Claimr verifies the transaction.

When the wallet disconnects or changes, the bridge calls logout(), so the widget does not keep a session for a wallet your app has let go of.

Summary

Method or callback	Called by	Purpose
`on_wallet_request`	Claimr widget	Ask your app to connect, sign, send, or disconnect. One callback, with a real result for every request.
`connect_wallet`	Your app	Sign the user in to Claimr with a signature your app already collected.
`logout`	Your app	End the Claimr session when the wallet disconnects or changes.
`on_request`	Claimr widget	The earlier transaction-only callback. Still supported, and used only when `on_wallet_request` is not set.

See the SDK guide for the full wallet callback reference.

API Guide

Webhooks Guide

SDK Guide

Framework Integration

Guides

Integrate Claimr widget into your dApp

Prerequisites

Configure the campaign

Load the widget in dApp mode

Answer wallet requests

Sign the user in from your app (optional)

How it works

Summary

​Prerequisites

​Configure the campaign

​Load the widget in dApp mode

​Answer wallet requests

​Sign the user in from your app (optional)

​How it works

​Summary

Prerequisites

Configure the campaign

Load the widget in dApp mode

Answer wallet requests

Sign the user in from your app (optional)

How it works

Summary