SOCI4L Developer API: Avalanche Reputation Scores

Endpoints

GET

Live score

/api/v1/score/:address

Full reputation read for any C-Chain address: the 0 to 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 github:SOCI4LNET/SOCI4L-SDK

Wraps every endpoint with typed responses matching the schema above, plus a verify(address, thresholds) helper that gates on any S4 dimension, batch screening that chunks a list of any size, and EIP-712 helpers for signed scores.

Install from the repository for now: the npm release is still pending.

GitHub SDK reference

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')

Plans

Plan	Requests / 30 days	Includes	Price
Free	2,500	Single-address scoring	Free
Builder	25,000	+ batch screening, + 90-day history	49.00 USDC
Growth	250,000	+ EIP-712 signed attestations	249.00 USDC
Scale	1,500,000	Everything, at volume	999.00 USDC

Paid in USDC on Avalanche C-Chain, per 30 days, no auto-renewal. Batch calls consume one unit per address; a 50-address call costs 50. Calling an endpoint outside your plan returns 402 with PLAN_REQUIRED.

Create a key or upgrade a plan

System status

Get an API key

Self-serve: connect your wallet, open the Developer tab in your dashboard, and create a key in one click. Free plan to start, USDC to upgrade.

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