> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sorsa Score & Crypto Analytics

# Sorsa Score and Crypto Social Graph Analytics

Sorsa maintains an internal database of crypto-related X accounts - projects, influencers, KOLs, venture capital firms, and their employees. The endpoints in this section tap into that database to provide analytics that go beyond standard X profile data: an influence score that measures an account's standing within the crypto ecosystem, follower categorization by type (influencer, project, VC), and tracking of recent follow activity among crypto accounts.

These endpoints are specifically designed for crypto due diligence, influencer vetting, project discovery, and community analysis. If you are evaluating whether a crypto project is legitimate, assessing an influencer's real weight in the space, or tracking which VCs are paying attention to emerging projects, this is the data layer you need.

> **Free to start:** Every endpoint here works on your first 100 requests: one-time, no credit card, no expiry. A full due-diligence pass is about four calls per account (Score, Score change, follower breakdown, top followers), so 100 requests covers roughly 25 accounts before you need a plan.

> **Note:** The Sorsa Score and related analytics are also available through the [Sorsa web app](https://api.sorsa.io/) with a visual interface. The API endpoints documented here provide programmatic access to the same underlying data for integration into your own tools and workflows.

***

## What is the Sorsa Score?

The Sorsa Score is a numeric metric that reflects how many influential crypto accounts follow a given account, and how influential those followers are. It is not based on total follower count, content quality, profile appearance, or verification status. It is based purely on the crypto social graph: who follows you, and how much weight they carry.

Key characteristics:

* **Quality matters more than quantity.** A few followers with a Score of 1000+ contribute more than dozens of followers with a Score of 200. The score rewards genuine recognition from established figures, not mass-following.
* **Follow-for-follow and mass-following accounts are excluded.** Sorsa detects and filters out accounts that artificially inflate their follower lists. These accounts do not contribute to Score calculations.
* **Content, profile design, and blue checkmarks do not directly affect the Score.** However, high-quality content tends to attract influential followers over time, so there is often a correlation.
* **The Score is dynamic.** It changes as influential accounts follow or unfollow. The `/score-changes` endpoint tracks this movement over weekly and monthly windows.

A high Sorsa Score signals that an account is genuinely recognized within the crypto ecosystem. A low score on an account claiming to be a major player is a red flag worth investigating.

***

## Endpoints Overview

| Endpoint                | What it returns                                                    |
| :---------------------- | :----------------------------------------------------------------- |
| `GET /score`            | The current Sorsa Score for an account                             |
| `GET /score-changes`    | Score delta over the last week and month                           |
| `GET /followers-stats`  | Follower count broken down by category: influencers, projects, VCs |
| `GET /top-followers`    | Top 20 followers ranked by Sorsa Score                             |
| `GET /top-following`    | Top 20 accounts the user follows, ranked by Score                  |
| `GET /new-followers-7d` | Crypto accounts that followed the user in the last 7 days          |
| `GET /new-following-7d` | Crypto accounts the user started following in the last 7 days      |

All endpoints accept `username`, `user_id`, or `user_link` as input (exactly one of the three required). All use the GET method.

***

## Get the Sorsa Score

**Endpoint:** `GET /v3/score`

```bash theme={null}
curl "https://api.sorsa.io/v3/score?username=VitalikButerin" \
  -H "ApiKey: YOUR_API_KEY"
```

```json theme={null}
{"score": 1843.7}
```

```python theme={null}
import requests

API_KEY = "YOUR_API_KEY"

def get_score(username):
    resp = requests.get(
        "https://api.sorsa.io/v3/score",
        headers={"ApiKey": API_KEY},
        params={"username": username},
    )
    resp.raise_for_status()
    return resp.json()["score"]

print(f"Vitalik's Sorsa Score: {get_score('VitalikButerin')}")
```

Like the other endpoints in this section, `/score` accepts `username`, `user_id`, or `user_link` (provide exactly one). Higher scores indicate stronger recognition among crypto influencers, projects, and VCs. Accounts with very large follower bases may take slightly longer to return on the first request.

***

## Track Score Changes Over Time

**Endpoint:** `GET /v3/score-changes`

Returns how much the Score has changed in the last week and month. Useful for detecting momentum - an account gaining Score rapidly may be an emerging project worth watching; an account losing Score may be falling out of favor.

```python theme={null}
def get_score_changes(username):
    resp = requests.get(
        "https://api.sorsa.io/v3/score-changes",
        headers={"ApiKey": API_KEY},
        params={"username": username},
    )
    resp.raise_for_status()
    return resp.json()

changes = get_score_changes("some_crypto_project")
print(f"Week delta:  {changes['week_delta']:+}")
print(f"Month delta: {changes['month_delta']:+}")
```

Response:

```json theme={null}
{
  "week_delta": 12,
  "month_delta": 24
}
```

A positive `week_delta` means the account gained Score in the past 7 days (more influential accounts followed them). A negative delta means influential followers unfollowed or lost their own Score.

**Requirement:** The account must already be tracked in the Sorsa database. New or previously untracked accounts will not have historical Score data.

***

## Follower Breakdown by Category

**Endpoint:** `GET /v3/followers-stats`

Breaks down an account's followers into three categories from Sorsa's database: influencers (individual crypto KOLs), projects (crypto project accounts), and venture capitals (VCs and their employees).

```python theme={null}
def get_follower_breakdown(username):
    resp = requests.get(
        "https://api.sorsa.io/v3/followers-stats",
        headers={"ApiKey": API_KEY},
        params={"username": username},
    )
    resp.raise_for_status()
    return resp.json()

stats = get_follower_breakdown("some_crypto_project")
print(f"Total followers (Sorsa DB): {stats['followers_count']}")
print(f"  Influencers: {stats['influencers_count']}")
print(f"  Projects:    {stats['projects_count']}")
print(f"  VCs:         {stats['venture_capitals_count']}")
```

Response:

```json theme={null}
{
  "followers_count": 16,
  "influencers_count": 12,
  "projects_count": 3,
  "venture_capitals_count": 1,
  "user_protected": false
}
```

Note that `followers_count` here refers to the number of followers from Sorsa's crypto database, not the account's total X follower count. An account with 50,000 X followers might have 200 crypto-relevant followers tracked by Sorsa.

This breakdown is particularly useful for due diligence: a project claiming to be VC-backed should have VC accounts in their follower stats. A project with zero VC followers and zero project followers despite claiming partnerships is a warning sign.

***

## Top 20 Followers and Following by Score

**Endpoint:** `GET /v3/top-followers`

Returns the 20 followers with the highest Sorsa Score. This tells you which of the most influential crypto accounts are watching this profile.

**Endpoint:** `GET /v3/top-following`

Returns the 20 accounts the user follows that have the highest Score. This reveals whose content and activity the account considers worth tracking.

```python theme={null}
def get_top_followers(username):
    resp = requests.get(
        "https://api.sorsa.io/v3/top-followers",
        headers={"ApiKey": API_KEY},
        params={"username": username},
    )
    resp.raise_for_status()
    return resp.json().get("users", [])


def get_top_following(username):
    resp = requests.get(
        "https://api.sorsa.io/v3/top-following",
        headers={"ApiKey": API_KEY},
        params={"username": username},
    )
    resp.raise_for_status()
    return resp.json().get("users", [])


# Who are the biggest names following this project?
top = get_top_followers("some_crypto_project")
print("Top followers by Sorsa Score:")
for u in top[:10]:
    print(f"  @{u['username']} (Score {u.get('score', 0)}, {u['followers_count']:,} followers)")
    print(f"    {u.get('description', '')[:60]}")
```

The two endpoints return slightly different shapes:

* `/top-followers` returns a `TopFollowersResponse`: an array of compact follower profiles, each carrying a `score` field (that follower's own Sorsa Score) so you can gauge how influential each one is. These profiles are compact and omit some fields present on a full profile, such as `location` and `bio_urls`.
* `/top-following` returns a `FollowersResponse`: `Follower` objects with the standard profile fields plus `followerDate` (when the follow relationship was established). Note there is no `score` field on this response.

If you need the full profile for a top follower (bio links, location, media count), pass its handle to `/info-batch`.

***

## New Followers and Following (Last 7 Days)

**Endpoint:** `GET /v3/new-followers-7d`

Returns crypto accounts from Sorsa's database that started following the specified user in the last 7 days.

**Endpoint:** `GET /v3/new-following-7d`

Returns crypto accounts from Sorsa's database that the specified user started following in the last 7 days.

```python theme={null}
def get_new_followers_7d(username):
    resp = requests.get(
        "https://api.sorsa.io/v3/new-followers-7d",
        headers={"ApiKey": API_KEY},
        params={"username": username},
    )
    resp.raise_for_status()
    return resp.json().get("users", [])


def get_new_following_7d(username):
    resp = requests.get(
        "https://api.sorsa.io/v3/new-following-7d",
        headers={"ApiKey": API_KEY},
        params={"username": username},
    )
    resp.raise_for_status()
    return resp.json().get("users", [])


new_followers = get_new_followers_7d("some_crypto_project")
print(f"New crypto followers this week: {len(new_followers)}")
for u in new_followers:
    print(f"  @{u['username']} followed on {u.get('followerDate', 'unknown')}")
```

Both 7-day endpoints return a `FollowersResponse` (`Follower` objects with a `followerDate`).

### Database Dependency

Both 7-day endpoints have important constraints to understand:

1. **The target account must already be in Sorsa's database.** If you query an account Sorsa has not been tracking, there is no historical data to compare against, so the endpoint cannot determine what is "new."
2. **Only follows involving accounts in Sorsa's database are shown.** If a random non-crypto X account follows the target, it will not appear in these results. These endpoints track movement within the crypto social graph specifically - crypto accounts following other crypto accounts.

This makes the data highly relevant for crypto analysis (you see exactly which known crypto players are making new connections) but it is not a substitute for the general `/followers` endpoint if you need the complete follower list including non-crypto accounts. See [Followers & Following](https://docs.sorsa.io/followers-and-following) for the general-purpose approach.

***

## Practical Applications

### Project Due Diligence

When evaluating a crypto project, combine several endpoints to build a trust profile:

```python theme={null}
def due_diligence_report(username):
    """Quick due diligence check for a crypto project."""
    score = get_score(username)
    changes = get_score_changes(username)
    stats = get_follower_breakdown(username)
    top = get_top_followers(username)

    print(f"Due Diligence: @{username}")
    print(f"{'='*40}")
    print(f"Sorsa Score:   {score}")
    print(f"  Week change: {changes['week_delta']:+}")
    print(f"  Month change:{changes['month_delta']:+}")
    print()
    print(f"Crypto followers: {stats['followers_count']}")
    print(f"  Influencers: {stats['influencers_count']}")
    print(f"  Projects:    {stats['projects_count']}")
    print(f"  VCs:         {stats['venture_capitals_count']}")
    print()

    if top:
        print(f"Top followers by Score:")
        for u in top[:5]:
            print(f"  @{u['username']} (Score {u.get('score', 0)}, {u['followers_count']:,} followers)")
    else:
        print("No significant crypto followers found - investigate further.")

    # Red flags
    flags = []
    if score < 10:
        flags.append("Very low Score - minimal recognition in crypto")
    if stats["venture_capitals_count"] == 0 and stats["projects_count"] == 0:
        flags.append("No VC or project followers - claims of partnerships may be false")
    if changes["month_delta"] < -20:
        flags.append("Score dropping fast - influential followers are leaving")

    if flags:
        print(f"\nRed flags:")
        for f in flags:
            print(f"  - {f}")

    return score, stats, top


due_diligence_report("some_crypto_project")
```

### Comparing Projects Side by Side

```python theme={null}
projects = ["project_a", "project_b", "project_c"]

print(f"{'Project':<20} {'Score':>7} {'Week':>6} {'Influencers':>12} {'Projects':>9} {'VCs':>5}")
print("-" * 65)

for handle in projects:
    score = get_score(handle)
    changes = get_score_changes(handle)
    stats = get_follower_breakdown(handle)

    print(f"@{handle:<19} {score:>7.1f} {changes['week_delta']:>+6} "
          f"{stats['influencers_count']:>12} {stats['projects_count']:>9} "
          f"{stats['venture_capitals_count']:>5}")
```

### Tracking VC Activity

Monitor which projects a known VC account starts following - this can signal upcoming investments or partnerships:

```python theme={null}
vc_accounts = ["a16z_crypto", "paradigm", "polychain"]

for vc in vc_accounts:
    new_follows = get_new_following_7d(vc)
    if new_follows:
        print(f"@{vc} started following {len(new_follows)} new crypto accounts this week:")
        for u in new_follows:
            print(f"  @{u['username']} (followed {u.get('followerDate', 'recently')})")
    else:
        print(f"@{vc}: no new crypto follows this week")
    print()
```

### Early Project Discovery

Find projects that are gaining Score momentum - a rising Score means influential accounts are taking notice:

```python theme={null}
watchlist = ["new_project_1", "new_project_2", "new_project_3", "new_project_4"]

rising = []
for handle in watchlist:
    try:
        score = get_score(handle)
        changes = get_score_changes(handle)
        if changes["week_delta"] > 5:
            rising.append({
                "handle": handle,
                "score": score,
                "week_delta": changes["week_delta"],
            })
    except Exception:
        continue

rising.sort(key=lambda x: x["week_delta"], reverse=True)

print("Rising projects (Score gained this week):")
for r in rising:
    print(f"  @{r['handle']}: Score {r['score']} ({r['week_delta']:+} this week)")
```

***

## Exporting to CSV

```python theme={null}
import csv
import time

def export_crypto_analysis(handles, output_file="crypto_analysis.csv"):
    """Export Score and follower stats for a list of accounts."""
    fields = ["username", "score", "week_delta", "month_delta",
              "crypto_followers", "influencers", "projects", "vcs"]

    with open(output_file, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=fields)
        writer.writeheader()

        for handle in handles:
            try:
                score = get_score(handle)
                changes = get_score_changes(handle)
                stats = get_follower_breakdown(handle)

                writer.writerow({
                    "username": handle,
                    "score": score,
                    "week_delta": changes["week_delta"],
                    "month_delta": changes["month_delta"],
                    "crypto_followers": stats["followers_count"],
                    "influencers": stats["influencers_count"],
                    "projects": stats["projects_count"],
                    "vcs": stats["venture_capitals_count"],
                })
            except Exception as e:
                print(f"Error for @{handle}: {e}")

            time.sleep(0.15)  # 3 API calls per account

    print(f"Exported {len(handles)} accounts to {output_file}")
```

***

## Next Steps

* [Competitor Analysis](https://docs.sorsa.io/Competitor-Analysis) - combine Sorsa Score data with general profile and content analysis.
* [Followers & Following](https://docs.sorsa.io/followers-and-following) - extract the full follower list (not just crypto-tracked accounts).
* [Target Audience Discovery](https://docs.sorsa.io/target-audiences-Discovery) - find crypto audiences via community scraping and bio search.
* [Marketing Campaign Verification](https://docs.sorsa.io/Marketing-Campaign-Verification) - verify engagement actions for crypto marketing campaigns.
* [API Reference](https://docs.sorsa.io/api-reference-guide) - full specification for all Sorsa Score and crypto analytics endpoints.