AlphaHub Builder Guide

Build your custom recognition system in days, not months.

The AlphaHub Builder is your control center for creating and managing your project's VerseID integration. This guide covers everything from initial setup to advanced customization, enabling you to deploy a production-ready recognition system optimized for your community.

What is an AlphaHub?

An AlphaHub is your project's customized portal within the VerseID ecosystem. It's where your users:

Discover and complete quests across 4 pathways
Earn BITS and unlock badges
Track their progression toward BEATS milestones
Build their project-specific VerseID card
Contribute 12.5% of BITS to their Macro VerseID

Think of it as your project's gamified identity layer - fully branded, completely customizable, and deeply integrated with your existing products.

Architecture Overview

You Focus On: What actions matter for your community We Handle: Infrastructure, security, scalability, 12.5% macro flow

Quick Start (5 Steps)

Step 1: Access Your AlphaHub Dashboard

Once accepted into the Vibes to Value campaign, you'll receive:

Dashboard URL: https://alphahub.verseid.io/your-project
Admin credentials
API keys
Technical documentation

First Login Checklist:

Change default password
Add team members (up to 5 admin accounts)
Review pre-configured settings
Connect your wallet for testing

Step 2: Configure Basic Settings

Project Information:

{
  "project_name": "Your Project",
  "project_slug": "your-project",
  "description": "Short description (160 chars)",
  "website": "https://yourproject.com",
  "socials": {
    "telegram": "@yourproject",
    "discord": "discord.gg/yourproject",
    "twitter": "@yourproject"
  }
}

Branding:

Primary color (hex)
Logo (SVG, 512x512px recommended)
Banner image (1200x400px)
Font choice (or use default Inter/DM Sans)

Step 3: Select Your Pathways

Every AlphaHub must include ALIGN (onboarding). Choose 2-3 additional pathways:

ALIGN (Required)

Use For: Onboarding, identity setup, basic actions

Typical Actions:

Connect wallet
Complete profile
Join Telegram/Discord
First transaction

BITS: 8-16 per action

ALPHA (Optional)

Use For: DeFi, capital deployment, high-value actions

Typical Actions:

Provide liquidity
Lock tokens
Trade volume milestones
Staking tiers

BITS: 16-64 per action

KARMA (Optional)

Use For: Social, community, cultural contribution

Typical Actions:

Content creation
Memes/artwork
Community support
Event participation

BITS: 8-32 per action

SYNERGY (Optional)

Use For: Referrals, network growth, ecosystem building

Typical Actions:

Referral bonuses
Cross-project activity
Partnership missions
Ecosystem quests

BITS: 32-128 per action

Recommended Combinations:

DeFi Protocol: ALIGN + ALPHA + SYNERGY
NFT/Gaming: ALIGN + KARMA + SYNERGY
DAO/Community: ALIGN + KARMA + ALPHA
Infrastructure: ALIGN + ALPHA + SYNERGY

Step 4: Design Your 32 Badges

Each pathway gets 8 custom badges. Use the Badge Builder UI:

Badge Structure:

{
  "badge_id": "first_trade",
  "pathway": "ALPHA",
  "name": "First Trade",
  "description": "Complete your first swap",
  "image": "url_or_upload",
  "unlock_condition": {
    "type": "action_count",
    "action": "swap",
    "count": 1
  },
  "bits_reward": 16,
  "tier": "bronze"
}

Badge Tiers (recommended):

🥉 Bronze (Easy): 1-2 actions, 8-16 BITS
🥈 Silver (Medium): 5-10 actions, 24-32 BITS
🥇 Gold (Hard): 20+ actions, 48-64 BITS
💎 Diamond (Elite): 50+ actions or rare conditions, 96-128 BITS

See Badge Customization Guide for detailed design principles and examples.

Step 5: Launch to Staging

Pre-Launch Testing:

# 1. Create test accounts (10+ users)
# 2. Complete all quest flows manually
# 3. Verify BITS distribution (87.5% local, 12.5% macro)
# 4. Check badge unlocks
# 5. Test edge cases (duplicate actions, failed transactions)
# 6. Review analytics dashboard

Staging Environment:

Test URL: https://staging.verseid.io/your-project
Test API endpoint: https://api-staging.verseid.io/v1
Sandbox wallet: Use testnet or mock wallet
Invite beta testers (50-100 users)

Dashboard Walkthrough

Home Dashboard

┌─────────────────────────────────────────────────────────┐
│  AlphaHub Dashboard - Your Project                      │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  📊 OVERVIEW                                            │
│  ┌───────────┬───────────┬───────────┬───────────┐     │
│  │   Users   │   BITS    │   BEATS   │  Badges   │     │
│  │   1,234   │  45,678   │    234    │   678     │     │
│  └───────────┴───────────┴───────────┴───────────┘     │
│                                                          │
│  📈 ACTIVITY (Last 7 Days)                              │
│  [Graph showing daily active users and BITS earned]     │
│                                                          │
│  🎯 TOP QUESTS                                          │
│  1. First Trade (892 completions)                       │
│  2. Join Discord (765 completions)                      │
│  3. Referral Bonus (543 completions)                    │
│                                                          │
└─────────────────────────────────────────────────────────┘

Key Metrics Tracked:

Total users with your project card
BITS distributed (total and by pathway)
BEATS milestones reached
Badge unlock rate
Macro VerseID flow (should be exactly 12.5%)
Quest completion rates
User retention (Day 1, 7, 30)

Pathway Manager

Configure each pathway's:

Status: Active/Inactive/Coming Soon
BITS Budget: Total BITS allocated to this pathway
Quests: List of all quests in pathway
Badges: 8 custom badges
Analytics: Completion rates, average time, drop-off points

Example Pathway Configuration:

{
  "pathway": "ALPHA",
  "status": "active",
  "bits_budget": 40000,
  "quests_count": 12,
  "badges_count": 8,
  "active_users": 456,
  "completion_rate": 68.3,
  "avg_bits_per_user": 87.6
}

Quest Builder

Quest Types:

Action-Based Quest

{
  "type": "action",
  "action_name": "swap",
  "condition": {
    "operator": ">=",
    "value": 1
  },
  "bits_reward": 16,
  "repeatable": false
}

Time-Based Quest

{
  "type": "time_gated",
  "start_date": "2025-10-15T00:00:00Z",
  "end_date": "2025-10-22T23:59:59Z",
  "action": "trade_volume",
  "condition": {
    "operator": ">=",
    "value": 1000
  },
  "bits_reward": 32,
  "bonus_multiplier": 1.5
}

Progressive Quest

{
  "type": "progressive",
  "tiers": [
    {"count": 1, "bits": 8, "badge": "bronze"},
    {"count": 10, "bits": 24, "badge": "silver"},
    {"count": 50, "bits": 64, "badge": "gold"},
    {"count": 100, "bits": 128, "badge": "diamond"}
  ],
  "action": "referrals"
}

Combo Quest (Multiple Requirements)

{
  "type": "combo",
  "requirements": [
    {"action": "join_discord", "count": 1},
    {"action": "trade", "count": 5},
    {"action": "hold_token", "days": 7}
  ],
  "bits_reward": 48,
  "badge_unlock": "combo_master"
}

Badge Studio

Badge Creation Workflow:

Upload badge image (SVG recommended, PNG accepted)
Set name and description
Choose pathway (ALIGN, ALPHA, KARMA, SYNERGY)
Define unlock condition
Set BITS reward
Assign tier (Bronze/Silver/Gold/Diamond)
Preview card appearance
Publish to staging

Badge Preview:

┌─────────────────────────────────┐
│  [Badge Image]                  │
│                                 │
│  🏆 First Trade                 │
│  Complete your first swap       │
│                                 │
│  💎 16 BITS                     │
│  🥉 Bronze Tier                 │
│  📊 892 unlocks                 │
└─────────────────────────────────┘

BITS Calibration

Distribution Settings:

Setting	Default	Range	Recommendation
BITS per Quest	16	8-128	Scale by difficulty
BEATS Threshold	4 quests	3-10	Lower = faster progression
Daily Cap	200 BITS	100-500	Prevent gaming
Macro Flow	12.5%	12.5% (fixed)	Cannot change
Local Retention	87.5%	87.5% (fixed)	Cannot change

BITS Weight Calculator:

Input: Total BITS budget = 100,000
Output per pathway:
- ALIGN (25%): 25,000 BITS
- ALPHA (40%): 40,000 BITS
- KARMA (20%): 20,000 BITS
- SYNERGY (15%): 15,000 BITS

Estimated reach:
- Avg user earns: 50-100 BITS
- Expected users: 1,000-2,000
- Local value: 87,500 BITS (stays in project)
- Macro flow: 12,500 BITS (flows to Macro VerseIDs)

Analytics Dashboard

Metrics Available:

User Metrics:

Daily/Weekly/Monthly active users
New vs returning users
Retention curves (Day 1, 7, 30, 90)
Churn rate and reasons

Engagement Metrics:

Quest completion rate (overall and per quest)
Average quests per user
BITS distribution pattern
BEATS milestones reached
Badge unlock rate

Economic Metrics:

Total BITS distributed
BITS per user (average, median, p95)
Macro flow verification (should be 12.5%)
Value per user (BITS × $BRO price)
ROI on campaign spend

Bot Detection (Vibe Oracle):

Fraud rate (<5% if working correctly)
Flagged accounts
Behavioral anomalies
Human verification rate

Export Options:

CSV export for all metrics
API access for custom dashboards
Webhook notifications for milestones
Real-time data feeds

API Integration

Authentication

All API requests require Bearer token authentication:

curl -X GET https://api.verseid.io/v1/users/0x1234.../card \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

API Key Management:

Generate in Dashboard → Settings → API Keys
Store securely (environment variables, secrets manager)
Rotate every 90 days
Use separate keys for staging and production

Core Endpoints

Award BITS

POST /api/v1/bits/award
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "user_id": "0x1234567890abcdef",
  "bits": 16,
  "action": "first_trade",
  "pathway": "ALPHA",
  "metadata": {
    "trade_value": 1000,
    "token_pair": "ETH/USDC",
    "timestamp": "2025-10-08T12:00:00Z"
  }
}

Response:

{
  "success": true,
  "bits_awarded": 16,
  "local_bits": 14,
  "macro_bits": 2,
  "new_total": 142,
  "badge_unlocked": null,
  "beat_milestone": false
}

Get User Card

GET /api/v1/users/{user_id}/card
Authorization: Bearer YOUR_API_KEY

Response:

{
  "user_id": "0x1234567890abcdef",
  "project_id": "your-project",
  "bits_total": 142,
  "beats_count": 3,
  "badges": [
    {
      "badge_id": "first_trade",
      "name": "First Trade",
      "unlocked_at": "2025-10-01T14:23:00Z"
    }
  ],
  "pathways": {
    "ALIGN": {"bits": 48, "quests_completed": 6},
    "ALPHA": {"bits": 78, "quests_completed": 4},
    "KARMA": {"bits": 16, "quests_completed": 2}
  },
  "macro_contribution": 17.75,
  "created_at": "2025-09-15T10:00:00Z",
  "last_activity": "2025-10-08T12:00:00Z"
}

List Available Quests

GET /api/v1/quests?pathway=ALPHA&status=active
Authorization: Bearer YOUR_API_KEY

Response:

{
  "quests": [
    {
      "quest_id": "first_trade",
      "name": "First Trade",
      "description": "Complete your first swap",
      "pathway": "ALPHA",
      "bits_reward": 16,
      "repeatable": false,
      "completion_count": 892,
      "completion_rate": 72.3
    }
  ],
  "total": 12,
  "page": 1
}

Track Quest Completion

POST /api/v1/quests/{quest_id}/complete
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "user_id": "0x1234567890abcdef",
  "proof": {
    "tx_hash": "0xabcdef...",
    "block_number": 18234567,
    "value": 1000
  }
}

Webhooks

Configure webhooks to receive real-time notifications:

Webhook Events:

bits.awarded - User earned BITS
badge.unlocked - User unlocked badge
beat.milestone - User reached BEAT milestone
quest.completed - Quest completion
user.created - New user created project card
fraud.detected - Vibe Oracle flagged suspicious activity

Webhook Payload Example:

{
  "event": "badge.unlocked",
  "timestamp": "2025-10-08T12:00:00Z",
  "data": {
    "user_id": "0x1234567890abcdef",
    "badge_id": "first_trade",
    "badge_name": "First Trade",
    "bits_awarded": 16,
    "pathway": "ALPHA"
  }
}

Configure Webhook:

POST /api/v1/webhooks
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "url": "https://yourproject.com/webhook/verseid",
  "events": ["bits.awarded", "badge.unlocked", "beat.milestone"],
  "secret": "your_webhook_secret"
}

Integration Patterns

Option 1: Telegram Mini App (Easiest)

Best For: Consumer-facing projects, mobile-first communities

Implementation:

We host the Mini App under your project slug
You configure pathways, badges, and quests in dashboard
Users access via Telegram: t.me/verseid_bot/your-project
Your backend sends BITS awards via API when actions complete

Pros:

✅ Zero frontend development
✅ Mobile-optimized UX
✅ 73.3% of Web3 users prefer Telegram
✅ Instant deployment

Cons:

❌ Limited UI customization
❌ Telegram dependency

Code Example:

// Your backend awards BITS when user completes action
async function onUserTrade(userId, tradeDetails) {
  await fetch('https://api.verseid.io/v1/bits/award', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VERSEID_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      user_id: userId,
      bits: 16,
      action: 'first_trade',
      pathway: 'ALPHA',
      metadata: tradeDetails
    })
  });
}

Best For: Existing web apps with custom UI

Implementation:

Install @verseid/react-widget package
Embed <VerseIDCard> component in your app
Style to match your brand
Award BITS via API

Pros:

✅ Full UI control
✅ Seamless UX within your app
✅ Custom branding
✅ React/Vue/vanilla JS support

Cons:

❌ Frontend integration required (2-3 weeks)
❌ Your domain/hosting

Code Example:

import { VerseIDCard, VerseIDProvider } from '@verseid/react-widget';

function App() {
  return (
    <VerseIDProvider
      projectId="your-project"
      apiKey={process.env.VERSEID_PUBLIC_KEY}
      theme="dark"
    >
      <VerseIDCard
        userId={currentUser.walletAddress}
        compact={false}
        showMacroFlow={true}
      />
    </VerseIDProvider>
  );
}

Customization:

<VerseIDCard
  userId="0x1234..."
  theme={{
    primaryColor: "#00A1F1",
    backgroundColor: "#1A1A1A",
    borderRadius: "12px"
  }}
  layout="horizontal"
  showBadges={true}
  showPathways={true}
  onBadgeClick={(badge) => console.log(badge)}
/>

Option 3: Full API Integration (Maximum Control)

Best For: Custom implementations, white-label solutions

Implementation:

Build your own UI from scratch
Use RESTful API for all operations
Subscribe to webhooks for real-time updates
Complete customization

Pros:

✅ Total control
✅ Any tech stack
✅ White-label ready
✅ Custom flows

Cons:

❌ Longest development time (3-4 weeks)
❌ More maintenance

Architecture:

Your Frontend
      ↓
Your Backend API
      ↓
VerseID REST API
      ↓
VerseID Infrastructure

Example Backend Service:

// Express.js example
const express = require('express');
const app = express();

// Award BITS when user completes action
app.post('/api/user/trade', async (req, res) => {
  const { userId, tradeDetails } = req.body;

  // Your business logic
  await processTradeInYourSystem(userId, tradeDetails);

  // Award BITS via VerseID API
  const result = await fetch('https://api.verseid.io/v1/bits/award', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VERSEID_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      user_id: userId,
      bits: 16,
      action: 'first_trade',
      pathway: 'ALPHA',
      metadata: tradeDetails
    })
  });

  res.json({ success: true, verseid: result });
});

// Receive webhook from VerseID
app.post('/webhook/verseid', (req, res) => {
  const { event, data } = req.body;

  if (event === 'badge.unlocked') {
    // Notify user they unlocked a badge
    notifyUser(data.user_id, `You unlocked ${data.badge_name}!`);
  }

  res.sendStatus(200);
});

Testing & QA

Staging Environment Checklist

Setup (Week 1):

Functional Testing (Week 2):

User can create project card
BITS award correctly (87.5% local, 12.5% macro)
Badges unlock when conditions met
BEATS milestones trigger at correct thresholds
Quest progress tracks accurately
Duplicate actions handled correctly
Failed transactions don't award BITS
Webhook notifications fire correctly

Integration Testing (Week 3):

Your app → VerseID API works
VerseID webhooks → Your app works
User authentication flows
Error handling (network issues, invalid data)
Rate limiting (1000 req/min)
Edge cases (simultaneous actions, race conditions)

Performance Testing (Week 4):

Security Testing:

Beta Testing Program

Phase 1: Private Beta (50 users, 1 week)

Invite your most engaged community members
Focus on finding breaking bugs
Collect qualitative feedback
Iterate quickly on critical issues

Phase 2: Public Beta (500 users, 2 weeks)

Open to wider community
Monitor metrics closely
Gather usage data
Optimize based on real behavior

Beta Checklist:

Beta announcement published
Feedback form created
Discord/Telegram support channel
Daily metrics review
Bug triage process
Community incentives (bonus BITS for beta testers)

Launch Strategy

Pre-Launch (1 Week Before)

Content Creation:

Community Prep:

Train moderators on VerseID
Create support scripts
Set up analytics tracking
Prepare launch incentives

Technical Prep:

Launch Day

Hour 0: Go Live

Hour 1-4: Monitor Closely

Watch real-time dashboard
Respond to questions immediately
Fix critical bugs (if any)
Celebrate milestones (100 users, 1000 BITS, etc.)

Hour 4-24: Engage

Host Twitter Space / AMA
Share user testimonials
Highlight badge unlocks
Post analytics screenshots

Post-Launch (First Week)

Daily Reviews:

Morning: Check overnight metrics, triage bugs
Afternoon: Community engagement, content creation
Evening: Metrics review, plan next day

Week 1 Milestones to Celebrate:

100 users
1,000 BITS distributed
50 BEATS milestones
First Diamond badge unlocked
10,000 quests completed

Optimization & Iteration

A/B Testing

What to Test:

BITS reward amounts (16 vs 24 vs 32)
Quest difficulty (5 trades vs 10 trades)
Badge unlock conditions
BEATS thresholds (4 quests vs 6 quests)

How to Test:

{
  "quest_id": "trade_volume",
  "variants": {
    "A": {"bits": 16, "requirement": 5},
    "B": {"bits": 24, "requirement": 10}
  },
  "split": 0.5,
  "metric": "completion_rate"
}

Common Optimizations

Problem: Low quest completion rate (<40%) Solutions:

Reduce difficulty
Increase BITS reward
Add tutorial/guide
Simplify instructions

Problem: High churn (users stop after first quest) Solutions:

Make first quest easier (quick win)
Show progress to next milestone
Add daily quests for retention
Push notifications for new quests

Problem: Bot activity detected Solutions:

Vibe Oracle should catch this automatically
Review flagged accounts manually
Adjust bot detection sensitivity
Require additional verification for high-value quests

Problem: Macro flow not exactly 12.5% Solutions:

This should be automatic - contact support
Check for rounding errors in custom integrations
Verify API calls include all required fields

Support & Resources

Documentation

📖 Badge Customization - Design guide
🚀 Project Onboarding - Complete setup and launch guide
🔧 API Reference - Complete endpoint documentation
💻 Code Examples - GitHub repo with templates

Direct Support

💬 Slack/Discord: Direct team access during onboarding
📧 Email: support@properlabs.io (24hr response)
📞 Emergency: Critical issues (99.9% uptime SLA)
📅 Office Hours: Weekly Q&A sessions

Community

🌐 Builder Community: Monthly calls with other AlphaHub projects
🎓 Workshops: Best practices, case studies, optimization tips
📊 Benchmarking: Compare your metrics vs similar projects

Next Steps

Ready to Build Your AlphaHub?

Start with these essential guides:

Design Your Badges →

Complete Onboarding Guide

Campaign Overview

Need Help? Join our Builder Community Discord or email support@properlabs.io

What is an AlphaHub?​

Architecture Overview​

Quick Start (5 Steps)​

Step 1: Access Your AlphaHub Dashboard​

Step 2: Configure Basic Settings​

Step 3: Select Your Pathways​

ALIGN (Required)​

ALPHA (Optional)​

KARMA (Optional)​

SYNERGY (Optional)​

Step 4: Design Your 32 Badges​

Step 5: Launch to Staging​

Dashboard Walkthrough​

Home Dashboard​

Pathway Manager​

Quest Builder​

Badge Studio​

BITS Calibration​

Analytics Dashboard​

API Integration​

Authentication​

Core Endpoints​

Award BITS​

Get User Card​

List Available Quests​

Track Quest Completion​

Webhooks​

Integration Patterns​

Option 1: Telegram Mini App (Easiest)​

Option 2: Embedded Widget (Balanced)​

Option 3: Full API Integration (Maximum Control)​

Testing & QA​

Staging Environment Checklist​

Beta Testing Program​

Launch Strategy​

Pre-Launch (1 Week Before)​

Launch Day​

Post-Launch (First Week)​

Optimization & Iteration​

A/B Testing​

Common Optimizations​

Support & Resources​

Documentation​

Direct Support​

Community​

Next Steps​

Ready to Build Your AlphaHub?

What is an AlphaHub?

Architecture Overview

Quick Start (5 Steps)

Step 1: Access Your AlphaHub Dashboard

Step 2: Configure Basic Settings

Step 3: Select Your Pathways

ALIGN (Required)

ALPHA (Optional)

KARMA (Optional)

SYNERGY (Optional)

Step 4: Design Your 32 Badges

Step 5: Launch to Staging

Dashboard Walkthrough

Home Dashboard

Pathway Manager

Quest Builder

Badge Studio

BITS Calibration

Analytics Dashboard

API Integration

Authentication

Core Endpoints

Award BITS

Get User Card

List Available Quests

Track Quest Completion

Webhooks

Integration Patterns

Option 1: Telegram Mini App (Easiest)

Option 2: Embedded Widget (Balanced)

Option 3: Full API Integration (Maximum Control)

Testing & QA

Staging Environment Checklist

Beta Testing Program

Launch Strategy

Pre-Launch (1 Week Before)

Launch Day

Post-Launch (First Week)

Optimization & Iteration

A/B Testing

Common Optimizations

Support & Resources

Documentation

Direct Support

Community

Next Steps