Verify Social Accounts

​

What is Base Verify?

• Token-gated airdrops or daily rewards
• Exclusive content access (e.g., creator coins)
• Identity-based rewards and loyalty programs

​

Core concepts

​

Provider

​

Verification

​

Trait

• verified: true — X account has blue checkmark
• coinbase_one_active: true — active Coinbase One subscription
• followers: gt:1000 — X account has over 1,000 followers
• followers_count: gte:5000 — Instagram account with 5,000+ followers
• video_count: gte:50 — TikTok account with 50+ videos

​

Action

• claim_daily_reward — claiming a daily reward
• join_allowlist — joining an exclusive allowlist
• unlock_premium_content — accessing gated content
• participate_in_raffle — entering a raffle

​

How actions work

resources: [
  'urn:verify:provider:x',
  'urn:verify:action:claim_daily_reward'
]

{
  "token": "abc123...",
  "action": "claim_daily_reward",
  "wallet": "0x1234..."
}

​

Why actions matter

• User verifies X account with action claim_airdrop → Token: abc123
• Same X account with action join_allowlist → Token: def456 (different)
• Same X account with action claim_airdrop again → Token: abc123 (same as first)

• Multiple campaigns — run separate airdrops without interference
• Feature gating — different tokens for different premium features
• Time-based events — new action per event (e.g., raffle_jan_2025, raffle_feb_2025)

​

Choosing action names

​

Token — Sybil resistance

​

How it works

1. Wallet A verifies an X account → Base Verify returns Token: abc123 → you have never seen it, so grant the airdrop.
2. The same X account tries again with Wallet B → Base Verify returns Token: abc123 → you have seen it, so block the duplicate claim.

​

Token properties

• Deterministic — the same provider account always produces the same token
• Unique per provider — a user’s X token is different from their Instagram token
• Unique per app — your app receives different tokens than other apps (privacy)
• Action-specific — tokens vary based on the action in your SIWE message
• Persistent — tokens don’t expire or rotate (unless the user deletes their verification)
• Trait-independent — tokens stay the same even if traits change (e.g., follower count increases)

​

How to store tokens

{
  token: "abc123...",
  walletAddress: "0x1234...",
  provider: "x",
  claimedAt: "2024-01-15",
}

​

Prevent double claims

async function claimAirdrop(verificationToken: string, walletAddress: string) {
  const existingClaim = await db.findClaimByToken(verificationToken);

  if (existingClaim) {
    return { error: "This X account already claimed" };
  }

  await db.createClaim({
    token: verificationToken,
    wallet: walletAddress,
    claimedAt: new Date()
  });

  return { success: true };
}

​

Architecture and flow

                    ┌─────────────┐
                    │             │  1. User connects wallet
                    │   Your      │
                    │   Mini App  │
                    │  (Frontend) │
                    └──────┬──────┘
                           │
                           │ 2. App generates SIWE message (frontend)
                           │    • Includes wallet address
                           │    • Includes provider (x, coinbase, instagram, tiktok)
                           │    • Includes traits (verified:true, followers:gt:1000)
                           │    • Includes action (e.g. claim_airdrop)
                           │
                           │ 3. User signs SIWE message with wallet
                           │
                           │ 4. Send signature + message to YOUR backend
                           │
                           ▼
                    ┌──────────────┐
                    │  Mini App    │  • Validates trait requirements
                    │  Backend     │  • Verifies signature with Base Verify API
                    │  (Your API)  │
                    └──────┬───────┘
                           │
                           ▼

   200 OK ←───────┌──────────────────┐───────→ 400
   Verified!      │                  │         User has account
   (DONE)         │  Base Verify API │         but traits not met
                  │  verify.base.dev │         (DONE)
                  └────────┬─────────┘
                           │
                           │ 404 Not Found
                           ▼

    5. Redirect to Base Verify Mini App
                           │
                           ▼
                    ┌──────────────────────┐
                    │  Base Verify         │  6. User completes OAuth
                    │  Mini App            │     (X, Coinbase, Instagram, TikTok)
                    │  verify.base.dev     │  7. Base Verify stores verification
                    └──────────┬───────────┘
                               │
                               │ 8. Redirects back to your app
                               ▼
                        ┌─────────────┐
                        │  Your       │  9. Check again (step 4)
                        │  Mini App   │     → Now returns 200 or 400
                        └─────────────┘

​

Your app’s responsibilities

• Generate SIWE messages with trait requirements
• Handle user wallet connection
• Redirect to the Base Verify Mini App when verification is not found
• Store the returned verification token to prevent reuse
• Keep your secret key secure on the backend

​

Base Verify’s responsibilities

• Validate SIWE signatures
• Store provider verifications (X, Coinbase, Instagram, TikTok)
• Check if verification meets trait requirements
• Facilitate OAuth flow with providers
• Return deterministic tokens for Sybil resistance

​

Response codes

​

Getting started

​

Prerequisites

1. API key — fill out the interest form to get access
2. Wallet integration — users must be able to connect and sign messages. See Authenticate users or the web React quickstart
3. Backend server — to securely call the Base Verify API and keep your secret key private. For a similar frontend-to-backend signing pattern, see Sign and verify typed data

​

Register your app

1. Your Mini App domain
2. Your redirect URI — where users return after verification (e.g., https://yourapp.com)

​

Implementation

export const config = {
  appUrl: 'https://your-app.com',
  baseVerifySecretKey: process.env.BASE_VERIFY_SECRET_KEY,
  baseVerifyApiUrl: 'https://verify.base.dev/v1',
  baseVerifyMiniAppUrl: 'https://verify.base.dev',
}

BASE_VERIFY_SECRET_KEY=your_secret_key_here

import { SiweMessage, generateNonce } from 'siwe'
import { config } from './config'

export async function generateSignature(
  signMessageFunction: (message: string) => Promise<string>,
  address: string
) {
  const resources = [
    'urn:verify:provider:x',
    'urn:verify:provider:x:verified:eq:true',
    'urn:verify:provider:x:followers:gte:100',
    'urn:verify:action:claim_airdrop'
  ]

  const siweMessage = new SiweMessage({
    domain: new URL(config.appUrl).hostname,
    address,
    statement: 'Verify your X account',
    uri: config.appUrl,
    version: '1',
    chainId: 8453,
    nonce: generateNonce(),
    issuedAt: new Date().toISOString(),
    expirationTime: new Date(Date.now() + 6 * 60 * 60 * 1000).toISOString(),
    resources,
  })

  const message = siweMessage.prepareMessage()
  const signature = await signMessageFunction(message)

  return { message, signature, address }
}

async function checkVerification(address: string) {
  const signature = await generateSignature(
    async (msg) => {
      return new Promise((resolve, reject) => {
        signMessage(
          { message: msg },
          { onSuccess: resolve, onError: reject }
        )
      })
    },
    address
  )

  const response = await fetch('/api/check-verification', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      signature: signature.signature,
      message: signature.message,
      address: address
    })
  })

  const data = await response.json();
  return data;
}

import { validateTraits } from '../../lib/trait-validator';

export default async function handler(req, res) {
  const { signature, message, address } = req.body;

  const expectedTraits = {
    'verified': 'true',
    'followers': 'gte:100'
  };

  const validation = validateTraits(message, 'x', expectedTraits);

  if (!validation.valid) {
    return res.status(400).json({
      error: 'Invalid trait requirements in message',
      details: validation.error
    });
  }

  const response = await fetch('https://verify.base.dev/v1/base_verify_token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.BASE_VERIFY_SECRET_KEY}`,
    },
    body: JSON.stringify({
      signature: signature,
      message: message,
    })
  });

  if (response.ok) {
    const data = await response.json();
    return res.status(200).json({ verified: true, token: data.token });
  } else if (response.status === 404) {
    return res.status(404).json({ verified: false, needsVerification: true });
  } else if (response.status === 400) {
    const data = await response.json();
    if (data.message === 'verification_traits_not_satisfied') {
      return res.status(400).json({ verified: false, traitsNotMet: true });
    }
  }

  return res.status(500).json({ error: 'Verification check failed' });
}

function redirectToVerifyMiniApp(provider: string) {
  const params = new URLSearchParams({
    redirect_uri: config.appUrl,
    providers: provider,
  })

  const miniAppUrl = `${config.baseVerifyMiniAppUrl}?${params.toString()}`

  const deepLink = `cbwallet://miniapp?url=${encodeURIComponent(miniAppUrl)}`
  window.open(deepLink, '_blank')
}

​

Error handling

​

API reference

​

Authentication

Authorization: Bearer YOUR_SECRET_KEY

​

POST /v1/base_verify_token

​

Request

{
  signature: string,   // SIWE signature from wallet
  message: string      // SIWE message (includes provider/traits in resources)
}

​

Example request

curl -X POST https://verify.base.dev/v1/base_verify_token \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -d '{
    "signature": "0x1234...",
    "message": "verify.base.dev wants you to sign in..."
  }'

​

Responses

{
  "token": "abc123...",
  "action": "claim_airdrop",
  "wallet": "0x1234..."
}

{
  "error": "verification_not_found"
}

{
  "code": 9,
  "message": "verification_traits_not_satisfied",
  "details": []
}

{
  "error": "unauthorized"
}

​

Mini App redirect

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

​

Trait catalog

urn:verify:provider:{provider}:{trait_name}:{operation}:{value}

​

Operations

​

Type system

• Values: "true" or "false" (as strings)
• Only supports eq operation
• Example: verified:eq:true

• Values: numbers as strings
• Supports: eq, gt, gte, lt, lte
• Example: followers:gte:1000

• Values: text strings
• Supports: eq, in
• Example: verified_type:eq:blue or verified_type:in:blue,government

​

Combining traits

resources: [
  'urn:verify:provider:x',
  'urn:verify:provider:x:verified:eq:true',
  'urn:verify:provider:x:followers:gte:10000'
]

​

Common patterns

// Bronze tier: any verified account
traits: { 'verified': 'true' }

// Silver tier: 1k+ followers
traits: { 'followers': 'gte:1000' }

// Gold tier: 10k+ followers
traits: { 'followers': 'gte:10000' }

​

Coinbase

// Check for Coinbase One subscribers
{
  provider: 'coinbase',
  traits: { 'coinbase_one_active': 'true' }
}

// Check for billed Coinbase One subscribers
{
  provider: 'coinbase',
  traits: { 'coinbase_one_billed': 'true' }
}

​

X

// Check for any verified account
{
  provider: 'x',
  traits: { 'verified': 'true' }
}

// Check for specific verification type
{
  provider: 'x',
  traits: { 'verified_type': 'blue' }
}

// Check for follower count (greater than or equal to)
{
  provider: 'x',
  traits: { 'followers': 'gte:1000' }
}

// Combine multiple traits
{
  provider: 'x',
  traits: {
    'verified': 'true',
    'followers': 'gte:10000'
  }
}

​

Instagram

// Check for follower count (greater than)
{
  provider: 'instagram',
  traits: { 'followers_count': 'gt:1000' }
}

// Check for follower count (greater than or equal to)
{
  provider: 'instagram',
  traits: { 'followers_count': 'gte:5000' }
}

// Combine multiple traits
{
  provider: 'instagram',
  traits: {
    'username': 'john_doe',
    'followers_count': 'gte:10000'
  }
}

​

TikTok

// Check for follower count
{
  provider: 'tiktok',
  traits: { 'follower_count': 'gt:1000' }
}

// Check for likes count
{
  provider: 'tiktok',
  traits: { 'likes_count': 'gte:10000' }
}

// Combine multiple traits (e.g., active creator)
{
  provider: 'tiktok',
  traits: {
    'follower_count': 'gte:5000',
    'likes_count': 'gte:100000',
    'video_count': 'gte:100'
  }
}

​

Security and privacy

​

SIWE signature requirement

• Arbitrary lookup of verification status
• Third parties checking if a wallet is verified
• Enumeration attacks

{
  domain: "your-app.com",
  address: "0x1234...",
  chainId: 8453,
  resources: [
    "urn:verify:provider:x",
    "urn:verify:provider:x:verified:eq:true",
    "urn:verify:action:claim_airdrop"
  ]
}

​

Validate trait requirements

1. Your app requires users to have 100 followers
2. User modifies the frontend to request only 10 followers
3. User signs the modified message
4. Without validation, your backend forwards the request to Base Verify
5. User gains access with fewer than 100 followers

import { validateTraits } from './lib/trait-validator';

const expectedTraits = {
  'followers': 'gte:100'
};

const validation = validateTraits(message, 'x', expectedTraits);

if (!validation.valid) {
  return res.status(400).json({
    error: 'Invalid trait requirements in message',
    details: validation.error
  });
}

​

Protect your secret key

• Include the secret key in frontend code
• Use NEXT_PUBLIC_* or similar environment variables that expose to the browser
• Commit secret keys to version control
• Share secret keys in chat, email, or documentation

• Store the secret key in backend environment variables only
• Use .env files that are gitignored
• Rotate keys immediately if accidentally exposed
• Call the Base Verify API only from your backend

​

OAuth security model

1. User initiates OAuth in the Base Verify Mini App
2. Provider (X, Instagram, etc.) authenticates the user
3. Provider returns an OAuth token to Base Verify
4. Base Verify fetches account data using the OAuth token
5. Base Verify stores the verification linked to the user’s wallet
6. OAuth token is encrypted and stored securely

​

Data storage

• Wallet addresses associated with verified provider accounts
• Provider account metadata (username, follower counts, verification status)
• OAuth tokens (encrypted, never shared with apps)
• Verification timestamps

• Users’ private keys
• Provider account passwords
• User activity or browsing history
• Any data beyond what’s needed for verification

​

User control

• Removes all stored provider data
• Invalidates future token generation
• Your app’s stored tokens become meaningless (user can’t re-verify with the same account)

​

Caching

• Cache for the user’s session (not permanently)
• Clear cache when the user disconnects their wallet
• Don’t check verification on every page load

​

Support