API Authentication¶

Learn how to authenticate your API requests to Chain Sentinel.

Getting Your API Key¶

1. Log in to app.chainsentinel.net
2. Navigate to 🔑 API Keys
3. Click "Create New API Key"
4. Enter a name (e.g., "Production App")
5. Select your tier (Free/Pro/Enterprise)
6. Copy the key immediately (shown only once!)

Authentication Methods¶

Method 1: X-API-Key Header (Recommended)¶

Include your API key in the X-API-Key header:

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

Method 2: Authorization Bearer Header¶

Alternatively, use the Authorization header:

curl -H "Authorization: Bearer your_api_key_here" \
  https://api.chainsentinel.net/api/tokens

Method 3: Query Parameter (Not Recommended)¶

For testing only, you can pass the key as a query parameter:

curl "https://api.chainsentinel.net/api/tokens?api_key=your_api_key_here"

Code Examples¶

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://api.chainsentinel.net"

headers = {
    "X-API-Key": API_KEY
}

response = requests.get(
    f"{BASE_URL}/api/tokens",
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code}")

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.chainsentinel.net';

const headers = {
  'X-API-Key': API_KEY
};

const response = await fetch(
  `${BASE_URL}/api/tokens`,
  { headers }
);

if (response.ok) {
  const data = await response.json();
  console.log(data);
} else {
  console.error(`Error: ${response.status}`);
}

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    apiKey := "your_api_key_here"
    baseURL := "https://api.chainsentinel.net"

    client := &http.Client{}
    req, _ := http.NewRequest("GET", 
        baseURL+"/api/tokens", nil)

    req.Header.Add("X-API-Key", apiKey)

    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

<?php
$apiKey = 'your_api_key_here';
$baseURL = 'https://api.chainsentinel.net';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseURL . '/api/tokens');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 200) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo "Error: $httpCode\n";
}
?>

Rate Limiting¶

API requests are rate-limited based on your subscription tier.

Rate Limit Tiers¶

Rate Limit Headers¶

Every API response includes rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

• X-RateLimit-Limit - Total requests allowed per day
• X-RateLimit-Remaining - Requests remaining today
• X-RateLimit-Reset - Unix timestamp when limit resets

Handling Rate Limits¶

When you exceed the rate limit:

Status Code: 429 Too Many Requests

Response:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your free tier limit of 100 requests per day",
  "tier": "free",
  "limit": 100,
  "upgrade": "https://chainsentinel.net/pricing"
}

Example with retry logic:

import time
import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            # Get reset time from header
            reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
            wait_time = max(reset_time - time.time(), 0)

            print(f"Rate limit exceeded. Waiting {wait_time}s...")
            time.sleep(wait_time + 1)
            continue

        return response

    raise Exception("Max retries exceeded")

Error Responses¶

401 Unauthorized¶

Cause: Invalid or missing API key

Response:

{
  "error": "API key required",
  "message": "Please provide an API key via X-API-Key header"
}

Solution: Verify your API key is correct and included in the request.

403 Forbidden¶

Cause: Insufficient permissions or subscription tier

Response:

{
  "error": "Insufficient permissions",
  "message": "This endpoint requires Pro tier or higher"
}

Solution: Upgrade your subscription tier.

Security Best Practices¶

1. Store Keys Securely¶

Never hardcode API keys in your source code:

❌ Bad:

API_KEY = "cs_1234567890abcdef"  # Hardcoded!

✅ Good:

import os
API_KEY = os.getenv("CHAIN_SENTINEL_API_KEY")

2. Use Environment Variables¶

Store keys in environment variables:

# .env file
CHAIN_SENTINEL_API_KEY=your_api_key_here

# Load in code
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("CHAIN_SENTINEL_API_KEY")

3. Add to .gitignore¶

Prevent committing sensitive files:

# Environment variables
.env
.env.local
.env.production

# API keys
api_keys.txt
secrets.json
config/secrets.yml

4. Rotate Keys Regularly¶

Rotate your API keys every 90 days:

1. Create a new API key
2. Update your applications
3. Test thoroughly
4. Revoke the old key

5. Use Different Keys for Different Environments¶

Create separate keys for:

• Development
• Staging
• Production

This allows you to: - Track usage per environment - Revoke keys without affecting other environments - Set different rate limits

6. Monitor Usage¶

Regularly check your API key usage:

1. Go to 🔑 API Keys in dashboard
2. Review request counts
3. Check for unusual activity
4. Revoke compromised keys immediately

Key Management¶

Viewing Your Keys¶

Navigate to 🔑 API Keys to see:

• Key name
• Creation date
• Last used date
• Request count (last 24h)
• Status (active/revoked)

Revoking Keys¶

To revoke a compromised key:

1. Go to 🔑 API Keys
2. Find the key to revoke
3. Click "Revoke"
4. Confirm the action

Key Statistics¶

View detailed statistics for each key:

• Total requests (all time)
• Requests today
• Requests this month
• Average response time
• Error rate
• Most used endpoints

Testing Your API Key¶

Quick Test¶

curl -H "X-API-Key: your_api_key_here" \
  https://api.chainsentinel.net/api/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2026-01-10T00:00:00Z"
}

Full Test¶

curl -H "X-API-Key: your_api_key_here" \
  https://api.chainsentinel.net/api/tokens?limit=1

Expected response:

{
  "data": [
    {
      "address": "...",
      "symbol": "...",
      "is_rug": true,
      "confidence": 0.95
    }
  ],
  "success": true
}

Need Help?¶

• 📖 API Overview
• 📖 API Examples
• 📖 FAQ
• 💬 Telegram Community
• 📧 support@chainsentinel.net

Next: API Endpoints →