Identity Build Guide

0

Prerequisites

You need a SocialOS API key to use these endpoints. If you don't have one yet, follow the Agent Quick Start to get your free sandbox key in under 2 minutes.

Base URL: https://sandbox.socialos.io/v2

1

Verify Credentials

Verify on-chain credentials for a user identity. Pass the user ID, credential type, and the specific credential to check. The API returns a confidence score indicating match strength.

POST /identity/verify

curl

curl -X POST https://sandbox.socialos.io/v2/identity/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "alice.kred",
    "type": "onchain",
    "credential": "eth_wallet"
  }'

Response 200 OK

{
  "verified": true,
  "userId": "alice.kred",
  "type": "onchain",
  "credential": "eth_wallet",
  "confidence": 0.97,
  "verified_at": "2026-02-20T10:30:00Z"
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/identity/verify",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "userId": "alice.kred",
        "type": "onchain",
        "credential": "eth_wallet"
    }
)
result = resp.json()
print(result)

2

Score Reputation

Update a user's reputation score after a verified action. The gamification engine tracks running totals, computes rank, and returns the updated score in real time.

POST /gamification/score

curl

curl -X POST https://sandbox.socialos.io/v2/gamification/score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "alice.kred",
    "metric": "trust",
    "action": "credential_verified",
    "value": 15
  }'

Response 200 OK

{
  "userId": "alice.kred",
  "metric": "trust",
  "previous": 82,
  "current": 97,
  "rank": 12,
  "updated_at": "2026-02-20T10:31:00Z"
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/gamification/score",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "userId": "alice.kred",
        "metric": "trust",
        "action": "credential_verified",
        "value": 15
    }
)
result = resp.json()
print(result)

3

Resolve Names

Resolve a human-readable name to a full user profile. Returns the canonical ID, domain, bio, trust score, and verification status for any registered identity.

GET /user/{userId}

curl

curl https://sandbox.socialos.io/v2/user/alice.kred \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "id": "usr_a1b2c3d4",
  "name": "alice.kred",
  "domain": "kred.io",
  "bio": {
    "screen_name": "Alice",
    "avatar": "https://cdn.socialos.io/avatars/alice.png"
  },
  "score": 97,
  "verified": true,
  "created_at": "2025-06-15T08:00:00Z"
}

Python

import requests

resp = requests.get(
    "https://sandbox.socialos.io/v2/user/alice.kred",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
result = resp.json()
print(result)

4

Complete Agent

A complete Identity agent that verifies a credential, updates the reputation score, and resolves the full user profile in one script.

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://sandbox.socialos.io/v2"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def verify_credential(user_id: str, credential: str) -> dict:
    """Verify an on-chain credential for a user."""
    resp = requests.post(f"{BASE}/identity/verify", headers=HEADERS, json={
        "userId": user_id,
        "type": "onchain",
        "credential": credential
    })
    return resp.json()


def update_reputation(user_id: str, action: str, value: int) -> dict:
    """Update the trust score after a verified action."""
    resp = requests.post(f"{BASE}/gamification/score", headers=HEADERS, json={
        "userId": user_id,
        "metric": "trust",
        "action": action,
        "value": value
    })
    return resp.json()


def resolve_name(user_id: str) -> dict:
    """Resolve a human-readable name to a full profile."""
    resp = requests.get(f"{BASE}/user/{user_id}", headers=HEADERS)
    return resp.json()


def main():
    user = "alice.kred"

    # Step 1 - Verify the wallet credential
    verification = verify_credential(user, "eth_wallet")
    print(f"Verified: {verification['verified']} (confidence {verification['confidence']})")

    # Step 2 - Bump reputation for successful verification
    score = update_reputation(user, "credential_verified", 15)
    print(f"Trust score: {score['previous']} -> {score['current']} (rank #{score['rank']})")

    # Step 3 - Resolve the full profile
    profile = resolve_name(user)
    print(f"Profile: {profile['name']} | Score: {profile['score']} | Verified: {profile['verified']}")


if __name__ == "__main__":
    main()

5

Next Steps

Continue building with these related guides and resources.

Build a Profile

Sync on-chain profiles and aggregate activity feeds.

Build a Score System

Compute trust scores, rank leaderboards, and flag anomalies.

Agent Quick Start

Authentication, base setup, and your first API call in under 5 minutes.

Full API Reference

Complete documentation for every endpoint, parameter, and response type.

Pricing

Compare plans and find the right tier for your agent's usage volume.