v1.0.0 · REST API

Helius PoL Engine API

The Helius Proof-of-Life Engine API lets you verify real-world human activity and issue rewards in any application. Submit GPS traces and sensor data, get fraud scores, PoL scores, and HLS token rewards back in milliseconds.

Base URL: https://your-site.netlify.app/api

Authentication

All requests require your API key in the Authorization header:

Authorization: Bearer hls_your_api_key_here

Quick Start

The fastest way to integrate — one call handles everything:

const result = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_id: 'user_123',
    start_time: '2026-03-14T08:00:00Z',
    end_time: '2026-03-14T08:45:00Z',
    distance_km: 4.2,
    activity_type: 'running',
    gps_trace: [
      { lat: 51.5000, lng: -0.1000, timestamp: '2026-03-14T08:00:00Z', accuracy: 8 },
      { lat: 51.5020, lng: -0.1010, timestamp: '2026-03-14T08:15:00Z', accuracy: 7 }
    ],
    sensor_data: [
      { timestamp: '2026-03-14T08:00:00Z', accelerometer: { x: 0.2, y: 9.8, z: 0.4 } }
    ],
    mission_type: 'environmental'
  })
});
// { status: 'verified', pol_score: 112, reward_amount: 4.2, fraud_risk: 'low' }

POST /reward/full-pipeline

Submit → Verify → Score → Reward in a single call. Recommended for most integrations.

POST/api/reward/full-pipeline

Request Body

Field	Type	Required	Description
user_id	string	REQUIRED	Your user's unique identifier
start_time	ISO 8601	REQUIRED	Session start timestamp
end_time	ISO 8601	REQUIRED	Session end timestamp
distance_km	float	OPTIONAL	Reported distance. Overridden by GPS trace if provided.
activity_type	string	OPTIONAL	walking · running · cycling · transit
gps_trace	array	OPTIONAL	Array of {lat, lng, timestamp, accuracy} objects
sensor_data	array	OPTIONAL	Accelerometer readings {timestamp, accelerometer: {x,y,z}}
mission_type	string	OPTIONAL	standard · community · environmental · weekly_challenge

Response

{
  "success": true,
  "user_id": "user_123",
  "status": "verified",
  "fraud_risk": "low",
  "confidence_score": 0.92,
  "pol_score": 112,
  "score_breakdown": {
    "distance_points": 59,
    "presence_points": 22,
    "impact_points": 25,
    "social_points": 6
  },
  "reward_amount": 4.2,
  "currency": "HLS",
  "daily_cap_info": { "remaining_today": 20.8, "daily_cap": 25 },
  "processed_at": "2026-03-14T08:46:00Z"
}

POST /activity/submit

Submit an activity session and receive a session_id for subsequent verification.

POST /api/activity/submit
{ "user_id": "u1", "start_time": "...", "end_time": "...", "gps_trace": [...] }
→ { "session_id": "uuid", "status": "pending" }

POST /activity/verify

Run 6-layer fraud detection on a submitted session.

POST /api/activity/verify
{ "session_id": "uuid" }
→ { "status": "verified", "confidence_score": 0.91, "fraud_risk": "low", "layers": {...} }

POST /score/calculate

POST /api/score/calculate
{ "user_id": "u1", "distance_km": 4.2, "duration_minutes": 45, "confidence_score": 0.91 }
→ { "pol_score": 112, "breakdown": { ... }, "multiplier": 1.14 }

POST /reward/calculate

POST /api/reward/calculate
{ "user_id": "u1", "pol_score": 112, "mission_type": "environmental" }
→ { "reward_amount": 4.2, "currency": "HLS", "daily_cap_info": { ... } }

Error Codes

Code	Meaning
400	Invalid request — check your payload structure
401	Unauthorized — missing or invalid API key
403	Suspicious activity detected — fraud score too high
404	Session not found
429	Rate limit exceeded — see your tier limits
500	Internal server error

Rate Limits

Tier	Requests/min	Verifications/month
Startup	100	10,000
Growth	500	100,000
Enterprise	2,000+	Unlimited

Fraud Detection Layers

Layer	Check	Action
1 — Speed	Any segment >25 km/h	Hard reject
2 — Teleport	>200km jump in <10 min	Hard reject
3 — Sensor Fusion	GPS movement, no accelerometer	Hard reject
4 — Route Entropy	Shannon entropy <0.2 (bot pattern)	Score reduction
5 — Time Consistency	Distance impossible for duration	Hard reject
6 — Device Integrity	Emulator/root/mock location	Confidence flag

PoL Score Formula

PoLScore = (DistancePoints + PresencePoints + ImpactPoints + SocialPoints)
           x confidence_score x reputation_multiplier

Reward = PoLScore x emission_rate x reputation_multiplier x mission_multiplier

Distance rates (per km):  walking=0.25  running=0.35  cycling=0.18  transit=0.01
Daily cap: 25 HLS/user — diminishing returns after 10km (30% rate)