INTEGRATION GUIDE

Build with Helius PoL

From zero to a live Proof-of-Life integration in under 30 minutes. This guide walks through React Native (Expo) and Node.js integrations.

1. Install the SDK

# npm
npm install helius-pol-sdk

# or copy sdk directly
curl -O https://heliusnetwork.com/sdk/helius-pol-sdk.js

2. Initialise the Client

const HeliusPoL = require('helius-pol-sdk');

const pol = new HeliusPoL({
  apiKey:  'hls_your_api_key',
  baseUrl: 'https://your-site.netlify.app'
});

3. Collect GPS (React Native)

import * as Location from 'expo-location';

const gpsTrace = [];

// Request permission
const { status } = await Location.requestForegroundPermissionsAsync();
if (status !== 'granted') return;

// Start tracking
const sub = await Location.watchPositionAsync(
  {
    accuracy: Location.Accuracy.BestForNavigation,
    timeInterval: 10000,   // every 10 seconds
    distanceInterval: 10   // or every 10 metres
  },
  (loc) => {
    gpsTrace.push({
      lat:       loc.coords.latitude,
      lng:       loc.coords.longitude,
      accuracy:  loc.coords.accuracy,
      timestamp: new Date(loc.timestamp).toISOString()
    });
  }
);

// Stop when session ends
sub.remove();

4. Collect Sensor Data

import { Accelerometer } from 'expo-sensors';

const sensorData = [];

Accelerometer.setUpdateInterval(5000); // every 5s
const accelSub = Accelerometer.addListener(({ x, y, z }) => {
  sensorData.push({
    timestamp:    new Date().toISOString(),
    accelerometer: { x, y, z }
  });
});

// Stop when session ends
accelSub.remove();

5. Submit the Session

const endSession = async (startTime) => {
  const result = await pol.fullPipeline({
    user_id:       currentUser.id,
    start_time:    startTime,
    end_time:      new Date().toISOString(),
    distance_km:   calculatedDistance,
    activity_type: 'running',
    gps_trace:     gpsTrace,
    sensor_data:   sensorData,
    device_meta: {
      isEmulator:     false,
      isMockLocation: false,
      isRooted:       false
    },
    mission_type: 'standard'
  });

  return result;
};

Full Pipeline Response

const result = await pol.fullPipeline(session);

if (result.status === 'verified') {
  console.log('PoL Score:',   result.pol_score);     // 112
  console.log('Reward:',      result.reward_amount); // 4.2 HLS
  console.log('Confidence:',  result.confidence_score); // 0.91
  console.log('Fraud Risk:',  result.fraud_risk);    // 'low'
  await creditUserWallet(result.reward_amount);
} else {
  // result.status === 'rejected'
  console.log('Rejected:', result.fraud_risk); // 'high'
  // Do not reward - activity failed fraud check
}

Error Handling

try {
  const result = await pol.fullPipeline(session);
} catch (err) {
  if (err.status === 403) {
    // Fraud detected - do not reward
    showAlert('Activity could not be verified');
  } else if (err.status === 429) {
    // Rate limited - retry after delay
    setTimeout(retry, 60000);
  } else if (err.status === 401) {
    // Bad API key
    console.error('Check your ANTHROPIC_KEY in Netlify env vars');
  }
}

Webhooks (Pro+)

POST /api/webhooks/register
{
  "url": "https://yourapp.com/webhook",
  "events": ["session.verified", "session.rejected", "reward.granted"]
}

// Payload example:
{
  "event":         "reward.granted",
  "session_id":    "uuid",
  "user_id":       "user_123",
  "reward_amount": 3.2,
  "currency":      "HLS",
  "timestamp":     "2026-03-14T09:00:00Z"
}