SOCI4L Developer API: Avalanche Reputation Scores

Endpoints

GET

Live score

/api/v1/score/:address

Full reputation read for any C-Chain address: the 0–100 composite headline + tier, the S4 vector (humanity / activity / social / economic + confidence), graph-anomaly flags, Verified Human number, and the legacy v1 breakdown.

POST

Batch scoring

/api/v1/score/batch

Up to 50 addresses per call: airdrop filtering, allowlist checks, sybil screening. Each address counts as one rate-limit unit.

GET

Score history

/api/v1/score/:address/history

Daily snapshots for trend analysis, up to 90 days. Add include=breakdown for per-signal time series.

GET

Signed attestation

/api/v1/score/:address/signed

The score as an EIP-712 signed attestation. Verify it offline with viem/ethers, or in the browser at soci4l.net/verify. Proves the score came from SOCI4L untampered.

Full reference (auth, schema, errors, examples) in the API docs. Machine-readable surface at GET /api/v1, no auth required.

Request

curl https://soci4l.net/api/v1/score/0x8ab0...1dc7 \
  -H "X-Api-Key: s4_live_..."

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

Response

{
  "address": "0x8ab0...1dc7",
  "headline": {
    "score": 60, "tier": "elite",
    "tierLabel": "Elite", "model": "s4-composite"
  },
  "s4": {
    "humanity": 72.1, "activity": 55.3,
    "social": 38.0, "economic": 61.4,
    "composite": 60.2, "confidence": 0.75
  },
  "graph": { "analyzed": true, "flags": [], "socialDamping": 1 },
  "verifiedHuman": 2,
  "score": 43.4, "tier": "established",   // legacy v1, kept for back-compat
  "breakdown": { "walletAge": 15, "txActivity": 10, ... }
}

TypeScript SDK

Typed client, zero dependencies, ESM + CommonJS.

Install

npm install soci4l-sdk

Wraps every endpoint with typed responses matching the schema above, plus a verify(address, thresholds) helper that gates on any S4 dimension.

npm GitHub

Verify in <10 lines

import { Soci4lClient } from 'soci4l-sdk'

const client = new Soci4lClient({
  apiKey: process.env.SOCI4L_API_KEY!,
})

// Gate an address on humanity in one call:
const { passed, s4 } = await client.verify(
  address, { humanity: 50 },
)
if (!passed) throw new Error('Not human enough')

Rate Limits

Free1,000 requests / day

Pro10,000 requests / day

Batch calls consume one unit per address. Limits reset on a rolling 24-hour window.

Get an API key

Self-serve: connect your wallet, open the Developer tab in your dashboard, and create a key in one click. Free tier, no card.

Create a key

Embeddable score badge

A live SVG badge for any address; drop it in a README, docs, or site. No API key required.

Updates automatically as the score changes.

Markdown

[![SOCI4L Score](https://soci4l.net/api/tools/score-badge/ADDRESS)](https://soci4l.net/tools/score/ADDRESS)

HTML

<a href="https://soci4l.net/tools/score/ADDRESS"><img src="https://soci4l.net/api/tools/score-badge/ADDRESS" alt="SOCI4L Score" /></a>

Replace ADDRESS with any Avalanche C-Chain address.

API Reference Scoring Methodology Score Leaderboard Score Checker Product Docs

Reputation as an API