> ## 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 e análises de cripto

# Sorsa Score e análise da rede social cripto

A Sorsa mantém uma base de contas do X relacionadas a cripto: projetos, influenciadores, líderes de opinião, fundos de venture capital e seus profissionais. Estes endpoints usam essa base para oferecer pontuação de influência, categorias de seguidores e acompanhamento de novas conexões, além dos dados comuns de perfil.

São recursos para avaliar projetos, analisar influenciadores, descobrir iniciativas e estudar comunidades. As métricas ajudam a investigar reconhecimento e relacionamentos no ecossistema.

> **Comece grátis:** todas as operações funcionam com as primeiras 100 requisições, sem cartão ou validade. Uma análise com Score, evolução, categorias e principais seguidores usa cerca de quatro chamadas por conta, permitindo testar aproximadamente 25 contas.

> Os mesmos dados também estão disponíveis visualmente no [aplicativo web da Sorsa](https://api.sorsa.io/). A API permite integrá-los às suas ferramentas.

## O que é Sorsa Score?

É uma métrica numérica baseada em quantas contas influentes de cripto seguem uma conta e no peso desses seguidores. Não usa diretamente total de seguidores, qualidade do conteúdo, aparência do perfil ou selo de verificação.

* **Qualidade pesa mais que quantidade.** Alguns seguidores com Score acima de 1.000 contribuem mais que dezenas com Score 200.
* **Contas de follow-for-follow e seguidores em massa são excluídas** dos cálculos quando identificadas pela Sorsa.
* **Conteúdo, design e selo não alteram diretamente a pontuação**, embora conteúdo de qualidade possa atrair seguidores influentes.
* **O Score muda com a rede.** Novas conexões e unfollows afetam a pontuação; `/score-changes` mostra a variação semanal e mensal.

Um Score alto indica reconhecimento na rede cripto acompanhada. Um Score baixo em uma conta que se apresenta como muito influente merece investigação.

## Endpoints

| Endpoint                | Retorno                                                      |
| :---------------------- | :----------------------------------------------------------- |
| `GET /score`            | Pontuação atual                                              |
| `GET /score-changes`    | Variação semanal e mensal                                    |
| `GET /followers-stats`  | Seguidores por categoria: influenciadores, projetos e fundos |
| `GET /top-followers`    | Top 20 seguidores por Score                                  |
| `GET /top-following`    | Top 20 contas seguidas por Score                             |
| `GET /new-followers-7d` | Novos seguidores cripto dos últimos 7 dias                   |
| `GET /new-following-7d` | Novas contas cripto seguidas nos últimos 7 dias              |

Todos usam GET e aceitam exatamente um entre `username`, `user_id` e `user_link`.

## Consultar o 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')}")
```

Pontuações maiores indicam reconhecimento mais forte entre influenciadores, projetos e fundos. Contas com muitos seguidores podem demorar um pouco mais na primeira consulta.

## Acompanhar a evolução

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

Retorna mudanças na semana e no mês, úteis para identificar contas ganhando ou perdendo reconhecimento.

```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']:+}")
```

Resposta:

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

`week_delta` positivo indica ganho nos últimos 7 dias. Uma variação negativa pode refletir unfollows de contas influentes ou queda no Score delas.

**Requisito:** a conta precisa já estar acompanhada na base da Sorsa. Contas novas ou não acompanhadas não têm histórico de pontuação.

## Categorias de seguidores

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

Agrupa seguidores da base em influenciadores individuais, projetos e fundos de venture capital, incluindo profissionais desses fundos.

```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']}")
```

Resposta:

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

`followers_count` aqui é a quantidade na base cripto da Sorsa, não o total do X. Uma conta com 50.000 seguidores pode ter apenas 200 acompanhados nessa base.

A distribuição ajuda na avaliação de relacionamentos declarados: ausência de fundos ou projetos entre seguidores pode motivar investigação adicional de alegações de apoio ou parceria.

## Top 20 seguidores e contas seguidas

**`GET /v3/top-followers`:** 20 seguidores de maior Score.

**`GET /v3/top-following`:** 20 contas seguidas de maior Score.

```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]}")
```

As estruturas diferem:

* `/top-followers` retorna `TopFollowersResponse`, com perfis compactos e `score` individual. Campos como `location` e `bio_urls` são omitidos.
* `/top-following` retorna `FollowersResponse`, com objetos `Follower`, perfil padrão e `followerDate`. Não inclui `score`.

Para completar um perfil compacto, envie seu nome a `/info-batch`.

## Novas conexões dos últimos 7 dias

**`GET /v3/new-followers-7d`:** contas cripto que começaram a seguir o usuário.

**`GET /v3/new-following-7d`:** contas cripto que o usuário começou a seguir.

```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')}")
```

Ambos retornam `FollowersResponse` com objetos `Follower` e `followerDate`.

### Dependência da base

1. **A conta-alvo precisa já estar na base.** Sem acompanhamento anterior, não há histórico para identificar novas conexões.
2. **Só entram relações com contas da base cripto.** Um novo seguidor de fora dessa base não aparece.

Use esses dados para a rede cripto, não como substituto da lista geral `/followers`. Veja [seguidores e contas seguidas](https://docs.sorsa.io/pt-BR/followers-and-following).

## Aplicações práticas

### Avaliar um projeto

Combine endpoints para analisar reconhecimento e conexões:

```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")
```

### Comparar projetos

```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}")
```

### Acompanhar fundos

Novas contas seguidas por um fundo podem sinalizar interesse em projetos ou possíveis parcerias:

```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()
```

### Descobrir projetos em ascensão

Identifique contas cuja pontuação está aumentando:

```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)")
```

## Exportar para 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}")
```

## Próximos passos

* [Concorrentes](https://docs.sorsa.io/pt-BR/Competitor-Analysis): combine Score, perfis e conteúdo.
* [Seguidores](https://docs.sorsa.io/pt-BR/followers-and-following): lista completa, inclusive fora de cripto.
* [Público-alvo](https://docs.sorsa.io/pt-BR/target-audiences-Discovery): bios e comunidades.
* [Campanhas](https://docs.sorsa.io/pt-BR/Marketing-Campaign-Verification): verifique ações.
* [Referência](https://docs.sorsa.io/pt-BR/api-reference-guide): especificações.