API Reference

SupaScan API Overview

SupaScan provides comprehensive access to Solana blockchain data through multiple interfaces:

REST API - Standard HTTP endpoints for common queries
SQL API - Direct ClickHouse queries for advanced analytics
Webhook API - Real-time notifications for token events
Custom Endpoints - Specialized analytics and market data

Authentication

All API requests require authentication via API key:

Authorization: Bearer YOUR_API_KEY

API keys can be generated in the SupaScan portal under API Keys section.

Base URL

https://api.supascan.xyz/v1

REST API Endpoints

Transaction Data

Get Transaction Details

GET /transactions/{signature}

Response:

{
  "signature": "5J7X8C9D2E1F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7",
  "slot": 123456789,
  "blockTime": 1640995200,
  "fee": 5000,
  "status": "success",
  "accounts": [
    {
      "pubkey": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "signer": true,
      "writable": true,
      "preBalance": 1000000000,
      "postBalance": 999995000
    }
  ],
  "instructions": [
    {
      "programId": "11111111111111111111111111111111",
      "accounts": [0, 1],
      "data": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB"
    }
  ]
}

Get Transactions by Wallet

GET /wallets/{address}/transactions?limit=50&offset=0

Query Parameters:

limit (optional): Number of transactions to return (max 100)
offset (optional): Number of transactions to skip
from (optional): Start timestamp
to (optional): End timestamp

Token Data

Get Token Information

GET /tokens/{mint}

Response:

{
  "mint": "So11111111111111111111111111111111111111112",
  "name": "Wrapped SOL",
  "symbol": "WSOL",
  "decimals": 9,
  "supply": 1000000000000000000,
  "marketCap": 50000000000,
  "price": 50.0,
  "volume24h": 1000000000,
  "holders": 1250000
}

Get Token Transfers

GET /tokens/{mint}/transfers?limit=100

Response:

{
  "transfers": [
    {
      "signature": "5J7X8C9D2E1F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7",
      "from": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "to": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": 1000000000,
      "timestamp": 1640995200
    }
  ],
  "total": 50000,
  "hasMore": true
}

SQL API (ClickHouse Direct Access)

Execute SQL Query

POST /sql/query
Content-Type: application/json

{
  "query": "SELECT * FROM transactions WHERE slot > 123456789 LIMIT 10"
}

Response:

{
  "data": [
    {
      "signature": "5J7X8C9D2E1F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7",
      "slot": 123456790,
      "blockTime": 1640995201,
      "fee": 5000,
      "success": 1
    }
  ],
  "rows": 1,
  "executionTime": 0.023
}

Common SQL Queries

Most Liquid Tokens (24h)

SELECT 
    token_mint,
    token_symbol,
    SUM(volume) as total_volume,
    COUNT(*) as trade_count
FROM token_swaps 
WHERE timestamp >= now() - INTERVAL 24 HOUR
GROUP BY token_mint, token_symbol
ORDER BY total_volume DESC
LIMIT 10

Most Active Wallets (7 days)

SELECT 
    wallet_address,
    COUNT(*) as transaction_count,
    SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as successful_txs,
    SUM(fee) as total_fees
FROM transactions 
WHERE timestamp >= now() - INTERVAL 7 DAY
GROUP BY wallet_address
ORDER BY transaction_count DESC
LIMIT 20

Token Creation Events

SELECT 
    signature,
    block_time,
    creator_wallet,
    token_mint,
    token_name,
    token_symbol,
    initial_supply
FROM token_creations 
WHERE timestamp >= now() - INTERVAL 1 DAY
ORDER BY block_time DESC

DEX Volume by Protocol

SELECT 
    dex_protocol,
    COUNT(*) as swap_count,
    SUM(volume_usd) as total_volume_usd,
    AVG(volume_usd) as avg_volume_usd
FROM dex_swaps 
WHERE timestamp >= now() - INTERVAL 24 HOUR
GROUP BY dex_protocol
ORDER BY total_volume_usd DESC

Custom Analytics Endpoints

DEX Fees by Protocol

Get Current Fees

GET /analytics/dex/fees?protocol=meteora&timeframe=24h

Query Parameters:

protocol: meteora, raydium, pumpfun, jupiter, orion
timeframe: 1h, 24h, 7d, 30d

Response:

{
  "protocol": "meteora",
  "timeframe": "24h",
  "fees": {
    "total_fees_usd": 125000.50,
    "average_fee_usd": 0.25,
    "median_fee_usd": 0.18,
    "fee_percentiles": {
      "p25": 0.12,
      "p50": 0.18,
      "p75": 0.28,
      "p90": 0.45,
      "p95": 0.67
    }
  },
  "swap_count": 500000,
  "unique_wallets": 45000
}

Most Liquid Tokens

Get Top Tokens by Volume

GET /analytics/tokens/liquidity?period=24h&limit=50

Response:

{
  "period": "24h",
  "tokens": [
    {
      "mint": "So11111111111111111111111111111111111111112",
      "symbol": "WSOL",
      "name": "Wrapped SOL",
      "volume_24h": 1500000000.50,
      "volume_change_24h": 12.5,
      "price": 50.25,
      "price_change_24h": 2.1,
      "market_cap": 50000000000,
      "liquidity": 2500000000,
      "holders": 1250000,
      "transactions_24h": 45000
    }
  ],
  "total_tokens": 50000
}

Most Active Wallets

Get Top Wallets by Activity

GET /analytics/wallets/activity?period=7d&metric=transactions&limit=100

Query Parameters:

period: 1h, 24h, 7d, 30d
metric: transactions, volume, fees, unique_tokens
limit: Number of results (max 1000)

Response:

{
  "period": "7d",
  "metric": "transactions",
  "wallets": [
    {
      "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "transaction_count": 15420,
      "successful_txs": 15380,
      "success_rate": 99.74,
      "total_volume_usd": 2500000.50,
      "unique_tokens_traded": 1250,
      "total_fees_paid": 12500.25,
      "first_seen": "2024-01-15T10:30:00Z",
      "last_activity": "2024-01-22T15:45:30Z"
    }
  ],
  "total_wallets": 500000
}

Token Deployer Analysis

Get Top Deployers

GET /analytics/deployers/top?period=30d&limit=50

Response:

{
  "period": "30d",
  "deployers": [
    {
      "wallet_address": "Deployer1234567890abcdef1234567890abcdef123456",
      "tokens_deployed": 1250,
      "successful_deployments": 1180,
      "success_rate": 94.4,
      "total_volume_generated": 50000000.50,
      "average_token_volume": 40000.40,
      "most_active_day": "2024-01-20",
      "deployment_frequency": "2.3 per day",
      "total_fees_spent": 250000.25
    }
  ]
}

Webhook API

Token Creation Alerts

Create Token Alert

POST /webhooks/token-alerts
Content-Type: application/json

{
  "webhook_url": "https://your-app.com/webhook",
  "filters": {
    "token_name_contains": ["PEPE", "DOGE", "SHIB"],
    "min_initial_supply": 1000000000,
    "max_initial_supply": 1000000000000,
    "deployer_wallet": "Deployer1234567890abcdef1234567890abcdef123456",
    "min_liquidity_usd": 10000,
    "dex_protocols": ["raydium", "meteora"],
    "exclude_known_deployers": true
  },
  "notification_settings": {
    "enabled": true,
    "cooldown_minutes": 5,
    "max_notifications_per_hour": 10
  }
}

Response:

{
  "webhook_id": "wh_1234567890abcdef",
  "status": "active",
  "created_at": "2024-01-22T10:30:00Z",
  "filters_applied": {
    "token_name_contains": 3,
    "min_initial_supply": 1000000000,
    "dex_protocols": 2
  }
}

Webhook Payload Example

When a token matching your criteria is created, you'll receive:

{
  "event_type": "token_created",
  "timestamp": "2024-01-22T15:45:30Z",
  "data": {
    "signature": "5J7X8C9D2E1F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7",
    "token": {
      "mint": "TokenMint1234567890abcdef1234567890abcdef123456",
      "name": "PEPE Coin",
      "symbol": "PEPE",
      "decimals": 9,
      "initial_supply": 1000000000000,
      "creator": "Deployer1234567890abcdef1234567890abcdef123456"
    },
    "liquidity": {
      "initial_liquidity_usd": 50000.00,
      "dex_protocol": "raydium",
      "pool_address": "PoolAddress1234567890abcdef1234567890abcdef123456"
    },
    "market_data": {
      "initial_price_usd": 0.00005,
      "market_cap_usd": 50000.00
    },
    "social_signals": {
      "twitter_mentions": 0,
      "telegram_mentions": 0,
      "reddit_mentions": 0
    }
  }
}

Advanced Token Filters

Bundle-based Alerts

POST /webhooks/token-alerts
Content-Type: application/json

{
  "webhook_url": "https://your-app.com/webhook",
  "filters": {
    "bundle_criteria": {
      "min_tokens_in_bundle": 5,
      "max_time_between_deployments": 300,
      "same_deployer": true,
      "similar_token_names": true,
      "similar_initial_supplies": true
    },
    "token_characteristics": {
      "name_length_range": [3, 8],
      "symbol_length_range": [3, 6],
      "min_initial_supply": 1000000000,
      "max_initial_supply": 1000000000000
    },
    "deployment_patterns": {
      "min_deployments_per_hour": 3,
      "max_deployments_per_hour": 20,
      "preferred_time_windows": ["09:00-17:00", "21:00-23:59"]
    }
  }
}

Social Signal Alerts

POST /webhooks/social-alerts
Content-Type: application/json

{
  "webhook_url": "https://your-app.com/webhook",
  "filters": {
    "influencers": ["elonmusk", "vitalikbuterin", "cz_binance"],
    "keywords": ["moon", "pump", "gem", "diamond hands"],
    "min_engagement": 1000,
    "min_followers": 100000,
    "time_window_hours": 24
  }
}

Social Alert Payload:

{
  "event_type": "social_signal",
  "timestamp": "2024-01-22T15:45:30Z",
  "data": {
    "platform": "twitter",
    "influencer": {
      "username": "elonmusk",
      "followers": 150000000,
      "verified": true
    },
    "post": {
      "id": "1234567890123456789",
      "text": "Just bought some PEPE coin 🐸",
      "engagement": {
        "likes": 50000,
        "retweets": 15000,
        "replies": 5000
      }
    },
    "related_tokens": [
      {
        "mint": "TokenMint1234567890abcdef1234567890abcdef123456",
        "symbol": "PEPE",
        "price_impact_1h": 25.5,
        "volume_impact_1h": 500000.00
      }
    ]
  }
}

Data Types

Transaction

interface Transaction {
  signature: string;
  slot: number;
  blockTime: number;
  fee: number;
  status: 'success' | 'failed';
  accounts: AccountInfo[];
  instructions: Instruction[];
  logs?: string[];
}

Token

interface Token {
  mint: string;
  name: string;
  symbol: string;
  decimals: number;
  supply: bigint;
  marketCap?: number;
  price?: number;
  volume24h?: number;
  holders?: number;
  creator?: string;
  createdAt?: number;
}

Wallet

interface Wallet {
  address: string;
  balance: number;
  tokenBalances: TokenBalance[];
  transactionCount: number;
  firstSeen: number;
  lastActivity: number;
  isContract: boolean;
}

TokenBalance

interface TokenBalance {
  mint: string;
  amount: bigint;
  uiAmount: number;
  decimals: number;
}

DEXSwap

interface DEXSwap {
  signature: string;
  wallet: string;
  tokenIn: string;
  tokenOut: string;
  amountIn: bigint;
  amountOut: bigint;
  priceImpact: number;
  fee: number;
  protocol: 'raydium' | 'meteora' | 'pumpfun' | 'jupiter' | 'orion';
  timestamp: number;
}

TokenCreation

interface TokenCreation {
  signature: string;
  tokenMint: string;
  tokenName: string;
  tokenSymbol: string;
  decimals: number;
  initialSupply: bigint;
  creator: string;
  timestamp: number;
  liquidity?: {
    amount: number;
    protocol: string;
    poolAddress: string;
  };
}

WebhookAlert

interface WebhookAlert {
  webhookId: string;
  webhookUrl: string;
  filters: TokenFilters;
  notificationSettings: NotificationSettings;
  status: 'active' | 'paused' | 'disabled';
  createdAt: string;
}

TokenFilters

interface TokenFilters {
  tokenNameContains?: string[];
  minInitialSupply?: bigint;
  maxInitialSupply?: bigint;
  deployerWallet?: string;
  minLiquidityUsd?: number;
  dexProtocols?: string[];
  excludeKnownDeployers?: boolean;
  bundleCriteria?: BundleCriteria;
  tokenCharacteristics?: TokenCharacteristics;
  deploymentPatterns?: DeploymentPatterns;
}

Error Codes

Code	Description	HTTP Status	User Message
`INVALID_API_KEY`	Invalid or missing API key	401	"Invalid API key"
`RATE_LIMIT_EXCEEDED`	Too many requests	429	"Rate limit exceeded. Please try again later"
`INVALID_ADDRESS`	Invalid Solana address format	400	"Invalid address format"
`TOKEN_NOT_FOUND`	Token not found in database	404	"Token not found"
`WALLET_NOT_FOUND`	Wallet not found in database	404	"Wallet not found"
`INVALID_QUERY`	Invalid SQL query	400	"Invalid query syntax"
`QUERY_TIMEOUT`	SQL query execution timeout	408	"Query timeout. Please try a simpler query"
`WEBHOOK_INVALID_URL`	Invalid webhook URL	400	"Invalid webhook URL"
`WEBHOOK_NOT_FOUND`	Webhook not found	404	"Webhook not found"
`INSUFFICIENT_PERMISSIONS`	Insufficient API permissions	403	"Insufficient permissions for this operation"
`DATABASE_ERROR`	Database operation failed	500	"Database error. Please try again"
`INDEXING_ERROR`	Data indexing error	500	"Data indexing error. Please try again"
`BLOCKCHAIN_ERROR`	Solana RPC connection error	502	"Blockchain connection error"

Rate Limits

API Endpoints

REST API: 1000 requests per hour per API key
SQL API: 100 queries per hour per API key
Webhook API: 50 webhook creations per day per API key
Analytics API: 500 requests per hour per API key

Query Limits

SQL Query: Max 10MB result size
SQL Query: Max 30 second execution time
SQL Query: Max 1000 rows per result (use LIMIT)
Transaction History: Max 10,000 transactions per request
Token Transfers: Max 50,000 transfers per request

Webhook Limits

Webhook Payload: Max 1MB per notification
Webhook Notifications: Max 100 per hour per webhook
Webhook Cooldown: Min 1 second between notifications
Webhook Retention: 7 days of failed delivery attempts

Response Headers

All API responses include these headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
X-Request-ID: req_1234567890abcdef
X-Response-Time: 0.023

Pagination

For endpoints that return lists, use these query parameters:

limit: Number of items per page (max 1000)
offset: Number of items to skip
cursor: Pagination cursor for large datasets

Example:

GET /tokens?limit=50&offset=100

Response:

{
  "data": [...],
  "pagination": {
    "limit": 50,
    "offset": 100,
    "total": 50000,
    "hasMore": true,
    "nextCursor": "eyJvZmZzZXQiOjE1MH0="
  }
}