Token Analyzer API

Blokiments API Integration for the Token Analyzer Engine. Experience one of the most powerful token analysis APIs available.

Please note that the Token Analyzer is only accessible to whitelisted users. To request access, contact us at [email protected] or in the Telegram group.

Overview

Blokiments Token Analyzer is a powerful tool that scans and aggregates token data in real time, providing clear, user-friendly warnings and in-depth metrics for advanced analysis. The same analytics engine that powers our platform is now available via API for seamless integration. Key Advantages:

  • Real-Time Intelligence: Our risk engine continuously processes on-chain and off-chain data, ensuring every report and warning reflects the most up-to-date information available at the time of the call.

  • Plain-English, LLM-Ready Alerts: We deliver clear, structured warnings that are easy for both humans and language models to understand. Perfect for use as contextual input in AI systems, no jargon, just actionable insights.

  • All-in-One Coverage: Risk assessments, trading data, on-chain movements, and social signals are all unified in a single product. There’s no need to juggle multiple tools or platforms.

  • One-Click Simplicity: Whether you’re a retail trader or an enterprise partner, powerful risk insights are available instantly, with no steep learning curve, no technical complexity.

  • Broad Multi-Chain Support: Currently live on Solana, Ethereum, Base, BSC, Arbitrum, and Tron, the Token Analyzer covers the ecosystems where scams are most active, with more chains coming soon.

  • Built on Real Scam Data: Our detection models leverage advanced pattern recognition and a proprietary database of thousands of confirmed rug pulls and scams, enabling faster and smarter detection than generic analytics tools.

Report types

The API provides two report types to suit different use cases. Our goal is to deliver accurate results as quickly as possible.

Note: Many coordinated or “bundled” scams cannot be reliably detected by the LITE report alone. The FULL report analyzes top holders with advanced pattern detection and metrics to uncover sophisticated fraud, which takes more time but yields stronger results.

For detailed field definitions and response models, see the API documentation.

API endpoints

A quick overview of the API endpoints for seamless integration into your product or bot. The Token Analyzer API consists of three main endpoints:

  • Request a report: POST /request-report

    • Submit the network and token address you want analyzed, and specify whether you need a lite or full report.

    • The system queues and analyzes the requested token and report type.

    • Credits are charged for every new report generation. If a report is already being processed (status: pending), no credits are charged for re-calling this endpoint.

  • Fetch the report:

    • Fetch the lite report: GET /lite-report

      • Use this endpoint if you requested a lite report.

    • Fetch the full report: GET /full-report

      • Use this endpoint if you requested a full report.

When fetching a report:

  • If the report is still being generated, the API will return a pending status.

  • You can poll the endpoint periodically (with small delays) until the status changes to completed.

  • Once completed, the full analysis data will be available.

Credits are never charged for fetching reports, only for generating new ones via /request-report.

Typical integration pattern

Follow these steps to efficiently integrate the Blokiments Token Analyzer API into your product or bot:

  1. Validate inputs: Before making any API calls, verify that the token address matches the selected network format. The API also performs this validation and will reject invalid combinations, but checking client-side helps prevent unnecessary calls.

  2. Check for existing reports (optional): Try fetching the desired report using the appropriate GET endpoint (/lite-report or /full-report). If a report already exists and its last refresh timestamp is recent enough for your use case, you can safely reuse it without spending credits.

  3. Request a new analysis (if needed):

    1. If no report exists, or you require a refreshed version, initiate a new analysis with: POST /request-report

    2. Provide the following parameters:

      1. network – one of the supported chains

      2. token_address – the token’s smart contract address

      3. report_type – lite or full

    3. If you already know you’ll need detailed insights, request the full report directly. If you only need quick, high-level checks or aren’t sure yet, start with the lite version - it covers the most common risk indicators and basic scam detection.

    4. You’ll receive a confirmation message such as “Report requested successfully.”

  4. Poll for results

    1. Once the request is submitted, periodically check the corresponding GET endpoint until the report is ready:

      1. Lite report: GET /lite-report: poll every 2 seconds

      2. Full report: GET /full-report: poll every 5 seconds

    2. If the API returns a pending status, wait briefly before retrying. When the status changes to completed, the full report data will be available.

  5. Use the results

    1. Once the report is completed, you can access all relevant metrics and risk insights for your product, dashboard, or alert system.

Practical step-by-step example

Let’s walk through a practical example of how to use the API and explain the most common fields. If you prefer to start building right away, you can use the official API documentation as a reference.

In this example, we’ll demonstrate how you can integrate the Token Analyzer into a bot.

1

Check for existing reports

Suppose we want to analyze a specific token. Before requesting a new analysis, we can check whether a lite report for that token already exists. If it does, we verify when the report was last generated and decide whether it’s still recent enough for our use case. By doing this, we can reuse valid cached data and avoid spending additional credits unnecessarily.

import requests

BASE_API_URL = "https://api.blokiments.com/api/v1/token-analyzer"
BLOKIMENTS_API_KEY = "YOUR_API_KEY"

def get_lite_token_report(network: str, token_address: str) -> dict | None:
    """Fetch the lite token analyzer report for a given token address on a specified network."""
    url = f"{BASE_API_URL}/lite-report"
    params = {"network": network, "token_address": token_address}
    headers = {"X-API-Key": BLOKIMENTS_API_KEY}
    response = requests.get(url, params=params, headers=headers)
    if response.status_code != 200:
        print(f"Error fetching report: {response.status_code} - {response.text}")
        return None
    return response.json()

if __name__ == "__main__":
    data = get_lite_token_report("ethereum", "0x07197f78c3f2d0a4a199dbc442f2187d416e3e88")
    if data:
        report_status = data.get("report_status")
        report_creation_timestamp = data.get("report_creation_timestamp")
        print(f"Report Status: {report_status}")
        print(f"Report Creation Timestamp: {report_creation_timestamp}")
        print(data)

When using the GET endpoints (/lite-report and /full-report) to retrieve reports, your application should properly handle the following status codes and key response fields to ensure reliable behavior.

  • 422 Unprocessable Entity:

    • Returned when the request contains an invalid or malformed network , or token_address field.

    • 👉 Tip: Always validate the token address and network on the client side before sending the request.

  • 401 Unauthorized: Indicates that the API key is missing, invalid, or does not have permission to access the endpoint.

    • 👉 Fix: Check that your API key is valid, active, and correctly included in the request header. Contact [email protected] to get an API key.

  • 400 Bad Request: Occurs when the address and network pass basic validation but are logically incompatible. For example, querying an ERC-20 token address using the Solana network configuration.

  • 404 Not found: Means the report for that token has never been generated. This doesn’t mean the token itself doesn’t exist, only that no analysis report is available yet. You should call POST /request-report to generate it. Example response:

{"detail":"Token analyzer lite report not generated yet. Please request a report first."}

  • 200 Success: Indicates that a report was found and returned successfully. In this case, your application should check additional response fields (described below) to determine the current report status (pending, completed, etc.) before using the data.

2

Validate the report fields

  1. Understanding the report_status Field: Every successful GET response (200 OK) includes a report_status field that indicates the current state of the analysis. This field can contain one of the following four statuses:

    1. not_found: The analyzer couldn’t locate the provided token.

      1. This may happen if:

        1. The token doesn’t have any active DEX pools, or

        2. The provided address doesn’t correspond to a valid token contract.

      2. Additional details are available in the report_status_details field, which explains why the token wasn’t found.

    2. error: An unexpected issue occurred during the analysis, and the report couldn’t be generated. More information about the failure is provided in the report_status_details field.

    3. pending: The token is currently being analyzed by the engine. In this case, you should call the same GET endpoint again after a few seconds to check whether the report is ready.

    4. completed: The report has been successfully generated, and the full data is now available. For additional insights or potential caveats, refer to the report_status_warnings field.

  2. About report_status_warnings: This field provides warnings about any conditions or issues that may have affected the data collection or analysis. While the system aims to deliver the most accurate and reliable results possible, certain cases—such as missing trading pools or partial data retrieval—may trigger warnings to inform you that some metrics could be incomplete. (These warnings typically relate to trading or liquidity data.)

  3. About report_creation_timestamp : The report_creation_timestamp field shows when the report was generated. All metrics, reviews, and insights are based on data captured at that specific moment in time. Use this timestamp to determine the report’s freshness and decide whether a new analysis is needed.

3

Request a new lite analysis

If a report is not found or is outdated, you’ll need to refresh the token data by making a POST /request-report call. After submitting the request, continue polling the corresponding GET endpoint until the report is ready. We recommend using a 2-second polling interval for lite reports to balance responsiveness and efficiency. Here’s an example code snippet to illustrate the process:

import time

import requests

POLLING_INTERVAL = 2  # seconds
BREAK_LOOP_ON_REPORT_STATUS = {"not_found", "error", "completed"}
BASE_API_URL = "https://api.blokiments.com/api/v1/token-analyzer"
BLOKIMENTS_API_KEY = "YOUR_API_KEY"


def request_new_report(network: str, token_address: str, report_type: str) -> dict | None:
    """Request a new token analyzer report."""
    url = f"{BASE_API_URL}/request-report"
    headers = {"X-API-Key": BLOKIMENTS_API_KEY}
    data = {"network": network, "token_address": token_address, "report_type": report_type}
    response = requests.post(url, headers=headers, json=data)
    if response.status_code != 200:
        print(f"Error requesting report: {response.status_code} - {response.text}")
        return None
    return response.json()


def pool_report_till_ready(network: str, token_address: str, report_type: str) -> dict | None:
    """Poll the API until the report is ready."""
    while True:
        url = f"{BASE_API_URL}/{report_type}-report"
        headers = {"X-API-Key": BLOKIMENTS_API_KEY}
        params = {"network": network, "token_address": token_address}
        response = requests.get(url, headers=headers, params=params)
        if response.status_code == 200:
            report = response.json()
            if report.get("report_status") in BREAK_LOOP_ON_REPORT_STATUS:
                return report
            print("Report not ready yet, polling again...")
            time.sleep(POLLING_INTERVAL)
        elif response.status_code == 404:
            print("Report not ready yet, polling again...")
            time.sleep(POLLING_INTERVAL)
        else:
            print(f"Error fetching report: {response.status_code} - {response.text}")
            return None


if __name__ == "__main__":
    data = request_new_report("ethereum", "0xb7c5464f000e019a106361da8e7652087cde44ff", "lite")
    if data:
        print("Report requested successfully.")
        data = pool_report_till_ready("ethereum", "0xb7c5464f000e019a106361da8e7652087cde44ff", "lite")
        print("Final Report Data:", data)

After you successfully submit a POST /request-report call, the report job is created in the system, but it may take a few seconds before the analyzer transitions into the pending state. During this short initialization period, calling the GET endpoint (/lite-report or /full-report) will return a 404 Not Found response. This does not mean the request failed or that the token doesn’t exist; it simply means the report is not yet available in the database. It’s important to wait and keep polling on a 404 status until the report enters the database. Avoid sending multiple POST requests during this period — doing so will trigger unnecessary credit charges. Instead, poll the GET endpoint every few seconds (for example, every 2 seconds for lite reports) until a 200 OK response is returned.

4

Check the requested lite report

Use the same validation steps described earlier in step 2 when handling the Lite report response. In addition, the Lite report includes a helpful field called token_risk_level, which provides an at-a-glance assessment of the token’s overall risk. This can guide you in deciding whether a full report is necessary for a deeper review.

  • low - Indicates a well-established token with multiple CEX listings, healthy liquidity, a strong holder base, and a solid market cap.

  • neutral - No specific risks detected; the token appears stable based on available data.

  • high - Multiple red flags or critical issues were found, or the token is very new - both factors increase the risk level.

  • need_more_data - The system couldn’t confidently assess the token’s risk using the Lite data alone. A Full report is recommended for a more accurate evaluation.

Note: The token_risk_level is not a price prediction or investment signal; it is a risk indicator, designed to help identify potentially unsafe or suspicious tokens.

Lite Report Result Fields

  • token_reviews — Contains a summary of key findings and risk messages in plain language, each with an associated severity level (info, warning, or critical).

  • token_metadata — An object containing all the metrics generated in the Lite report (see the API documentation for a complete field reference).

If the Lite report indicates elevated risk or insufficient data (need_more_data), you can proceed to generate a Full report for a deeper and more comprehensive analysis.

5

Request a full analysis if needed

We can follow the same logic used for the Lite report request, simply change the report_type to full and increase the polling interval to 5 seconds.

Below is the complete code example demonstrating the full workflow.

import time

import requests

POLLING_INTERVAL = 5  # seconds
BREAK_LOOP_ON_REPORT_STATUS = {"not_found", "error", "completed"}
BASE_API_URL = "https://api.blokiments.com/api/v1/token-analyzer"
BLOKIMENTS_API_KEY = "YOUR_API_KEY"


def request_new_report(network: str, token_address: str, report_type: str) -> dict | None:
    """Request a new token analyzer report."""
    url = f"{BASE_API_URL}/request-report"
    headers = {"X-API-Key": BLOKIMENTS_API_KEY}
    data = {"network": network, "token_address": token_address, "report_type": report_type}
    response = requests.post(url, headers=headers, json=data)
    if response.status_code != 200:
        print(f"Error requesting report: {response.status_code} - {response.text}")
        return None
    return response.json()


def pool_report_till_ready(network: str, token_address: str, report_type: str) -> dict | None:
    """Poll the API until the report is ready."""
    while True:
        url = f"{BASE_API_URL}/{report_type}-report"
        headers = {"X-API-Key": BLOKIMENTS_API_KEY}
        params = {"network": network, "token_address": token_address}
        response = requests.get(url, headers=headers, params=params)
        if response.status_code == 200:
            report = response.json()
            if report.get("report_status") in BREAK_LOOP_ON_REPORT_STATUS:
                return report
            print("Report not ready yet, polling again...")
            time.sleep(POLLING_INTERVAL)
        elif response.status_code == 404:
            print("Report not ready yet, polling again...")
            time.sleep(POLLING_INTERVAL)
        else:
            print(f"Error fetching report: {response.status_code} - {response.text}")
            return None


if __name__ == "__main__":
    data = request_new_report("ethereum", "0xb7c5464f000e019a106361da8e7652087cde44ff", "full")
    if data:
        print("Report requested successfully.")
        data = pool_report_till_ready("ethereum", "0xb7c5464f000e019a106361da8e7652087cde44ff", "full")
        print("Final Report Data:", data)
6

Retrieving the Full Report Results

The Full report response follows the same structure and behavior as the Lite report, with two key differences:

  • token_risk_level — This field is not included in the Full report. To assess the token’s overall risk, refer to the detailed insights provided in the token_reviews field.

  • token_advanced_metadata — This field is available only in the Full report and contains additional metrics generated by the advanced analysis modules.

With these differences in mind, you can interpret the Full report in the same way as the Lite report. This concludes our example.

Check API usage

You can monitor your credit consumption using the /usage endpoint. This endpoint returns the following information:

  • Total credit limit

  • Monthly credit limit

  • Used credits

  • Available credits

If any of the limits are shown as none, it means no restriction is applied for that specific interval. Credit limits are configured by the Blokiments team during API activation based on your subscription plan and expected usage.

Expected result:

{
  "enabled": true,
  "last_activity_timestamp": "2025-11-01T11:58:47.429025Z",
  "total_credits_limit": 10000,
  "total_used_credits": 0,
  "total_available_credits": 10000,
  "monthly_credits_limit": 0,
  "monthly_used_credits": 0,
  "monthly_available_credits": 10000
}

FAQ

Why can’t I find any data about the token?

For the API to return data and successfully generate a report, the token must have at least one active liquidity pool. If no liquidity pool exists for the token, the analyzer cannot gather the necessary on-chain data, and the token address will be marked as not_found.

PreviousGoogle Sheets IntegrationNextGet historical price data

Last updated

Was this helpful?