Screening Alert Events

When counterparty screening finds a match, Opsion immediately creates a critical alert event of type counterparty_screening. This event appears on the Alerts → Events page and is delivered over all configured notification channels.

Event structure

Counterparty screening events are standard alert events with a structured metadata payload that carries all the screening-specific details.

json

{
  "id": "evt_01j9xmk4p8q3r7t2",
  "severity": "critical",
  "status": "open",
  "title": "Sanctioned counterparty detected",
  "message": "Inbound from 0x1234…abcd · Lazarus Group (sanctions) · tx 0xa1b2c3d4e5…",
  "firedAt": "2025-05-24T11:34:00Z",
  "transaction": {
    "id": "txn_...",
    "hash": "0xa1b2c3d4e5f6...",
    "chain": "ethereum",
    "walletId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "metadata": {
    "type": "counterparty_screening",
    "counterpartyAddress": "0x1234...abcd",
    "fromAddress": "0x1234...abcd",
    "direction": "inbound",
    "transactionHash": "0xa1b2c3d4e5f6...",
    "hits": [
      {
        "entityName": "Lazarus Group",
        "entityId": "Q16246970",
        "categories": ["sanctions"],
        "topics": ["sanction", "crime.theft"],
        "datasets": ["us_ofac_sdn"],
        "score": 0.91
      }
    ]
  }
}

Metadata field	Description
`type`	"counterparty_screening" — identifies this as a screening event
`counterpartyAddress`	The address that matched one or more sanctions entries
`fromAddress`	The originating address of the transaction — shows where funds were sent from
`direction`	"inbound" (counterparty sent funds to you) or "outbound" (you sent to counterparty)
`transactionHash`	The on-chain transaction hash
`hits`	Array of matched entities — see hit fields below

Each entry in the hits array contains:

Field	Description
`entityName`	The name of the matched entity (e.g. "Lazarus Group")
`entityId`	OpenSanctions entity ID — use this to look up the entity on opensanctions.org
`categories`	Opsion risk categories derived from topics (e.g. ["sanctions", "hack"])
`topics`	Raw OpenSanctions topic strings
`datasets`	Source datasets the entity appears in (e.g. "us_ofac_sdn", "eu_fsf")
`score`	Match confidence, 0–1. Opsion flags results ≥ 0.5

Full details dialog

In the Opsion console, every counterparty screening event on the Alerts → Events page shows a View screening details button. Clicking it opens a dialog with:

Counterparty address — the address that matched the sanctions list, shown in full (monospaced, copyable).
Source address — the originating address of the transaction. For an inbound transaction this is the same as the counterparty address; for an outbound transaction it is your wallet's address. This field helps you immediately understand the flow of funds.
Direction — whether the transaction was inbound or outbound relative to your monitored wallet.
Transaction hash — a clickable link to the block explorer for the chain on which the transaction occurred.
Matched entities — one card per hit, showing the entity name, match confidence percentage, categories, source datasets, and OpenSanctions topics.

✦

Block explorer links

Transaction hashes in the full details dialog link directly to the relevant block explorer (Etherscan for Ethereum, Basescan for Base, Solscan for Solana, etc.). The link opens in a new tab so you can cross-reference on-chain data without leaving the console.

Notifications

Counterparty screening events are delivered over the same channels as your other alert rules — email, Slack, Lark, and Telegram. They are always sent at critical severity regardless of the severity setting on your alert rules.

The notification message format is:

text

Inbound from 0x1234…abcd · Lazarus Group (sanctions) · tx 0xa1b2c3d4…

For email notifications, the message includes the full counterparty address, all matched entity names, and a direct link to view the event in the Opsion console.

💡

No rule required

Counterparty screening alert events are created automatically — they are not tied to any specific alert rule you configure. They appear on the Events page alongside rule-based events and can be filtered by their counterparty_screening type.

Reviewing events

On the Alerts → Events page, counterparty screening events are identified by the View screening details action button. You can:

Acknowledge — mark the event as seen. Use this when you are actively investigating the match.
Resolve — close the event with an optional note. Use this when you have completed your review. A resolution note is strongly recommended for compliance audit trails (e.g. "Confirmed false positive — entity name collision with unrelated individual").
Export — include the event in a compliance evidence pack via Compliance → Evidence Packs. The exported record includes the full metadata payload, resolution note, and reviewer details.

Retrieving via API

Counterparty screening events are returned by the standard alert events endpoint. Filter to only screening events using the status parameter or inspect the metadata.type field client-side.

bash

# List all open alert events (includes counterparty screening events)
curl "https://api.opsion.xyz/api/alerts/events?status=open" \
  -H "Authorization: Bearer opsk_your_key_here"

typescript

// Filter to counterparty screening events client-side
const events = await opsion.alerts.events.list({ status: 'open' })
const screeningEvents = events.data.filter(
  e => e.metadata?.type === 'counterparty_screening'
)

See the API — Alerts reference for full details on querying, acknowledging, and resolving events programmatically.