Domain Security - HashDit API Documentation

Synchronous endpoint Assess the threat-intelligence risk of a domain or URL. Optionally add a liveness check that asks whether a visitor would see usable content.

This endpoint analyzes domains and URLs, so it does not accept chain_id.

HashDit-owned request fields are documented in snake_case. Equivalent camelCase input remains accepted for compatibility.

Quick Start

The minimum request sends only url.

curl --request POST \
  --url https://service.hashdit.io/v2/hashdit/domain-security \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "url": "https://pancakeswap.finance/"
  }'

{
  "code": "0",
  "status": "ok",
  "data": {
    "request_id": "85cb060e-75cf-4d75-887f-c23f2fc45106",
    "has_result": true,
    "polling_interval": 0,
    "risk_level": 0,
    "risk_name": "Trusted",
    "risk_detail": [
      {
        "name": "is_in_wlist",
        "value": "The dApp is relatively safe based on the threat intelligence."
      }
    ]
  }
}

Request Fields

string

required

Your HashDit API key. Missing keys return HTTP 401; a legacy gateway can return 403 for a rejected key. Keep the key on a trusted server.

string

required

Domain or URL to analyze. A scheme, path, and query string are accepted and normalized.

boolean

default:"false"

Add a usable-content availability check. This increases latency.

string

default:"lenient"

How to interpret a check blocked by bot protection: lenient, strict, or evidence.

Response Fields

string

required

API result code. "0" indicates success; non-zero values indicate an error.

string

required

Request status. A successful completed response returns "ok".

string

Unique request identifier to include in support requests.

boolean

Whether a domain risk result was immediately available.

number

Seconds to wait before retrying when has_result is false; otherwise 0.

integer

Numeric threat-intelligence risk level.

string

Human-readable risk label.

object[]

Triggered threat-intelligence indicators. Use each item’s name for application logic.

Show Risk detail fields

string

Stable threat-intelligence category identifier.

string

Human-readable explanation of the matched indicator.

string

alive, dead, or unknown when liveness_check was requested and a result is available.

object

Availability status, policy, observed HTTP status, and scan timestamp.

Show Liveness detail fields

string | null

accessible, not_accessible, or null when the selected policy preserves uncertainty.

string

Applied policy: lenient, strict, or evidence.

integer | null

Observed HTTP status, or null when no HTTP response was reached.

string | null

ISO 8601 timestamp of the availability check, or null when unavailable.

The availability result is per host, so URLs sharing a host share one availability answer. accessible asks whether a visitor would see usable content; a working server alone is not sufficient. liveness maps from liveness_detail.status: accessible → alive, not_accessible → dead, and unknown when no determination is available or the policy is evidence.

Absence is not negative. If the check could not run, liveness and liveness_detail are omitted. Treat a missing field as “no answer”, never as “not accessible”.

How to Use the Response

Use risk_level and risk_name for the top-level domain decision.
Use risk_detail[].name for application logic and value for user-facing context.
If you request liveness, treat it as an availability signal independent from risk_level.
A low risk result is a point-in-time threat-intelligence assessment, not a guarantee that every path or future page is safe.

Risk Level Reference

`risk_level`	`risk_name`	Meaning
`-1`	`Unknown`	No verdict could be formed; do not treat this as safe.
`0`	`Trusted`	The domain is affirmatively trusted by HashDit threat intelligence.
`1`	`No Obvious Risk`	No configured signal produced a stronger verdict.
`2`	`Low Risk`	Low-severity risk signals were detected.
`3`	`Medium Risk`	Material risk signals require user attention.
`4`	`High Risk`	Strong risk signals were detected.
`5`	`Significant Risk`	The highest-severity risk signals were detected.

Choosing a Liveness Policy

liveness_policy resolves one uncertainty: the check was blocked and cannot tell whether a visitor would have been. Definite observations such as 404, a sale placeholder, or a domain that does not resolve are read the same under every policy.

Policy	On a blocked check	Use when
`lenient` (default)	`accessible`	Warning users. A site that only blocks automation can still work for a person.
`strict`	`not_accessible`	Vetting submitted sites. Expect some legitimate sites to require manual review.
`evidence`	`status` is `null`	You want `http_status` without a HashDit availability verdict.

Changing this policy never changes risk_level. A bot-protected site can return the same http_status: 403 under both policies while the availability interpretation differs.

Latency and Cache Age

liveness_check: false is the fast path. A liveness check adds latency; a recently checked host normally answers quickly, while a new host can return unknown as the result is prepared in the background. A later request can then use the cached result. Results are cached per host. last_scanned_at describes when the availability check ran, not when the current API response was generated. Apply your own freshness threshold when needed.

Limits

The availability answer is per host, not per path.
A block against automated checks cannot prove the site is blocked for a human visitor.
A determined site can serve different content to security infrastructure and users.

Availability is a useful signal, but should not be the only input to a security decision.

Errors and Retry Guidance

All errors use the standard code, status, and detail envelope.

HTTP	Cause	Client action
`400`	`url` is missing, empty, or cannot be parsed	Correct the request; do not retry unchanged.
`401` / `403`	Missing or invalid API key	Fix authentication.
`422`	Invalid `liveness_policy` or an unrecognized field	Correct the request schema.
`429`	Rate limit exceeded	Retry with exponential backoff and jitter.
`500`	Internal error	Retry a bounded number of times; include `request_id` in support requests.

A liveness-check failure does not fail the risk request. The API can return HTTP 200 with the risk verdict intact and omit the two liveness fields.

​Quick Start

​Request Fields

​Response Fields

​How to Use the Response

​Risk Level Reference

​Choosing a Liveness Policy

​Latency and Cache Age

​Limits

​Errors and Retry Guidance

Quick Start

Request Fields

Response Fields

How to Use the Response

Risk Level Reference

Choosing a Liveness Policy

Latency and Cache Age

Limits

Errors and Retry Guidance