Integration Guide

All endpoints require an API key as a Bearer Authorization header. API keys must only be used in backend server code.

Integration Steps

Create a Verification Session

Your backend calls the Predicate API to create a KYC or KYB session

Display the QR Code and Link

Show the QR code or redirect URL to the user in your application

Monitor Session Status

Use SSE (recommended) or polling to track verification progress

Verify Wallet Addresses

Check if a wallet belongs to a verified identity before transactions

Step 1: Create a Verification Session

Your backend creates a session by calling the registration endpoint. The response includes a QR code and redirect URL for the user.

Individual (KYC)
Business (KYB)

cURL

curl -X POST "https://api.identity.predicate.io/api/v1/register/individual?size=300" \
  -H "Authorization: Bearer $PREDICATE_KYC_API_KEY"

cURL

curl -X POST "https://api.identity.predicate.io/api/v1/register/business?size=300" \
  -H "Authorization: Bearer $PREDICATE_KYC_API_KEY"

Request Body (Optional):

{
  "walletAddress": "0x1234567890abcdef...",
  "originUrl": "https://yourapp.example.com/verified"
}

Wallet Constraint: When you include walletAddress in the request:

The user can only connect and verify with that specific wallet address
If a session (pending, retry, or completed) already exists for that wallet with the same verification type, the existing session is returned (session reuse)
Sessions are only reused within the same check type (KYC sessions for /register/individual, KYB for /register/business)
Useful for pre-registering known wallet addresses or enforcing wallet constraints

Origin URL: Pass an optional originUrl (an absolute https:// URL) to give the user a button back to your application when they finish the verification flow (and while a manual review is pending, with a note that they are not yet authorized). It is named originUrl so it is not confused with the response redirectUrl, which is the hosted verification link you send the user to.

HTTP Status Codes:

201 Created - A new session was created
200 OK - An existing session was reused (when walletAddress matched an existing reusable session)

Response:

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "redirectUrl": "https://identity.predicate.io/session/550e8400-e29b-41d4-a716-446655440000",
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSU..."
}

Backend Implementation (Node.js)

const express = require('express');
const router = express.Router();

const KYC_API_KEY = process.env.KYC_API_KEY;

router.post('/kyc/create-session', async (req, res) => {
  const { type, walletAddress } = req.body; // 'individual' or 'business', optional wallet

  const endpoint = type === 'business' ? 'business' : 'individual';
  const url = `https://api.identity.predicate.io/api/v1/register/${endpoint}`;

  // Build request options
  const options = {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${KYC_API_KEY}`
    }
  };

  // Include wallet address if provided (restricts session to this wallet)
  if (walletAddress) {
    options.headers['Content-Type'] = 'application/json';
    options.body = JSON.stringify({ walletAddress });
  }

  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || `API error: ${response.status}`);
    }

    const data = await response.json();
    res.json(data);
  } catch (error) {
    console.error('Session creation error:', error);
    res.status(500).json({ error: 'Failed to create verification session' });
  }
});

module.exports = router;

Step 2: Display the QR Code and Link

Display the base64-encoded QR code from the response directly in an <img> tag.

<div class="kyc-section">
  <h2>Complete Your Verification</h2>
  <p>Scan the QR code or click the link below to start:</p>

  <!-- QR Code (from API response) -->
  <img id="kyc-qr" alt="Verify Identity" style="width: 300px; height: 300px;" />

  <!-- Direct link -->
  <p><a id="kyc-link" target="_blank">Verify Your Identity</a></p>
</div>

<script>
async function initiateKYC(type) {
  const response = await fetch('/kyc/create-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ type: type || 'individual' })
  });

  const data = await response.json();

  // Display QR code (already base64-encoded with data URI prefix)
  document.getElementById('kyc-qr').src = data.qrCode;
  document.getElementById('kyc-link').href = data.redirectUrl;

  // Start monitoring for completion
  startMonitoring(data.sessionId, type || 'individual');
}
</script>

What happens on the verification portal:

User lands on the verification page
User connects their wallet(s) - up to 20 per session, across different chains
User completes identity verification
Session status updates are sent via SSE
When finished (or while a manual review is pending), the user can return to your application using the originUrl you provided (if any)

Step 3: Monitor Session Status

Once a user starts verification, monitor their progress using SSE (recommended) or polling. Session Status Values:

Status	Description
`pending`	Session created, user in verification process
`submitted`	Documents submitted, awaiting manual operator review
`completed`	Verification successful, user is verified
`rejected`	Verification permanently failed (fraud, sanctions)
`retry`	Fixable issue (e.g., blurry document), user can retry

Important: A submitted status means documents are under manual review. The wallet is not verified until status becomes completed.

SSE (Recommended)
Polling

Server-Sent Events provide instant notifications when verification status changes.

The SSE endpoint requires your API key. Since browsers’ EventSource API doesn’t support custom headers, you must create a backend proxy.

Proxy Timeout: Ensure your backend proxy does not impose a response time limit on the SSE connection. Some frameworks (e.g., Next.js API routes) have default timeouts that will prematurely close the stream. Use a standalone server or configure your framework to allow long-lived connections.

Backend SSE Proxy (Node.js)

router.get('/kyc/stream/:type/:sessionId', async (req, res) => {
  const { type, sessionId } = req.params;

  if (type !== 'individual' && type !== 'business') {
    return res.status(400).json({ error: 'Type must be individual or business' });
  }

  // Validate UUID format
  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
  if (!uuidRegex.test(sessionId)) {
    return res.status(400).json({ error: 'Invalid session ID format' });
  }

  // Set SSE headers
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  res.setHeader('X-Accel-Buffering', 'no');

  const kycUrl = `https://api.identity.predicate.io/api/v1/status/realtime/${type}/${sessionId}`;

  try {
    const response = await fetch(kycUrl, {
      headers: { 'Authorization': `Bearer ${KYC_API_KEY}` }
    });

    if (!response.ok) {
      throw new Error(`KYC API error: ${response.status}`);
    }

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    req.on('close', () => reader.cancel());

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      res.write(decoder.decode(value, { stream: true }));
    }
  } catch (error) {
    console.error('SSE streaming error:', error);
    res.write(`event: error\ndata: ${JSON.stringify({ error: 'Stream failed' })}\n\n`);
  }
});

Frontend SSE Client

class VerificationMonitor {
  constructor(sessionId, type) {
    this.sessionId = sessionId;
    this.type = type;
    this.eventSource = null;
  }

  start(onStatusUpdate, onError) {
    // Connect to YOUR backend, not directly to KYC API
    const url = `/kyc/stream/${this.type}/${this.sessionId}`;
    this.eventSource = new EventSource(url);

    this.eventSource.onmessage = (event) => {
      const status = JSON.parse(event.data);
      onStatusUpdate(status);

      if (status.status === 'completed' || status.status === 'rejected') {
        this.stop();
      }
    };

    this.eventSource.onerror = () => {
      onError('Connection lost');
      this.stop();
    };
  }

  stop() {
    if (this.eventSource) {
      this.eventSource.close();
      this.eventSource = null;
    }
  }
}

function startMonitoring(sessionId, type) {
  const monitor = new VerificationMonitor(sessionId, type);
  monitor.start(
    (status) => updateVerificationUI(status),
    (error) => console.error('Monitoring error:', error)
  );
  return monitor;
}

SSE Event Format:

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "userId": "user-uuid-here",
  "completedAt": "2025-01-21T10:30:00Z",
  "verifiedWallets": [
    { "id": "wallet-uuid-1", "address": "0x1234...", "chain": "ethereum" },
    { "id": "wallet-uuid-2", "address": "0x5678...", "chain": "polygon" }
  ],
  "unverifiedWallets": []
}

Wallet Arrays:

Field	Description
`verifiedWallets`	Wallets connected to this session. Only populated when session status is `completed`.
`unverifiedWallets`	Wallets connected to this session. Populated when session is not yet `completed`.

If SSE isn’t suitable for your infrastructure, poll the status endpoint at regular intervals.

Backend Polling Endpoint (Node.js)

router.get('/kyc/status/:type/:sessionId', async (req, res) => {
  const { type, sessionId } = req.params;

  if (type !== 'individual' && type !== 'business') {
    return res.status(400).json({ error: 'Type must be individual or business' });
  }

  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
  if (!uuidRegex.test(sessionId)) {
    return res.status(400).json({ error: 'Invalid session ID format' });
  }

  const kycUrl = `https://api.identity.predicate.io/api/v1/status/${type}/${sessionId}`;

  try {
    const response = await fetch(kycUrl, {
      headers: { 'Authorization': `Bearer ${KYC_API_KEY}` }
    });

    if (!response.ok) {
      throw new Error(`KYC API error: ${response.status}`);
    }

    const data = await response.json();
    res.json(data);
  } catch (error) {
    console.error('Status check error:', error);
    res.status(500).json({ error: 'Failed to check verification status' });
  }
});

Frontend Polling Client

class VerificationPoller {
  constructor(sessionId, type, interval = 3000) {
    this.sessionId = sessionId;
    this.type = type;
    this.interval = interval;
    this.isPolling = false;
  }

  start(onStatusUpdate, onError) {
    this.onStatusUpdate = onStatusUpdate;
    this.onError = onError;
    this.isPolling = true;
    this.poll();
  }

  async poll() {
    if (!this.isPolling) return;

    try {
      const response = await fetch(`/kyc/status/${this.type}/${this.sessionId}`);
      const status = await response.json();
      this.onStatusUpdate(status);

      if (status.status === 'completed' || status.status === 'rejected') {
        this.stop();
        return;
      }

      this.pollTimer = setTimeout(() => this.poll(), this.interval);
    } catch (error) {
      this.onError(error);
      this.pollTimer = setTimeout(() => this.poll(), this.interval);
    }
  }

  stop() {
    this.isPolling = false;
    if (this.pollTimer) clearTimeout(this.pollTimer);
  }
}

Verifying Wallet Addresses

Once a user has completed verification, check if any wallet address belongs to a verified identity.

cURL

curl -X POST "https://api.identity.predicate.io/api/v1/verify" \
  -H "Authorization: Bearer $PREDICATE_KYC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x1234567890abcdef...",
    "type": "individual"
  }'

Response (verified):

{
  "address": "0x1234...",
  "verified": true,
  "status": "completed",
  "userId": "uuid-of-verified-identity",
  "checkType": "kyc",
  "verifiedAt": "2025-01-21T10:30:00Z",
  "wallets": [
    { "address": "0x1234...", "chain": "ethereum" },
    { "address": "0x5678...", "chain": "polygon" }
  ]
}

Response (not verified):

{
  "address": "0x1234...",
  "verified": false
}

Verification Levels: The verify endpoint returns verified status for wallets that were verified at your organization’s current verification level. If you upgrade your verification level, previously verified wallets will need to re-verify. Wallets verified through other organizations at the same scrutiny level will also appear as verified.

Best Practices

Security

Never expose API keys in frontend code - All authenticated operations must happen on your backend
Use environment variables - Store API keys in .env files or secure secret management systems
Validate session IDs - Always validate UUID format before making API calls
Verify session ownership - The API ensures sessions can only be accessed by the customer that created them

User Experience

Show clear progress indicators - Update the UI as session status changes
Handle all statuses - Display appropriate messages for pending, submitted, completed, rejected, and retry
Explain submitted status to users - When status is submitted, inform users that their documents are under review and they’ll be notified when a decision is made. submitted does NOT mean approved.
Provide both QR and link - Some users prefer clicking, others prefer scanning
Consider timeouts - Sessions don’t expire, but you may want to implement client-side timeouts

Performance

Use SSE over polling - Real-time updates are more efficient and user-friendly
Implement reconnection logic - Handle network interruptions gracefully
Close connections when done - Stop monitoring once verification completes or fails

Complete Integration Example

Here’s a full example tying everything together:

<!DOCTYPE html>
<html>
<head>
  <title>Identity Verification</title>
  <style>
    .kyc-container {
      max-width: 400px;
      margin: 50px auto;
      text-align: center;
      font-family: sans-serif;
    }
    .kyc-qr {
      width: 300px;
      height: 300px;
      border: 1px solid #ddd;
      margin: 20px auto;
    }
    .status-pending { color: #f59e0b; }
    .status-verified { color: #10b981; }
    .status-failed { color: #ef4444; }
  </style>
</head>
<body>
  <div class="kyc-container">
    <h1>Verify Your Identity</h1>

    <div id="start-section">
      <button id="start-btn" onclick="startVerification()">
        Start Verification
      </button>
    </div>

    <div id="verification-section" style="display: none;">
      <p>Scan the QR code or click the link below:</p>
      <img id="kyc-qr" class="kyc-qr" alt="QR Code" />
      <p><a id="kyc-link" target="_blank">Open Verification Portal →</a></p>
      <p id="verification-status" class="status-pending">Waiting...</p>
    </div>
  </div>

  <script>
    async function startVerification() {
      try {
        const response = await fetch('/kyc/create-session', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ type: 'individual' })
        });

        if (!response.ok) throw new Error('Failed to create session');

        const data = await response.json();

        document.getElementById('start-section').style.display = 'none';
        document.getElementById('verification-section').style.display = 'block';
        document.getElementById('kyc-qr').src = data.qrCode;
        document.getElementById('kyc-link').href = data.redirectUrl;

        const monitor = new VerificationMonitor(data.sessionId, 'individual');
        monitor.start(
          (status) => {
            const statusEl = document.getElementById('verification-status');
            switch (status.status) {
              case 'completed':
                statusEl.textContent = '✓ Verified!';
                statusEl.className = 'status-verified';
                break;
              case 'pending':
                statusEl.textContent = 'Verification in progress...';
                statusEl.className = 'status-pending';
                break;
              case 'submitted':
                statusEl.textContent = 'Under review...';
                statusEl.className = 'status-pending';
                break;
              case 'retry':
                statusEl.textContent = 'Please resubmit documents';
                statusEl.className = 'status-pending';
                break;
              case 'rejected':
                statusEl.textContent = '✗ Verification rejected';
                statusEl.className = 'status-failed';
                break;
            }
          },
          (error) => console.error('Monitor error:', error)
        );
      } catch (error) {
        console.error('Error:', error);
        alert('Failed to start verification');
      }
    }

    class VerificationMonitor {
      constructor(sessionId, type) {
        this.sessionId = sessionId;
        this.type = type;
        this.eventSource = null;
      }

      start(onStatusUpdate, onError) {
        const url = `/kyc/stream/${this.type}/${this.sessionId}`;
        this.eventSource = new EventSource(url);

        this.eventSource.onmessage = (event) => {
          try {
            const status = JSON.parse(event.data);
            onStatusUpdate(status);
            if (status.status === 'completed' || status.status === 'rejected') {
              this.stop();
            }
          } catch (e) {
            console.error('Parse error:', e);
          }
        };

        this.eventSource.onerror = () => {
          onError('Connection lost');
          this.stop();
        };
      }

      stop() {
        if (this.eventSource) {
          this.eventSource.close();
          this.eventSource = null;
        }
      }
    }
  </script>
</body>
</html>

API Reference

Method	Endpoint	Purpose	Auth
`POST`	`/api/v1/register/individual[?size=N]`	Create individual KYC session	API Key
`POST`	`/api/v1/register/business[?size=N]`	Create business KYB session	API Key
`POST`	`/api/v1/verify`	Check if wallet is verified	API Key
`GET`	`/api/v1/status/{type}/{sessionId}`	Get session status (one-shot)	API Key
`GET`	`/api/v1/status/realtime/{type}/{sessionId}`	Stream session updates (SSE)	API Key

Query Parameters for Registration Endpoints:

size (optional): QR code size in pixels, between 80 and 2000. Default: 300.

All API endpoints require a Bearer token:

Authorization: Bearer YOUR_API_KEY

Essentials

Compliance For

Identity Solution

Integration Steps

Step 1: Create a Verification Session

Step 2: Display the QR Code and Link

Step 3: Monitor Session Status

Verifying Wallet Addresses

Best Practices

Security

User Experience

Performance

Complete Integration Example

API Reference

​Integration Steps

​Step 1: Create a Verification Session

​Step 2: Display the QR Code and Link

​Step 3: Monitor Session Status

​Verifying Wallet Addresses

​Best Practices

​Security

​User Experience

​Performance

​Complete Integration Example

​API Reference

Integration Steps

Step 1: Create a Verification Session

Step 2: Display the QR Code and Link

Step 3: Monitor Session Status

Verifying Wallet Addresses

Best Practices

Security

User Experience

Performance

Complete Integration Example

API Reference