API — Screening

Opsion integrates with OpenSanctions (via a self-hosted yente instance) to screen wallet addresses against sanctions lists, PEP registries, and crime datasets. When a match is found, Opsion automatically creates risk labels on the wallet.

💡

Plan requirement

Screening is available on the Enterprise plan. Bulk screening requires Edit access.

Screen a wallet

Triggers an immediate on-demand screening for a single wallet. The wallet must belong to your organisation. Requires Edit access.

bash

POST /api/screening/wallets/:id

curl -X POST https://api.opsion.xyz/api/screening/wallets/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer opsk_your_key_here"

Response — 200 OK

json

{
  "data": {
    "screeningId": "c3d4e5f6-0000-0000-0000-000000000000",
    "status": "flagged",
    "hitCount": 1
  }
}

Returns 502 Bad Gateway if the upstream screening service could not be reached.

Bulk screen

Screens every wallet in the organisation in parallel. Returns a summary with per-wallet results. Requires Edit access.

bash

POST /api/screening/wallets

curl -X POST https://api.opsion.xyz/api/screening/wallets \
  -H "Authorization: Bearer opsk_your_key_here"

Response — 200 OK

json

{
  "data": {
    "screened": 12,
    "flagged": 1,
    "clear": 10,
    "errors": 1,
    "results": [
      {
        "walletId": "550e8400-e29b-41d4-a716-446655440000",
        "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "status": "flagged",
        "hitCount": 2,
        "screeningId": "c3d4e5f6-0000-0000-0000-000000000000"
      },
      {
        "walletId": "661f9511-f3ac-52e5-b827-557766551111",
        "address": "0xAb5801a7D398351b8bE11C439e05C5B3259aEC9B",
        "status": "clear",
        "hitCount": 0,
        "screeningId": "d4e5f6a7-0000-0000-0000-000000000000"
      }
    ]
  }
}

✦

Rate limits

Each wallet consumes one call to the underlying screening service. For large organisations, prefer scheduling bulk runs during off-peak hours.

Get screening results

Returns the 20 most recent screening records for a wallet, newest first.

bash

GET /api/screening/wallets/:id/results

curl https://api.opsion.xyz/api/screening/wallets/550e8400-e29b-41d4-a716-446655440000/results \
  -H "Authorization: Bearer opsk_your_key_here"

json

{
  "data": [
    {
      "id": "c3d4e5f6-0000-0000-0000-000000000000",
      "walletId": "550e8400-e29b-41d4-a716-446655440000",
      "organisationId": "aabbccdd-0000-0000-0000-000000000000",
      "status": "flagged",
      "hitCount": 1,
      "triggeredBy": "manual",
      "screenedAt": "2025-03-01T14:22:00Z",
      "createdAt": "2025-03-01T14:22:01Z"
    }
  ]
}

Field	Type	Description
`id`	`uuid`	Unique ID for this screening run
`walletId`	`uuid`	Wallet that was screened
`organisationId`	`uuid`	Your organisation
`status`	`string`	clear \| flagged \| error
`hitCount`	`integer`	Number of matching entities found
`triggeredBy`	`string`	auto \| manual \| bulk
`screenedAt`	`datetime`	When the screening ran

Screening statuses

Status	Meaning
`clear`	No matches found above the confidence threshold (≥ 0.5)
`flagged`	One or more entities matched — risk labels have been written
`error`	The upstream screening service returned an error or timed out

Risk labels

When a screening run returns a flagged status, Opsion automatically upserts risk labels onto the wallet — one label per OpenSanctions topic category. Labels are visible in the console and via the Wallets API (GET /api/wallets/:id).

Risk category	OpenSanctions topics
`sanctions`	sanction, debarment, export_control, counter_sanction
`pep`	role.pep, role.politician, role.rca, role.oligarch, role.diplomat, …
`terrorist_financing`	terror, crime.terror
`money_laundering`	crime.money_laundering, crime.fin_crime, crime
`ransomware`	crime.ransomware
`hack`	crime.theft
`scam`	crime.fraud