Skip to main content

Getting Started: Build Your First CrowdProof Integration in 5 Minutes

· 3 min read
CrowdProof Team
CrowdProof Team
Protocol Engineering

You can add on-chain reputation checks to your application in under 5 minutes. This tutorial walks through the fastest path from zero to a working integration — querying scores, verifying proofs, and receiving real-time updates.

Step 1: Get an API Key​

Create a free API key (100 queries/month, 10 req/s):

curl -X POST https://crowdproof-api.azurewebsites.net/api/v1/billing/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "organizationName": "My DeFi App",
    "contactEmail": "dev@example.com",
    "tier": "Free"
  }'

Save the returned key — you'll pass it as X-API-Key in subsequent requests.

Step 2: Query a Reputation Score​

curl https://crowdproof-api.azurewebsites.net/api/v1/reputation/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
  -H "X-API-Key: YOUR_KEY"

This returns scores across all 6 categories for Vitalik's address:

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "scores": [
    { "category": "GOVERNANCE", "score": 920, "tier": "Excellent", "confidence": 0.95 },
    { "category": "DEFI_LENDING", "score": 680, "tier": "Good", "confidence": 0.72 },
    ...
  ]
}

Step 3: Use an SDK​

Raw HTTP works, but SDKs are nicer. Pick your language:

TypeScript​

npm install @crowdproof/sdk
import { CrowdProof } from '@crowdproof/sdk';

const client = new CrowdProof({ apiKey: 'YOUR_KEY' });

// Single score
const score = await client.getScore('0x1234...', 'DEFI_LENDING');
console.log(`${score.tier}: ${score.score}/1000 (${Math.round(score.confidence * 100)}% confident)`);

// Batch query — check 50 addresses at once
const batch = await client.batchQuery(
  addresses, // up to 100
  'DEFI_LENDING'
);

Python​

pip install crowdproof
from crowdproof import CrowdProofClient

client = CrowdProofClient(api_key="YOUR_KEY")

score = client.get_score("0x1234...", "DEFI_LENDING")
print(f"{score.tier}: {score.score}/1000")

Step 4: Generate a ZK Proof​

Prove a score exceeds a threshold without revealing the exact number:

// Prove lending score ≥ 700
const proof = await client.generateProof({
  subject: '0x1234...',
  proofType: 'ScoreAboveThreshold',
  category: 'DEFI_LENDING',
  threshold: 700,
});

// Verify the proof (anyone can do this)
const { valid } = await client.verifyProof(proof.proof);
// valid === true if score is genuinely ≥ 700

The proof is a 192-byte Groth16 SNARK that can also be verified on-chain via the ReputationOracle contract — no API call needed.

Step 5: Real-Time Updates (WebSocket)​

Subscribe to live score changes for specific addresses:

import { HubConnectionBuilder } from '@microsoft/signalr';

const connection = new HubConnectionBuilder()
  .withUrl('https://crowdproof-api.azurewebsites.net/hubs/scores')
  .withAutomaticReconnect()
  .build();

connection.on('ScoreUpdated', (data) => {
  console.log(`${data.address}: ${data.category} ${data.oldScore} → ${data.newScore}`);
});

await connection.start();
await connection.invoke('SubscribeToAddress', '0x1234...');

Or use webhooks for server-to-server notifications:

const webhook = await client.createWebhook({
  url: 'https://your-app.com/webhook/crowdproof',
  walletAddress: '0x1234...', // optional filter
});
// Save webhook.secret for HMAC verification

Common Integration Patterns​

Under-Collateralized Lending​

const score = await client.getScore(borrower, 'DEFI_LENDING');

let collateralRatio;
if (score.score >= 800 && score.confidence >= 0.8) {
  collateralRatio = 1.1; // 110% — excellent history
} else if (score.score >= 650) {
  collateralRatio = 1.3; // 130% — good history
} else {
  collateralRatio = 1.5; // 150% — standard
}

DAO Governance Weighting​

const score = await client.getScore(voter, 'GOVERNANCE');
const voteWeight = baseWeight * (1 + score.score / 1000);
// Active governors get up to 2x vote weight

Access Gating with ZK Proofs​

function claimReward(bytes calldata proof) external {
    require(
        reputationOracle.verifyProof(proof, 500, ScoreCategory.SOCIAL),
        "Social reputation too low"
    );
    // Grant reward without knowing the exact score
}

Next Steps​

Happy building!