Skip to content

API Endpoints

Complete reference for all Chain Sentinel API endpoints.

Base URL

https://api.chainsentinel.net

Authentication

All endpoints require API key authentication. See API Authentication for details.

curl -H "X-API-Key: your_api_key" https://api.chainsentinel.net/tokens

Rate Limits

Tier Requests/Day Rate
Free 100 1 req/15min
Pro 1,000 1 req/90s
Enterprise Unlimited No limit

Response Format

All responses are JSON:

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-01-10T12:34:56Z"
}

Error Response: 

{
  "success": false,
  "error": "Invalid API key",
  "code": "AUTH_001",
  "timestamp": "2026-01-10T12:34:56Z"
}

Tokens

List Tokens

Get a list of analyzed tokens.

Endpoint: GET /tokens

Parameters:

Parameter Type Required Description
limit integer No Number of results (default: 50, max: 100)
offset integer No Pagination offset (default: 0)
prediction string No Filter by prediction: SCAM or LEGIT
min_confidence integer No Minimum confidence (0-100)
sort string No Sort by: created_at, confidence, risk_score
order string No Sort order: asc or desc (default: desc)

Example Request: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/tokens?prediction=SCAM&min_confidence=80&limit=10"

Example Response: 

{
  "success": true,
  "data": {
    "tokens": [
      {
        "address": "ABC...123",
        "name": "SCAM Token",
        "symbol": "SCAM",
        "prediction": "SCAM",
        "confidence": 98,
        "risk_score": 95,
        "model": "GNN_v2",
        "created_at": "2026-01-10T10:00:00Z",
        "analyzed_at": "2026-01-10T10:05:00Z"
      }
    ],
    "total": 1247,
    "limit": 10,
    "offset": 0
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Get Token

Get detailed information about a specific token.

Endpoint: GET /tokens/{address}

Parameters:

Parameter Type Required Description
address string Yes Token address (path parameter)

Example Request: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/tokens/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"

Example Response: 

{
  "success": true,
  "data": {
    "address": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "name": "Bonk",
    "symbol": "BONK",
    "prediction": "LEGIT",
    "confidence": 92,
    "risk_score": 15,
    "model": "XGBoost",
    "features": {
      "holder_count": 125000,
      "transaction_count": 5000000,
      "liquidity_usd": 2500000,
      "top_10_concentration": 0.28,
      "creator_risk_score": 10
    },
    "shap_values": {
      "holder_count": 0.15,
      "liquidity_usd": 0.12,
      "top_10_concentration": -0.08
    },
    "creator": {
      "address": "Creator...Wallet",
      "risk_score": 10,
      "tokens_created": 1,
      "scam_rate": 0
    },
    "created_at": "2022-12-25T00:00:00Z",
    "analyzed_at": "2026-01-10T10:00:00Z"
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Analyze Token

Request analysis of a new token.

Endpoint: POST /tokens/analyze

Parameters:

Parameter Type Required Description
address string Yes Token address to analyze
force boolean No Force re-analysis (default: false)

Example Request: 

curl -X POST \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"address": "ABC...123", "force": false}' \
  "https://api.chainsentinel.net/tokens/analyze"

Example Response: 

{
  "success": true,
  "data": {
    "address": "ABC...123",
    "status": "analyzing",
    "estimated_time": 30,
    "job_id": "job_123456"
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Check Analysis Status: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/tokens/analyze/job_123456"

Get Token Network

Get network graph data for a token.

Endpoint: GET /tokens/{address}/network

Parameters:

Parameter Type Required Description
address string Yes Token address (path parameter)
depth integer No Network depth (default: 2, max: 3)

Example Request: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/tokens/ABC...123/network?depth=2"

Example Response: 

{
  "success": true,
  "data": {
    "nodes": [
      {
        "id": "token_ABC...123",
        "type": "token",
        "label": "SCAM (SCAM)",
        "prediction": "SCAM",
        "confidence": 98
      },
      {
        "id": "wallet_DEF...456",
        "type": "wallet",
        "label": "Creator",
        "risk_score": 85
      }
    ],
    "edges": [
      {
        "source": "wallet_DEF...456",
        "target": "token_ABC...123",
        "type": "created",
        "weight": 1.0
      }
    ]
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Wallets

Get Wallet

Get information about a wallet.

Endpoint: GET /wallets/{address}

Parameters:

Parameter Type Required Description
address string Yes Wallet address (path parameter)

Example Request: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/wallets/ABC...123"

Example Response: 

{
  "success": true,
  "data": {
    "address": "ABC...123",
    "risk_score": 85,
    "role": "creator",
    "tokens_created": 15,
    "scam_rate": 0.87,
    "total_value_stolen": 1200000,
    "victims": 847,
    "first_seen": "2024-03-15T00:00:00Z",
    "last_activity": "2026-01-09T18:00:00Z",
    "cluster_id": "cluster_42",
    "is_known_scammer": true
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Get Wallet Tokens

Get tokens created by a wallet.

Endpoint: GET /wallets/{address}/tokens

Parameters:

Parameter Type Required Description
address string Yes Wallet address (path parameter)
limit integer No Number of results (default: 50)
offset integer No Pagination offset (default: 0)

Example Request: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/wallets/ABC...123/tokens"

Example Response: 

{
  "success": true,
  "data": {
    "tokens": [
      {
        "address": "Token1...123",
        "name": "SCAM1",
        "symbol": "SCAM1",
        "prediction": "SCAM",
        "confidence": 98,
        "created_at": "2026-01-09T10:00:00Z"
      }
    ],
    "total": 15,
    "limit": 50,
    "offset": 0
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Clusters

List Clusters

Get a list of wallet clusters.

Endpoint: GET /clusters

Parameters:

Parameter Type Required Description
limit integer No Number of results (default: 50)
offset integer No Pagination offset (default: 0)
min_size integer No Minimum cluster size (default: 3)

Example Request: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/clusters?min_size=5"

Example Response: 

{
  "success": true,
  "data": {
    "clusters": [
      {
        "id": "cluster_42",
        "name": "Scam Ring #42",
        "size": 8,
        "risk_score": 95,
        "tokens_created": 23,
        "scam_rate": 0.91,
        "total_stolen": 2300000,
        "victims": 1247
      }
    ],
    "total": 156,
    "limit": 50,
    "offset": 0
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Get Cluster

Get detailed information about a cluster.

Endpoint: GET /clusters/{id}

Parameters:

Parameter Type Required Description
id string Yes Cluster ID (path parameter)

Example Request: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/clusters/cluster_42"

Example Response: 

{
  "success": true,
  "data": {
    "id": "cluster_42",
    "name": "Scam Ring #42",
    "wallets": [
      {
        "address": "ABC...123",
        "role": "master",
        "risk_score": 95
      },
      {
        "address": "DEF...456",
        "role": "puppet",
        "risk_score": 80
      }
    ],
    "tokens": [
      {
        "address": "Token1...123",
        "name": "SCAM1",
        "prediction": "SCAM",
        "confidence": 98
      }
    ],
    "statistics": {
      "size": 8,
      "tokens_created": 23,
      "scam_rate": 0.91,
      "total_stolen": 2300000,
      "victims": 1247
    }
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Watchlist

Get Watchlist

Get your watchlist items.

Endpoint: GET /watchlist

Parameters:

Parameter Type Required Description
type string No Filter by type: token or wallet

Example Request: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/watchlist?type=token"

Example Response: 

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 123,
        "type": "token",
        "address": "ABC...123",
        "name": "SCAM (SCAM)",
        "alerts": ["rug_pull", "price_drop"],
        "sensitivity": "medium",
        "created_at": "2026-01-09T10:00:00Z"
      }
    ],
    "total": 5,
    "limit": 5
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Add to Watchlist

Add a token or wallet to your watchlist.

Endpoint: POST /watchlist

Parameters:

Parameter Type Required Description
type string Yes token or wallet
address string Yes Token/wallet address
alerts array No Alert types to enable
sensitivity string No low, medium, or high

Example Request: 

curl -X POST \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "token",
    "address": "ABC...123",
    "alerts": ["rug_pull", "price_drop"],
    "sensitivity": "medium"
  }' \
  "https://api.chainsentinel.net/watchlist"

Example Response: 

{
  "success": true,
  "data": {
    "id": 123,
    "type": "token",
    "address": "ABC...123",
    "alerts": ["rug_pull", "price_drop"],
    "sensitivity": "medium",
    "created_at": "2026-01-10T12:34:56Z"
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Remove from Watchlist

Remove an item from your watchlist.

Endpoint: DELETE /watchlist/{id}

Parameters:

Parameter Type Required Description
id integer Yes Watchlist item ID (path parameter)

Example Request: 

curl -X DELETE \
  -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/watchlist/123"

Example Response: 

{
  "success": true,
  "data": {
    "message": "Item removed from watchlist"
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Alerts

Get Alerts

Get your recent alerts.

Endpoint: GET /alerts

Parameters:

Parameter Type Required Description
limit integer No Number of results (default: 50)
offset integer No Pagination offset (default: 0)
severity string No Filter by severity: critical, warning, info
unread boolean No Only unread alerts (default: false)

Example Request: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/alerts?severity=critical&unread=true"

Example Response: 

{
  "success": true,
  "data": {
    "alerts": [
      {
        "id": 456,
        "type": "rug_pull",
        "severity": "critical",
        "token": {
          "address": "ABC...123",
          "name": "SCAM",
          "symbol": "SCAM"
        },
        "details": {
          "liquidity_change": -0.85,
          "creator_sold_usd": 65000
        },
        "recommendation": "SELL_IMMEDIATELY",
        "read": false,
        "created_at": "2026-01-10T12:30:00Z"
      }
    ],
    "total": 1,
    "unread": 1
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Mark Alert as Read

Mark an alert as read.

Endpoint: POST /alerts/{id}/read

Parameters:

Parameter Type Required Description
id integer Yes Alert ID (path parameter)

Example Request: 

curl -X POST \
  -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/alerts/456/read"

Example Response: 

{
  "success": true,
  "data": {
    "message": "Alert marked as read"
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Statistics

Get Global Stats

Get global platform statistics.

Endpoint: GET /stats

Example Request: 

curl -H "X-API-Key: your_api_key" \
  "https://api.chainsentinel.net/stats"

Example Response: 

{
  "success": true,
  "data": {
    "tokens_analyzed": 291547,
    "scam_rate": 0.803,
    "accuracy": 0.9606,
    "wallets_tracked": 125000,
    "clusters_detected": 156,
    "total_saved": 15000000
  },
  "timestamp": "2026-01-10T12:34:56Z"
}

Error Codes

Code Description
AUTH_001 Invalid API key
AUTH_002 API key expired
AUTH_003 Rate limit exceeded
REQ_001 Invalid request parameters
REQ_002 Missing required parameter
RES_001 Resource not found
RES_002 Resource already exists
SYS_001 Internal server error
SYS_002 Service unavailable

Support

Need help with the API?