> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Screen Wallet PDF
> Stateless companion to `POST /v3/wallet-screening/`: repost the exact JSON body that endpoint returned — including the `report_signature` it added — and get back a Didit-branded PDF of the same result. No provider is called and nothing is billed or persisted; this only re-renders a result Didit already produced. The signature ties the PDF to an unmodified result: editing `risk_score`, `severity`, `sanctions_hit`, or any other signed field before reposting fails with `400`.
export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
const [copied, setCopied] = React.useState(false);
const handleCopy = e => {
e.stopPropagation();
if (!prompt) return;
navigator.clipboard.writeText(prompt.trim()).then(() => {
setCopied(true);
setTimeout(() => setCopied(false), 2000);
});
};
const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
return
{}
{title}
{}
{prompt.trim()}
{}
Paste into
{agents.map(name => {name})}
;
};
.pdf
Failure modes:
- 400 - the body is not a JSON object matching the wallet-screening result shape, or report_signature is missing or invalid (the result was edited, truncated, or hand-built instead of reposted verbatim).
- 401 - missing or invalid x-api-key.
For the underlying screening call, see /management-api/transactions/screen-wallet.`}
/>
## Why it's stateless
Standalone wallet screening writes nothing to the transactions table, so there is no stored record for this endpoint to render from. Instead, you repost the exact JSON that `POST /v3/wallet-screening/` already gave you, and Didit renders that payload into a PDF without calling a provider again.
## The `report_signature` field
Every `POST /v3/wallet-screening/` response now includes a `report_signature` field — an opaque signature scoped to your application. This endpoint verifies it before rendering, so a caller can't edit `risk_score`, `severity`, `sanctions_hit`, or any other field and get a clean-looking Didit-branded PDF for a result Didit never produced.
Always repost the full response body **unmodified**, including `report_signature`. Reordering keys is fine; changing any signed value is not.
```bash theme={null}
# 1. Run the screening and save the full response
RESULT=$(curl -s -X POST https://verification.didit.me/v3/wallet-screening/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"wallet_address": "0x28c6c06298d514db089934071355e5743bf21d60", "blockchain": "ETH"}')
# 2. Repost it verbatim to render the PDF
curl -X POST https://verification.didit.me/v3/wallet-screening/pdf/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "$RESULT" \
-o wallet_screening_report.pdf
```
## Billing
No provider call is made and nothing is billed — this only re-renders a result you already paid for when you called `POST /v3/wallet-screening/`.
## Errors
| Status | Meaning |
| - | - |
| `400` | Body is not a JSON object matching the wallet-screening result shape, or `report_signature` is missing or does not match the reposted fields. |
| `401` | Missing or invalid `x-api-key`. |
## Next steps
Run the underlying on-demand wallet screening and get the JSON result to repost here.
Overview of the standalone wallet-screening endpoint and result model.
## OpenAPI
````yaml POST /v3/wallet-screening/pdf/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/wallet-screening/pdf/:
post:
tags:
- Transactions
summary: Render a wallet-screening result as a PDF
description: >-
Stateless companion to `POST /v3/wallet-screening/`: repost the exact
JSON body that endpoint returned — including the `report_signature` it
added — and get back a Didit-branded PDF of the same result. No provider
is called and nothing is billed or persisted; this only re-renders a
result Didit already produced. The signature ties the PDF to an
unmodified result: editing `risk_score`, `severity`, `sanctions_hit`, or
any other signed field before reposting fails with `400`.
operationId: screenWalletPdf
requestBody:
required: true
description: >-
The unmodified JSON object returned by `POST /v3/wallet-screening/`,
including `report_signature`.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/WalletScreeningResult'
required:
- report_signature
description: >-
Same shape as the `POST /v3/wallet-screening/` response — pass
that response body back verbatim, including `report_signature`.
responses:
'200':
description: >-
The rendered PDF document, returned directly as binary
`application/pdf` — there is no JSON wrapper.
headers:
Content-Disposition:
description: >-
`attachment; filename=wallet_screening_{address}.pdf`, derived
from the `wallet_address` (or `transaction_hash`) in the
reposted result.
schema:
type: string
example: >-
attachment;
filename=wallet_screening_0x28c6c06298d514db0899.pdf
content:
application/pdf:
schema:
type: string
format: binary
'400':
description: >-
The body is not a JSON object matching the wallet-screening result
shape, or `report_signature` is missing or does not match the
reposted fields (edited or truncated before repost).
content:
application/json:
schema:
type: object
examples:
Not an object:
value:
non_field_errors:
- >-
Expected a JSON object matching a wallet-screening
result.
Missing or invalid signature:
value:
report_signature:
- >-
This wallet-screening result is missing or fails its
report signature - repost the exact JSON returned by the
wallet-screening endpoint, unmodified.
'401':
description: Missing or invalid `x-api-key`.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
# $RESULT is the saved JSON body from POST /v3/wallet-screening/
curl -X POST
'https://verification.didit.me/v3/wallet-screening/pdf/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d "$RESULT" \
-o wallet_screening_report.pdf
- lang: python
label: Python
source: >-
import requests
# `result` is the dict returned by POST /v3/wallet-screening/,
unmodified
response = requests.post(
'https://verification.didit.me/v3/wallet-screening/pdf/',
headers={'x-api-key': 'YOUR_API_KEY'},
json=result,
timeout=30,
)
response.raise_for_status()
with open('wallet_screening_report.pdf', 'wb') as fh:
fh.write(response.content)
- lang: javascript
label: JavaScript
source: >-
// `result` is the object returned by POST /v3/wallet-screening/,
unmodified
const response = await
fetch('https://verification.didit.me/v3/wallet-screening/pdf/', {
method: 'POST',
headers: {
'x-api-key': process.env.DIDIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(result),
});
if (!response.ok) throw new Error(`PDF generation failed: HTTP
${response.status}`);
const pdfBuffer = Buffer.from(await response.arrayBuffer());
components:
schemas:
WalletScreeningResult:
type: object
properties:
provider:
type: string
description: >-
Provider that performed the screening (e.g. `merklescience`,
`crystal`).
screening_type:
type: string
enum:
- WALLET_SCREENING
description: Always `WALLET_SCREENING` for this endpoint.
risk_score:
type: integer
description: >-
Normalised 0-100 risk score. Higher means greater exposure to risky
entities. Merkle Science grades an address 0-5, which maps to 0, 15,
35, 55, 75 or 95.
severity:
type: string
enum:
- UNKNOWN
- LOW
- MEDIUM
- HIGH
- CRITICAL
description: >-
Risk bucket derived from `risk_score`: `0-9` UNKNOWN, `10-39` LOW,
`40-69` MEDIUM, `70-89` HIGH, `90-100` CRITICAL. `UNKNOWN` is the
lowest band, not a separate no-data state: `risk_score` 0 (the
common clean-address case) means no adverse assessment, while a
non-zero score in the 1-9 range is a real but sub-LOW signal - read
the `risk_score`, not just the band. Never treat `UNKNOWN` as an
affirmative low-risk or clear rating; do not display it as a pass.
status:
type: string
enum:
- SCREENED
- PENDING
- ERROR
description: Screening outcome status.
summary:
type: string
description: Human-readable summary of the screening result.
wallet_address:
type: string
description: The screened address, echoed back.
transaction_hash:
type: string
nullable: true
description: >-
Transaction screening field, shared with the result shape. Always
`null` on a wallet screening result.
blockchain:
type: string
description: The blockchain that was screened.
block_timestamp:
type: string
nullable: true
description: >-
Transaction screening field, shared with the result shape. Always
`null` on a wallet screening result.
total_value_usd:
type: number
nullable: true
description: >-
Transaction screening field, shared with the result shape. Always
`null` on a wallet screening result.
fee_usd:
type: number
nullable: true
description: >-
Transaction screening field, shared with the result shape. Always
`null` on a wallet screening result.
sender_rows:
type: array
items:
type: object
description: >-
Transaction screening field, shared with the result shape. Always
empty on a wallet screening result.
receiver_rows:
type: array
items:
type: object
description: >-
Transaction screening field, shared with the result shape. Always
empty on a wallet screening result.
transaction_flows:
type: array
items:
type: object
description: >-
Transaction screening field, shared with the result shape. Always
empty on a wallet screening result.
transaction_flows_status:
type: string
nullable: true
description: >-
Transaction screening field, shared with the result shape. Always
`null` on a wallet screening result.
transaction_flows_error:
type: string
nullable: true
description: >-
Transaction screening field, shared with the result shape. Always
`null` on a wallet screening result.
source_of_funds:
type: array
description: >-
Where the address received funds from, attributed by entity. Each
entry is an exposure breakdown.
items:
type: object
properties:
category:
type: string
description: >-
Normalised risk category, e.g. `exchange_licensed`, `dex`,
`defi`, `payment_processor`, `mixer`, `darknet_market`,
`sanctioned`, `stolen_funds`, `high_risk_exchange`.
percentage:
type: number
description: Share of the direction's total exposure, 0-100.
amount_usd:
type: number
nullable: true
description: USD value attributed to this entity.
entity_name:
type: string
nullable: true
description: >-
Name of the attributed entity, for example an exchange, a
mixer or a sanctioned group.
entity_type:
type: string
nullable: true
description: >-
Provider entity type (e.g. `Exchange`, `DeFi`, `Sanctions`,
`Theft`).
entity_subtype:
type: string
nullable: true
description: >-
More granular subtype (e.g. `Mandatory KYC and AML`, `OFAC`,
`Yield Aggregator`).
hops:
type: integer
nullable: true
description: >-
Number of hops to the entity (1 for a direct counterparty),
when the provider reports one. Always `null` for Merkle
Science, which reports only whether exposure is direct or
indirect: use `exposure_type`.
description:
type: string
nullable: true
description: >-
`entity_type / entity_subtype`, as the provider labels the
entity.
is_direct:
type: boolean
description: True when `exposure_type` is `direct`.
exposure_direction:
type: string
enum:
- incoming
- outgoing
- connected
description: >-
Whether the funds came from (`incoming`) or went to
(`outgoing`) this entity.
exposure_type:
type: string
enum:
- direct
- indirect
description: '`direct` (1 hop) or `indirect` (multi-hop) exposure.'
provider_entity_id:
type: string
nullable: true
description: The provider's own identifier for the entity.
provider_entity_type_id:
type: string
nullable: true
description: The provider's own identifier for `entity_type`.
provider_entity_subtype_id:
type: string
nullable: true
description: The provider's own identifier for `entity_subtype`.
country:
type: string
nullable: true
description: >-
Primary ISO 3166-1 alpha-2 country of the entity. Empty or
`null` when the provider does not know it.
raw_amount:
type: number
nullable: true
description: Amount in the asset's own unit, when the provider reports it.
raw_currency:
type: string
nullable: true
description: Unit of `raw_amount`, when the provider reports it.
destination_of_funds:
type: array
description: >-
Where the address sent funds to, attributed by entity. Same item
shape as `source_of_funds` with `exposure_direction` = `outgoing`.
items:
type: object
properties:
category:
type: string
description: >-
Normalised risk category, e.g. `exchange_licensed`, `dex`,
`defi`, `payment_processor`, `mixer`, `darknet_market`,
`sanctioned`, `stolen_funds`, `high_risk_exchange`.
percentage:
type: number
description: Share of the direction's total exposure, 0-100.
amount_usd:
type: number
nullable: true
description: USD value attributed to this entity.
entity_name:
type: string
nullable: true
description: >-
Name of the attributed entity, for example an exchange, a
mixer or a sanctioned group.
entity_type:
type: string
nullable: true
description: >-
Provider entity type (e.g. `Exchange`, `DeFi`, `Sanctions`,
`Theft`).
entity_subtype:
type: string
nullable: true
description: >-
More granular subtype (e.g. `Mandatory KYC and AML`, `OFAC`,
`Yield Aggregator`).
hops:
type: integer
nullable: true
description: >-
Number of hops to the entity (1 for a direct counterparty),
when the provider reports one. Always `null` for Merkle
Science, which reports only whether exposure is direct or
indirect: use `exposure_type`.
description:
type: string
nullable: true
description: >-
`entity_type / entity_subtype`, as the provider labels the
entity.
is_direct:
type: boolean
description: True when `exposure_type` is `direct`.
exposure_direction:
type: string
enum:
- incoming
- outgoing
- connected
description: >-
Whether the funds came from (`incoming`) or went to
(`outgoing`) this entity.
exposure_type:
type: string
enum:
- direct
- indirect
description: '`direct` (1 hop) or `indirect` (multi-hop) exposure.'
provider_entity_id:
type: string
nullable: true
description: The provider's own identifier for the entity.
provider_entity_type_id:
type: string
nullable: true
description: The provider's own identifier for `entity_type`.
provider_entity_subtype_id:
type: string
nullable: true
description: The provider's own identifier for `entity_subtype`.
country:
type: string
nullable: true
description: >-
Primary ISO 3166-1 alpha-2 country of the entity. Empty or
`null` when the provider does not know it.
raw_amount:
type: number
nullable: true
description: Amount in the asset's own unit, when the provider reports it.
raw_currency:
type: string
nullable: true
description: Unit of `raw_amount`, when the provider reports it.
counterparty_connections:
type: array
description: >-
Entities the provider attributes the screened address to. For Merkle
Science these come from the address's own owner and user tags, so
the same entity can appear twice, and they carry no fund flows:
`received_usd`, `sent_usd`, `received_hops` and `sent_hops` are
`null` and `percentage` is 0. Do not route on `risk_level` or
`is_direct` here: use `sanctions_hit`, `dominant_risk_category` and
`risk_factors[].is_high_risk` for the verdict, and `exposure_type`
in `source_of_funds`/`destination_of_funds` for directness.
items:
type: object
properties:
entity_name:
type: string
nullable: true
description: Attributed entity name.
entity_type:
type: string
nullable: true
description: Provider entity type.
entity_subtype:
type: string
nullable: true
description: Provider entity subtype.
risk_level:
type: string
description: >-
Lowercase and provider-dependent. For Merkle Science it is the
address's own 0-5 risk grade (`no_risk`, `low`, `medium_low`,
`medium`, `high`, `critical`), raised to `high` when the
entity's category is high risk; it is not a separate grade of
the entity.
categories:
type: array
items:
type: string
description: Normalised risk categories of the entity.
received_usd:
type: number
nullable: true
description: USD received from the entity, when the provider reports it.
sent_usd:
type: number
nullable: true
description: USD sent to the entity, when the provider reports it.
received_hops:
type: integer
nullable: true
description: >-
Hops to the entity on the receiving side, when the provider
reports them.
sent_hops:
type: integer
nullable: true
description: >-
Hops to the entity on the sending side, when the provider
reports them.
percentage:
type: number
description: >-
Share of the address's exposure, when the provider reports it;
otherwise 0.
is_direct:
type: boolean
description: >-
Always `true` for Merkle Science, whose connections are
attributions rather than counterparties.
country:
type: string
nullable: true
description: Country of the entity, when known.
provider_entity_id:
type: string
nullable: true
description: The provider's own identifier for the entity.
network_nodes:
type: array
items:
type: object
description: >-
Exposure graph nodes for transaction screening. Empty on a wallet
screening result.
network_edges:
type: array
items:
type: object
description: >-
Exposure graph edges for transaction screening. Empty on a wallet
screening result.
sanctions_hit:
type: boolean
description: True if the address has direct or indirect sanctions exposure.
pep_counterparty:
type: boolean
description: >-
Politically exposed person exposure. `null` when no PEP finding is
available, which is every result today because no provider reports
one; `false` only for an explicit negative screening result. Do not
read `null` as a completed PEP check.
nullable: true
dominant_risk_category:
type: string
nullable: true
description: >-
Highest-weighted high-risk category, or `null` when none is dominant
(e.g. `sanctioned`, `mixer`, `stolen_funds`).
risk_factors:
type: array
description: >-
Ranked explanation of `risk_score`: what produced this verdict.
Providers grade an address on their own model and return only a
verdict (Merkle Science returns an integer 0-5), so the score alone
is not actionable. Ordered high-risk first, then by the value that
moved through each driver, capped at the five strongest;
`source_of_funds` and `destination_of_funds` always carry the
complete breakdown. A high `risk_score` with no `is_high_risk` entry
means the provider reported no sanctions or attributed-entity match
and graded the address purely on its own exposure model - `summary`
states this explicitly.
items:
type: object
properties:
source:
type: string
enum:
- attribution
- exposure
description: >-
`attribution` is what the provider says the address itself is
(its own tag or cluster); `exposure` is where its funds
actually moved.
category:
type: string
description: >-
Normalised risk category, same vocabulary as the exposure
breakdown.
label:
type: string
description: >-
The provider's own wording for the driver (e.g. `Gambling /
Crypto only`), which is what you would also see in the
provider's console.
entity_name:
type: string
nullable: true
description: >-
Attributed entity behind the driver, for example a gambling
site or an exchange.
direction:
type: string
enum:
- incoming
- outgoing
- connected
- unknown
- attribution
description: >-
Direction of the fund flow, `attribution` when the driver is
the address's own tag, or `unknown` when the provider did not
report a direction.
exposure_type:
type: string
enum:
- direct
- indirect
- unknown
- attribution
description: >-
`direct` (1 hop) or `indirect` (multi-hop), `attribution` for
the address's own tag, or `unknown` when the provider did not
state how many hops away the counterparty is. Treat `unknown`
as unclassified, not as `direct`.
amount_usd:
type: number
format: float
nullable: true
description: USD value attributed to this driver.
percentage:
type: number
format: float
description: >-
Share of the address's TOTAL screened volume, both directions
combined - unlike `percentage` inside
`source_of_funds`/`destination_of_funds`, which is normalised
per direction. Comparable and summable across the whole list.
is_high_risk:
type: boolean
description: >-
Whether the category is one Didit treats as high risk
(`sanctioned`, `mixer`, `stolen_funds`, `ransomware`, `scam`,
`darknet_market`, `terrorist_financing`, `child_exploitation`,
`hacked_exchange`, `high_risk_exchange`, `seized_funds`).
description:
type: string
description: >-
One-line rendering of the driver, e.g. `9.01% indirect
outgoing exposure to Gambling / Crypto only (Example
Gambling)`.
raw_response:
type: object
additionalProperties: true
description: >-
The provider's own payload. Its shape is provider-specific and can
change without notice: read the normalised fields instead of parsing
it.
report_signature:
type: string
description: >-
Opaque HMAC-SHA256 signature over this exact result, scoped to your
application. Not meaningful on its own — repost the full response
body, unmodified and including this field, to `POST
/v3/wallet-screening/pdf/` to render it as a PDF. The PDF endpoint
rejects the request with `400` if `report_signature` is missing or
if any signed field (e.g. `risk_score`, `severity`, `sanctions_hit`)
was edited before repost.
required:
- provider
- screening_type
- risk_score
- severity
- status
- summary
- wallet_address
- blockchain
- sanctions_hit
- dominant_risk_category
- source_of_funds
- destination_of_funds
- counterparty_connections
- report_signature
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Your application's API key, from Developers -> API keys in the Business
Console. The primary key has full access. A named key can be scoped:
none, read or write per resource, limited to some workflows or to
approved sessions, to a list of IP addresses, and to an expiry date. 401
means the key is missing, wrong, revoked or expired; 403 means the key
has no access to this resource or action, or the request came from an
address outside its IP list; 404 on a session route means the session is
outside the key's workflows or statuses. A key without media access
receives image, video and PDF URLs as null, and a key without sessions
write receives session links and tokens as null. See
https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.