Verdetto Threat API: Python SDK

Check links, domains and crypto addresses against Verdetto's listings and other sources. The signed lists sit on your machine, so most checks send nothing.

Install

pip install verdettoqr-threat==0.1.2

First check

from verdettoqr_threat import Verdetto

v = Verdetto()
a = v.check("https://listed.test.verdettoqr.com/login")
print(a["status"])  # "listed"

No key and no setup. A test host is answered with no request; for other links, the first check downloads the lists, and a check after an hour refreshes them.

not_listed means no current listing matched, nothing more.

Live checks

v = Verdetto("vtk_open_...")  # or set VERDETTO_API_KEY
a = v.check_live("https://example.com/sign-in")

Get an Open key at verdettoqr.com/api. A timeout and retries are set for you.

Answers

Every answer is a dict with status, checked_at and matches.

is_listed(a) is true for listed and listed_by. route is local or live; past the lists' age, live_on_stale asks the API.

A local match of ours carries listing_id in place of category; with_evidence(a) adds its category and evidence.

history() answers ok with listings in place of matches; truncated when more than 60 match.

Errors

A lookup does not raise: an answer that is not a verdict carries code.

Any other code is the API's, with http_status: see Error codes.

An API code comes with its title and detail, in your language; the SDK's own codes have neither.

A failed sync keeps the lists it holds and tries again later. sync() gives its code; snapshot_stale carries it.

Retry-After:

• A 429 is not sent again. Live calls wait its Retry-After and answer rate_limited, code held, until then. With the hint batch, single calls alone wait.
• A 5xx with the API's code comes back at once, with retry_after_s.
• A network fault, or a 5xx without a code, is sent again up to max_retries times. A Retry-After up to 30 s is waited out; a longer one comes back as retry_after_s.

Methods

Options

v = Verdetto("vtk_open_...", live_on_stale=True, timeout_s=5)

language: a BCP 47 tag or a list, first preferred, sent to the API as Accept-Language: language=["de-AT", "en"].

What is sent

• The lists: GETs from the bundle host, with no key and no input: list.json, the suffix list, api/list.json and the files it names.
• check, check_many, check_domain, check_address: nothing. In a list past 50,000 of our listings, a hit reads one file named by 3 hex digits of its hash.
• With live_on_stale, a link or domain past the lists' age goes to the API.
• record, with_evidence: the record index once, then the record's file, from the bundle host.
• check_live, check_live_many, history: a POST to the API with the input and the key. An input it would refuse is not sent.
• Every request: User-Agent: verdettoqr-threat-python/0.1.2. The API's also: Content-Type: application/json, Authorization: Bearer <key>, and Accept-Language when language is set.
• Your HTTP stack adds its own, such as Host.

Test hosts

listed.test.verdettoqr.com answers listed. clear.test.verdettoqr.com answers not_listed.

Runs on

Python 3.11 and up. One client may be shared across threads. No dependencies; pip install verdettoqr-threat[fast] adds cryptography for a faster signature check.

License

Code: MIT. Our listings: CC0 1.0. Other sources: their own terms, in the lists' manifest.