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

# Sybil Detection

> Analyze an Ethereum address for sybil behavior using on-chain transaction signals

## Overview

Analyzes an Ethereum address for sybil behavior by computing behavioral and relational signals from on-chain transaction data. Returns a composite sybil score (0-100, where higher = more likely sybil) along with individual indicator values.

<Info>
  This endpoint examines **Ethereum mainnet** transaction history to detect patterns consistent with sybil wallets -low diversity of counterparties, scripted timing, minimal gas expenditure, and lack of identity attestations.
</Info>

## Authentication

This endpoint supports two authentication methods:

| Method       | Header                               | Cost         |
| ------------ | ------------------------------------ | ------------ |
| API Token    | `Authorization: Bearer YOUR_API_KEY` | 3 Cred Units |
| x402 Payment | `X-PAYMENT: <signed_payment>`        | \$0.03 USDC  |

<Tip>
  **x402 payments** allow instant, accountless access. Pay per request with USDC on Base -no signup required.
  [Try it live →](https://credprotocol.com/try)
</Tip>

## Path Parameters

<ParamField path="address" type="string" required>
  Ethereum address or ENS name (e.g., `vitalik.eth` or `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`)
</ParamField>

## Response

<ResponseField name="address" type="string">
  The resolved Ethereum address (checksummed)
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp of when the analysis was computed
</ResponseField>

<ResponseField name="sybil_score" type="integer">
  Composite sybil score from 0-100. Higher scores indicate a greater likelihood that the address is a sybil.
</ResponseField>

<ResponseField name="risk_level" type="string">
  Human-readable risk classification derived from `sybil_score`. One of: `low`, `medium`, `high`, `critical`.
</ResponseField>

<ResponseField name="indicators" type="object">
  Individual signals used to compute the composite score.
</ResponseField>

<ResponseField name="indicators.count_unique_counterparties" type="integer">
  Number of unique addresses this wallet has transacted with (normal transactions + ERC-20 token transfers), excluding itself.
</ResponseField>

<ResponseField name="indicators.count_unique_contracts_interacted" type="integer">
  Number of unique smart contracts called (transactions with non-empty input data) or created.
</ResponseField>

<ResponseField name="indicators.total_gas_spent_eth" type="number">
  Total gas spent on outbound transactions, in ETH. Calculated as the sum of gasUsed times gasPrice for all transactions sent from this address.
</ResponseField>

<ResponseField name="indicators.funding_source_address" type="string">
  The address that first funded this wallet (sender of the first inbound ETH transfer). Null if no inbound value transfers exist.
</ResponseField>

<ResponseField name="indicators.transaction_time_entropy" type="number">
  Shannon entropy of inter-transaction time deltas, normalized to 0-1. Higher values indicate more varied (human-like) timing patterns; lower values suggest scripted/automated behavior.
</ResponseField>

<ResponseField name="indicators.identity_attestations" type="integer">
  Number of verified identity attestations associated with this address (ENS name, Gitcoin Passport, POAPs, credentials, etc.).
</ResponseField>

<ResponseField name="indicators.wallet_age_days" type="integer">
  Number of days since the wallet's first transaction on Ethereum mainnet.
</ResponseField>

<ResponseField name="indicators.transaction_count" type="integer">
  Total number of normal transactions on Ethereum mainnet.
</ResponseField>

## Risk Levels

| Score  | Risk Level | Interpretation                                      |
| ------ | ---------- | --------------------------------------------------- |
| 0-24   | `low`      | Unlikely sybil -diverse activity, verified identity |
| 25-49  | `medium`   | Some suspicious characteristics                     |
| 50-74  | `high`     | Likely sybil -limited activity or identity          |
| 75-100 | `critical` | Very likely sybil -minimal on-chain presence        |

## Scoring Methodology

The sybil score is computed by normalizing each indicator through a sigmoid function and combining them with the following weights:

| Indicator             | Weight | Description                                 |
| --------------------- | ------ | ------------------------------------------- |
| Identity Attestations | 25%    | Verified on-chain/off-chain identity proofs |
| Unique Counterparties | 20%    | Diversity of transaction partners           |
| Unique Contracts      | 15%    | Breadth of smart contract interactions      |
| Gas Spent             | 10%    | Economic commitment to the network          |
| Time Entropy          | 10%    | Human-like transaction timing               |
| Wallet Age            | 10%    | Longevity of the address                    |
| Transaction Count     | 10%    | Overall activity level                      |

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.credprotocol.com/api/v2/identity/address/vitalik.eth/sybil" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.credprotocol.com/api/v2/identity/address/vitalik.eth/sybil',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const sybil = await response.json();
  console.log(`Sybil Score: ${sybil.sybil_score}/100`);
  console.log(`Risk Level: ${sybil.risk_level}`);
  console.log(`Unique Counterparties: ${sybil.indicators.count_unique_counterparties}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.credprotocol.com/api/v2/identity/address/vitalik.eth/sybil",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )

  sybil = response.json()
  print(f"Sybil Score: {sybil['sybil_score']}/100")
  print(f"Risk Level: {sybil['risk_level']}")
  print(f"Unique Counterparties: {sybil['indicators']['count_unique_counterparties']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "timestamp": "2024-03-12T14:30:00+00:00",
    "sybil_score": 12,
    "risk_level": "low",
    "indicators": {
      "count_unique_counterparties": 142,
      "count_unique_contracts_interacted": 37,
      "total_gas_spent_eth": 0.847,
      "funding_source_address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "transaction_time_entropy": 0.82,
      "identity_attestations": 3,
      "wallet_age_days": 1095,
      "transaction_count": 456
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Invalid Ethereum address",
    "status_code": 400
  }
  ```

  ```json 401 theme={null}
  {
    "detail": "Invalid or expired API token. Please create a new API token in /dashboard/console."
  }
  ```

  ```json 402 theme={null}
  {
    "error": "authentication_required",
    "message": "This endpoint requires authentication.",
    "cred_units": 3,
    "options": [
      { "method": "api_token", "cost": "3 Cred Units" },
      { "method": "x402_payment", "price": "$0.03", "currency": "USDC" }
    ]
  }
  ```
</ResponseExample>

## Use Cases

<AccordionGroup>
  <Accordion title="Airdrop Protection">
    Screen recipient addresses before distributing tokens. Flag addresses with `high` or `critical` risk levels to prevent sybil farming.
  </Accordion>

  <Accordion title="Governance Sybil Resistance">
    Verify that voters in DAO governance represent unique humans by checking sybil scores before counting votes or distributing voting power.
  </Accordion>

  <Accordion title="Lending Risk Assessment">
    Combine sybil detection with credit scoring to identify borrowers who may be operating multiple wallets to circumvent lending limits.
  </Accordion>

  <Accordion title="Community Verification">
    Gate access to communities, allowlists, or early access programs by requiring a sybil score below a threshold (e.g., score under 25).
  </Accordion>
</AccordionGroup>

## Performance

* **Response Time**: Typically 2-5 seconds (uncached), under 100ms (cached)
* **Caching**: Results cached for 30 minutes per address
* **Data Source**: Ethereum mainnet only (via Etherscan API)