Verify Users Onchain

​

Summary

1. Deploy or upgrade a contract to extend BaseVerifyConsumer and declare an immutable provider and conditions (your eligibility policy).
2. Fetch a verification in your app: the user signs a SIWE message naming your contract, which you POST to POST /v1/onchain_verifications.
3. Submit the returned { identityHash, expiration, signature } to your contract, which calls registry.verifyVerification(...) and dedupes on identityHash.

• Verified X account example — gates on a verified X account.
• Coinbase One example — gates on an active Coinbase One membership.

​

What is Base Verify Onchain?

• Sybil resistance comes from the identityHash. The same real-world identity always produces the same hash for your contract, regardless of which wallet it uses, so your contract counts each real person once.
• Policy gating comes from your contract’s policy. You declare a provider and conditions (for example, X followers ≥ 10,000 or an active Coinbase One membership); Base Verify checks the user’s real credential against them and only signs when they pass.

​

Core concepts

​

Verification

• identityHash — a one-way hash of the user’s real-world identity (your dedupe key).
• policyHash — binds the verification to your contract’s policy on a specific chain. The registry recomputes it onchain, so it never travels in the response.
• expiration — unix seconds; verifications are short-lived (a few minutes).

​

identityHash

• One-way — you cannot recover the user’s identity from it.
• Per-contract — different for every contract, so identities cannot be correlated across apps.
• Cross-wallet — a second wallet for the same person produces the same hash, so your contract blocks the duplicate.

​

Policy (provider + conditions)

​

How eligibility is enforced

​

Architecture and flow

1. The user connects their wallet in your app.
2. Your app builds a SIWE message that names your contract (in the Resources line) and has the user sign it.
3. Your app posts the message and signature to the Base Verify API.
4. Base recovers the wallet from the signature, reads your contract’s provider and conditions onchain, and checks the wallet’s stored credential against them.
5. On success, Base returns a signed verification (identityHash, expiration, signature). If the user isn’t verified or doesn’t meet the conditions, it returns a 404 or 400 instead.
6. Your app submits the verification to your contract’s enroll function (or your deposit, borrow, or claim path).
7. Your contract calls registry.verifyVerification(...), which checks the signature and expiry and recomputes policyHash from your live policy. Your contract then dedupes on identityHash and lets the user participate.

​

Implementation

// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import {BaseVerifyConsumer} from "@baseverify/BaseVerifyConsumer.sol";

contract IncentiveProgram is BaseVerifyConsumer {
    mapping(bytes32 identityHash => bool enrolled) public enrolled;
    mapping(address wallet => bool active) public isParticipant;

    error AlreadyEnrolled();

    // Pass the SignerRegistry address for your chain.
    constructor(address registry_) BaseVerifyConsumer(registry_) {}

    // Your eligibility policy. Both MUST be immutable (constant / pure).
    function provider() external pure override returns (string memory) {
        return "coinbase";
    }

    function conditions() external pure override returns (Condition[] memory) {
        Condition[] memory c = new Condition[](1);
        c[0] = Condition({name: "coinbase_one_active", op: "eq", value: "true"});
        return c;
    }

    function enroll(bytes32 identityHash, uint40 expiration, bytes calldata signature) external {
        // One enrollment per real identity, across every wallet they control.
        if (enrolled[identityHash]) revert AlreadyEnrolled();

        // Binds msg.sender as the verified wallet; reverts on a bad or expired verification.
        _verify(identityHash, expiration, signature);

        enrolled[identityHash] = true;
        isParticipant[msg.sender] = true;

        // ... start accruing boosted rewards for msg.sender ...
    }
}

import { createSiweMessage, generateSiweNonce } from 'viem/siwe';

const MY_CONTRACT_ADDRESS = '0x...'; // your deployed consumer
const CHAIN_ID = 84532; // Base Sepolia

export async function fetchVerification(
  userAddress: `0x${string}`,
  signMessageAsync: (args: { message: string }) => Promise<string>,
) {
  // The statement and Resources line below are required by the API, exactly as written.
  const message = createSiweMessage({
    domain: window.location.host,
    address: userAddress,
    statement: 'Claim eligibility for a Base Verify onchain benefit.',
    uri: window.location.origin,
    version: '1',
    chainId: CHAIN_ID,
    nonce: generateSiweNonce(),
    resources: [`eip155:${CHAIN_ID}:${MY_CONTRACT_ADDRESS}`],
  });

  const signature = await signMessageAsync({ message });

  const res = await fetch('https://verify.base.dev/v1/onchain_verifications', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message, signature }),
  });

  if (!res.ok) {
    // See error handling below (e.g. 404 means send the user to Base Verify first).
    throw new Error(`verification failed: ${res.status}`);
  }

  // { identityHash, expiration, signature }
  return res.json();
}

import { INCENTIVE_PROGRAM_ABI } from './abi';

const { identityHash, expiration, signature } = await fetchVerification(userAddress, signMessageAsync);

await writeContract({
  address: MY_CONTRACT_ADDRESS,
  abi: INCENTIVE_PROGRAM_ABI,
  functionName: 'enroll',
  args: [identityHash, expiration, signature],
});

​

Error handling

https://verify.base.dev?redirect_uri={your_app_url}&providers={provider}

​

API reference

​

POST /v1/onchain_verifications

​

Request

{
  "message": "<SIWE message; its Resources line names your contract>",
  "signature": "0x<wallet signature over the message>"
}

​

Example request

curl -X POST https://verify.base.dev/v1/onchain_verifications \
  -H "Content-Type: application/json" \
  -d '{
    "message": "app.example.com wants you to sign in with your Ethereum account:...",
    "signature": "0x1234..."
  }'

​

Response 200

{
  "identityHash": "0x88c9f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "expiration": 1723497600,
  "signature": "0x4d3c2b1a..."
}

​

Contracts

​

SignerRegistry

function verifyVerification(
    address user,
    bytes32 identityHash,
    uint40 expiration,
    bytes calldata signature
) external view;
// Reverts VerificationExpired(expiration) when block.timestamp > expiration.
// Reverts InvalidSignature() when the signature cannot be recovered.
// Reverts NotSigner(signer) when the recovered signer is not on the allowlist.

​

BaseVerifyConsumer

abstract contract BaseVerifyConsumer {
    struct Condition {
        string name;  // e.g. "followers"
        string op;    // eq | gt | gte | lt | lte | in
        string value; // e.g. "1000"
    }

    // Your eligibility policy — MUST be immutable (constant / pure).
    function provider() external view virtual returns (string memory);
    function conditions() external view virtual returns (Condition[] memory);

    // Optional: reject credentials last authenticated before this block. Return 0 for no cutoff.
    function cutoffBlock() external view virtual returns (uint256);

    // Passes msg.sender as the verified wallet, so a verification can only be spent by its owner.
    function _verify(bytes32 identityHash, uint40 expiration, bytes calldata signature) internal view;
}

​

Supported providers and conditions

​

Security

​

What Base Verify enforces

• Eligibility is checked against the user’s real credential, read from your contract’s policy, so users cannot fake conditions.
• One identity, one action, via the deterministic identityHash you dedupe on.
• Verifications are bound to your contract and chain and expire quickly (a few minutes).
• Only the signing wallet can submit a verification, so it cannot be front-run out of the mempool (when you extend BaseVerifyConsumer and pass msg.sender).

​

Requirements

• Keep your policy (provider and conditions) immutable.
• Dedupe on identityHash in your claim path.
• Treat a successful check as proof of a unique verified identity, not of any specific account or personal data.

​

Support