Domain Security
Domain Security
Scores a domain or URL against HashDit threat intelligence and, optionally, reports whether a visitor opening that URL would see usable content.
POST
/
v2
/
hashdit
/
domain-security
curl --request POST \
--url https://service.hashdit.io/v2/hashdit/domain-security \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <x-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."
}
]
}
}The Domain Security endpoint does not require a chain ID as it analyzes domains and URLs rather than blockchain addresses.
Choosing a policy
liveness_policy resolves one uncertainty: our check was blocked and cannot tell whether a visitor would have been. Everything with a definite observation behind it — a 404, a sale placeholder, a domain that does not resolve — reads the same under every policy.
| Policy | On a blocked check | Use when |
|---|---|---|
lenient (default) | accessible | Warning users. A site that only blocks automation still works for the person about to click it. |
strict | not_accessible | Vetting a submitted site, where “blocked and unconfirmed” is fair grounds to hold it back. Expect some manual review: many legitimate sites block automation. |
evidence | status is null | You want http_status with no verdict and will apply your own rule. |
risk_level. A site behind bot protection returns the same http_status: 403 under both policies; the Try It examples Bot Protection (lenient) and Bot Protection (strict) show the two readings.
Latency
liveness_check: false (the default) is the fast path.
liveness_check: true adds latency. A recently checked host answers almost immediately; a host not checked before takes noticeably longer, and in the worst case returns unknown while the real answer is prepared in the background — a repeat request shortly after will have it. If that does not fit your flow, run the check on a background job and read the result on the next call.
Results are cached per host. last_scanned_at tells you how old any answer is — when the check ran, not when this response was generated. Apply your own freshness rule against it if you need one tighter than ours.
Limits
- The answer is per host, not per path. A host can be usable while one path on it is gone.
- Automation blocks are indistinguishable. We cannot tell “this site blocks all tools” from “this site blocks the addresses our checks come from”. Both read as
accessibleunderlenient. - A determined site can show us something different. A malicious site can serve a clean page to anything that looks like a security check and the real payload to actual visitors.
Errors
All errors use the standard envelope:code, status, and detail.
| Status | Cause |
|---|---|
400 | url is missing, empty, or cannot be parsed |
401 / 403 | Missing or invalid X-API-KEY |
422 | liveness_policy is not one of lenient, strict, evidence; or the body contains an unrecognized field |
429 | Rate limit exceeded |
500 | Internal error — retry, and quote request_id if it persists |
200 with the risk verdict intact and the two availability fields omitted.
Request/Response Fields
The availability check is evaluated per host, so every URL sharing a host shares one availability answer.accessible answers “would a visitor see usable content?”, so a working server is not sufficient on its own: a root path returning 404, 5xx or a for-sale placeholder reads as not_accessible.
liveness maps from status: accessible → alive, not_accessible → dead, and unknown when the result could not be determined or liveness_policy is evidence.
Absence is not a negative. If
liveness_check was true but the check could not run, liveness and liveness_detail are omitted. Treat a missing field as “no answer”, never as “not accessible”.Request fields accept both
camelCase and snake_case. See Request Field Names.Headers
Your HashDit API key
Body
application/json
Domain or URL to analyze
The domain or URL to analyze. A scheme, path and query string are accepted and normalized.
Example:
"https://pancakeswap.finance/"
When true, also report whether a visitor opening this URL would see usable content. Adds latency. A healthy server answering a request is not sufficient. Also accepts liveness_check.
How to resolve the case where the check was blocked and cannot tell whether a visitor would have been. Only meaningful when livenessCheck is true. Any other value is rejected with HTTP 422. Also accepts liveness_policy. Switching policy never changes risk_level.
lenient(default) — blocked check isaccessible. Use when warning users: a site that only blocks automation still works for the person about to click it.strict— blocked check isnot_accessible. Use when vetting a submitted site; expect some manual review.evidence— returns no verdict;statusisnulland you decide fromhttp_status
Available options:
lenient, strict, evidence Was this page helpful?