API Documentation

Complete reference for the Honeypot Detection API

Quick Start

Get your API key from the dashboard and start making requests immediately.

Authentication

All API requests require an API key to be included in the request header.

Header

X-API-Key: YOUR_API_KEY

API Endpoints

GET

/api/scan/

Analyze a token and return pairs, liquidity, gas usage, and potential buy/sell limits and taxes.

Query Parameters

Name Type Required Description
address string Yes Token contract address or pair/pool address
chain_id string Yes Network ID: Ethereum (1), BSC (56), Base (8453)

Sample Response

{
  "data": [
    {
      "name": "Dai Stablecoin",                                  // token name
      "total_supply": 3.3424822072689636e+27,                     // total supply (wei)
      "decimals": 18,                                            // token decimals
      "symbol": "DAI",
      "max_buy_amount_in_wei": 2.292984953673296e+21,            // max buy per tx (wei) found by simulation
      "max_sell_amount_in_token": 2.6761641303094227e+24,       // max sell per tx (token units) found by simulation
      "buy_limit_found": false,                                  // whether a buy limit was detected
      "sell_limit_found": false,                                 // whether a sell limit was detected
      "pair": {
        "exchange": "Uniswap V2",                              // DEX where the pair was found
        "liquidity": 2292.984953673,                             // liquidity amount denominated in the OTHER token shown below
                                                                // (units depend on other_token_in_the_pair — common values: USDT, BUSD, WETH, WBNB)
        "address": "0xa478c2975ab1ea89e8196811f51a7b7ade33eb11", // pair/pool contract address
        "other_token_in_the_pair": "WETH"                      // the other token in the pair; liquidity above is in this token's units (e.g. USDT/BUSD/WETH/WBNB)
      },
      "buy_tax": 0,                                               // buy tax percentage (if detectable)
      "sell_tax": 0,                                              // sell tax percentage (if detectable)
      "buy_gas_used": 120062,                                     // gas estimate for buy path
      "sell_gas_used": 111287                                     // gas estimate for sell path
    }
  ]
}
GET

/api/holders/

Retrieve detailed information about token holders, including balances, percentages, and flags.

Query Parameters

Name Type Required Description
address string Yes Token contract address
chain_id string Yes Network ID: Ethereum (1), BSC (56), Base (8453)
top_holders JSON string No Optional. Chrome extension parameter (not required for API calls). Max 100 entries

Note: top_holders is an optional Chrome-extension-specific parameter and is unnecessary for normal API usage.

Note: holders_analyzed indicates how many of the top holders were analyzed (up to 100). It is NOT the total holder count.

Sample Response

{
  "data": {
    "holders_analyzed": 99,            // number of top holders actually analyzed (up to 100). NOT the total holder count
    "siphoned": 0,              // total siphoned amount (token base units) from analyzed holders
    "can_not_sell": 5,          // number of holders that cannot sell
    "holders": [
      {
        "wallet": "0x1a9C8182C09F50C8318d769245beA52c32BE35BC", // holder wallet address
        "balance": 3.6966947229e+26,                             // raw balance (token base units) as a number
        "is_contract": true,                                    // whether the holder is a contract
        "percentage": 36.97,                                    // % of total supply
        "can_sell": true,                                       // whether this holder can currently sell
        "is_siphoned": false                                    // whether tokens from this holder appear siphoned (rare false positives possible)
      },
      {
        "wallet": "0xF977814e90dA44bFA03b6295A0616a897441aceC",
        "balance": 4.14664785921e+25,
        "is_contract": false,
        "percentage": 4.15,
        "can_sell": true,
        "is_siphoned": false
      }
    ]
  }
}
GET

/api/contract/

Fetch verification status, proxy status, creator and source code (if available) for a smart contract.

Query Parameters

Name Type Required Description
address string Yes Contract address to inspect
chain_id string Yes Network ID: Ethereum (1), BSC (56), Base (8453)

Sample Response

{
  "data": {
    "verified": true,                         // whether the contract source is verified on the explorer
    "is_proxy": false,                        // whether this contract is a proxy
    "contract_creator": "0x1234...",       // address that deployed the contract
    "block_number": 12345678,                 // block where the contract was created
    "time_stamp": "1712466666",   // creation timestamp
    "source_code": "// SPDX-License-Identifier: MIT\\npragma solidity ^0.8.0;...", // source code when available
    "compiler_version": "v0.8.17+commit.8df45f5f"
  }
}

Rate Limits

Rate limits vary by subscription plan. Check your dashboard for current limits.

Error Codes

Code Description
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
403 Forbidden - No active subscription
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error