A neutral SDK that fetches and assembles reputation data from Ethos Network, Talent Protocol, and Neynar (Farcaster) without interpretation, ranking, or judgment.
npm install basecred-sdkA neutral, composable SDK that fetches and assembles reputation data from Ethos Network, Talent Protocol, and Neynar (Farcaster).
This SDK exists to make reputation data observable without turning it into judgment.
v0.6.1
- Fetches Ethos social credibility signals (vouches, reviews, raw score)
- Fetches Talent Protocol builder and creator credibility (builder score, creator score)
- Supports versioned score slugs (e.g., builder_score_2025) and prefers the newest known variant
- Exposes raw rank_position per score when provided by Talent Protocol
- Fetches Neynar Farcaster account quality score (opt-in)
- Derives semantic levels from scores (enabled by default)
- Computes time semantics (days active, recency buckets)
- Returns a unified, neutral profile
- Explicitly declares absence and failure states
- No rankings
- No percentiles
- No trust verdicts
- No aggregation or interpretation
- No gamification logic
``bash`
npm install basecred-sdk
> Requires Node.js 18+ (uses native fetch).
This SDK is intended for applications that need neutral access to reputation signals without embedded judgment or ranking logic.
`ts
import { getUnifiedProfile } from 'basecred-sdk';
const profile = await getUnifiedProfile(
'0xabc...',
{
ethos: {
baseUrl: 'https://api.ethos.network',
clientId: 'your-app@0.1.0',
},
talent: {
baseUrl: 'https://api.talentprotocol.com',
apiKey: process.env.TALENT_API_KEY!,
},
// Optional: Enable Farcaster quality scoring
farcaster: {
enabled: true,
neynarApiKey: process.env.NEYNAR_API_KEY!,
qualityThreshold: 0.5, // Optional, default: 0.5
},
}
);
// Level derivation is enabled by default.
// To disable level derivation:
const profileWithoutLevels = await getUnifiedProfile(
'0xabc...',
{
ethos: { / ... / },
talent: { / ... / },
levels: { enabled: false },
}
);
`
Note:
- Ethos Network does not require an API key
- Talent Protocol requires an API key (request one at talentprotocol.com)
- Farcaster (Neynar) requires an API key (get one at neynar.com)
`json`
{
"identity": {
"address": "0xabc..."
},
"availability": {
"ethos": "available",
"talent": "available",
"farcaster": "available"
},
"ethos": {
"data": {
"score": 1732,
"credibilityLevel": {
"value": 1732,
"level": "Established",
"levelSource": "sdk",
"levelPolicy": "ethos@v1"
},
"vouchesReceived": 5,
"reviews": {
"positive": 12,
"neutral": 1,
"negative": 0
}
},
"signals": {
"hasNegativeReviews": false,
"hasVouches": true
},
"meta": {
"firstSeenAt": "2024-03-15T10:00:00Z",
"lastUpdatedAt": "2026-01-20T14:30:00Z",
"activeSinceDays": 679,
"lastUpdatedDaysAgo": 3
}
},
"talent": {
"data": {
"builderScore": 196,
"builderRankPosition": 641,
"builderLevel": {
"value": 196,
"level": "Expert",
"levelSource": "sdk",
"levelPolicy": "builder@v1"
},
"creatorScore": 97,
"creatorRankPosition": null,
"creatorLevel": {
"value": 97,
"level": "Established",
"levelSource": "sdk",
"levelPolicy": "creator@v1"
}
},
"signals": {
"verifiedBuilder": true,
"verifiedCreator": true
},
"meta": {
"lastUpdatedAt": "2026-01-22T15:22:46Z",
"lastUpdatedDaysAgo": 1
}
},
"farcaster": {
"data": {
"userScore": 0.97
},
"signals": {
"passesQualityThreshold": true
},
"meta": {
"source": "neynar",
"scope": "farcaster",
"lastUpdatedAt": "2026-01-25T08:00:00Z",
"lastUpdatedDaysAgo": 0,
"updateCadence": "weekly",
"timeMeaning": "system_update"
}
},
"recency": {
"bucket": "recent",
"windowDays": 30,
"lastUpdatedDaysAgo": 0,
"derivedFrom": ["talent", "farcaster"],
"computedAt": "2026-01-25T12:00:00Z",
"policy": "recency@v1"
}
}
The SDK derives semantic levels from raw scores using documented upstream protocol thresholds.
Ethos Credibility Levels (ethos@v1):
| Score | Level |
|-------|-------|
| 0-799 | Untrusted |
| 800-1199 | Questionable |
| 1200-1399 | Neutral |
| 1400-1599 | Known |
| 1600-1799 | Established |
| 1800-1999 | Reputable |
| 2000-2199 | Exemplary |
| 2200-2399 | Distinguished |
| 2400-2599 | Revered |
| 2600-2800 | Renowned |
Talent Builder Levels (builder@v1):
| Score | Level |
|-------|-------|
| 0-39 | Novice |
| 40-79 | Apprentice |
| 80-119 | Practitioner |
| 120-169 | Advanced |
| 170-249 | Expert |
| 250+ | Master |
Talent Creator Levels (creator@v1):
| Score | Level |
|-------|-------|
| 0-39 | Emerging |
| 40-79 | Growing |
| 80-119 | Established |
| 120-169 | Accomplished |
| 170-249 | Prominent |
| 250+ | Elite |
Level derivation is:
- Enabled by default — set levels: { enabled: false } to disableethos@v1
- Deterministic — same score always maps to same level
- Versioned — policy identifier included in output (e.g., )
The SDK computes time-based fields from timestamps:
| Field | Source | Description |
|-------|--------|-------------|
| ethos.meta.activeSinceDays | firstSeenAt | Days since profile creation |ethos.meta.lastUpdatedDaysAgo
| | lastUpdatedAt | Days since last profile update |talent.meta.lastUpdatedDaysAgo
| | lastUpdatedAt | Days since score recalculation |
The SDK uses the Talent Protocol GET /scores endpoint and maps fields directly:
| Talent Field | SDK Field | Notes |
|-------------|-----------|-------|
| slug | talent.data.builderScore / talent.data.creatorScore | Only known slugs are mapped |points
| | Score values | Raw score values |rank_position
| | builderRankPosition / creatorRankPosition | Nullable, exposed as-is |last_calculated_at
| | talent.meta.lastUpdatedAt | Most recent timestamp across known scores |
Profile-level data freshness indicator (recency@v1):
| Bucket | Condition |
|--------|-----------|
| recent | Updated within 30 days |stale
| | Updated 31-90 days ago |dormant
| | Updated more than 90 days ago |
Recency is:
- Derived from the most recently updated facet
- Omitted if no facet has lastUpdatedAt
- Computed at query time (UTC)
Each source declares exactly one state:
| State | Meaning |
|-------|---------|
| available | Profile exists, data fetched |not_found
| | No profile exists |unlinked
| | Identity exists but not linked |error
| | API error or failure |
Partial responses are valid. Both facets are optional based on availability.
- Absence is explicit — Missing data is declared, never hidden
- Time matters more than score — Temporal fields enable continuity analysis
- Sources are parallel — Ethos and Talent are peers, not ranked
- Data is reported, not judged — Consumers interpret meaning
This SDK intentionally does NOT:
- Decide trustworthiness
- Rank users
- Compare users
- Produce composite scores
- Replace human judgment
This SDK never throws on valid input.
All failures are surfaced explicitly via the availability field for each source. Consumers should check availability.ethos and availability.talent to determine data presence.
v0.6.1 — Talent Scores Update
- Support versioned score slugs (e.g., builder_score_2025, creator_score_2025)rank_position
- Expose Talent as builderRankPosition / creatorRankPosition
- uses the most recent last_calculated_at
v0.6.0 — Farcaster Account Quality
Optional Neynar score integration for Farcaster platform account quality.
v0.5.2 — Bug Fix
Talent API 404 now correctly maps to 'not_found' instead of 'error'.
v0.5.1 — Documentation
Pre-publish checklist, cleaned up comments, updated docs.
v0.5.0 — Time Semantics
The SDK now computes time-based fields (days active, recency buckets) from upstream timestamps.
v0.4.0 — Ethos Timestamps
Ethos profile creation and update times now exposed via firstSeenAt and lastUpdatedAt.
v0.3.0 — Creator Score
Talent facet expanded with creatorScore and creatorLevel` as parallel axes to builder credibility.
MIT