SRR Investigation Workflow (Sandbox)

The sandbox is a free way to try the CipherOwl Screening, Risk & Reporting (SRR) API end-to-end before you go to production. It exposes a small, curated set of blockchain addresses that return real risk data — so you can build and test your integration against meaningful responses without being charged.

You opt into the sandbox by adding ?config=co-sandbox to any Screening or Risk Reason request. Under this config:

• A curated set of addresses (see the catalog below) returns a risky verdict with real reasons.
• Every other address returns clean (foundRisk: false). The sandbox deliberately exposes nothing beyond the curated set.

📘

What you can test

The sandbox covers the EVM and Tron chains, across the Screening and Risk Reason APIs. Use it to validate your auth flow, request shapes, JSON parsing, and how your application reacts to both risky and clean verdicts.

Prerequisites

1. A CipherOwl account on the free tier. Sign up at the CipherOwl application.
2. A working API client. See Build a CipherOwl Client to exchange your client_id / client_secret for a Bearer token and handle refresh and rate limits.

The curl examples below assume you have exported that token:

export CO_TOKEN="{YOUR_ACCESS_TOKEN}"

All requests go to the https://svc.cipherowl.ai base URL. For the {chain} path parameter, use the chain family key evm (for any EVM-compatible address) or tron. The Screening and Risk Reason APIs also resolve EVM network names like ethereum to evm, but the Report API strictly requires evm.

A complete compliance workflow

A real compliance check rarely stops at a yes/no. The SRR API is designed as a funnel: start with the cheapest, fastest call and drill down only when you need more. After a one-time capability check (Step 0), the walkthrough follows one address through the funnel — from a real-time gate, to triage, to a full investigation, and finally a shareable report.

Step 0 — Check what's supported (once)

Before screening, discover which chains expose the SRR capabilities you need. chain-capabilities lists every supported chain with three progressive tiers: screening (baseline address screening), reporting (the full SRR stack — score, breakdown, detail, report), and research (also available in OwlTrace). This is a one-time preflight — it isn't tied to an address and doesn't take a config.

curl --request GET \
  --url 'https://svc.cipherowl.ai/api/chain-capabilities/v1' \
  --header 'accept: application/json' \
  --header "Authorization: Bearer $CO_TOKEN"

{
  "capabilities": {
    "ethereum": { "chainClass": "evm", "screening": true, "reporting": true, "research": true },
    "tron": { "chainClass": "tron", "screening": true, "reporting": true, "research": true },
    "bitcoin": { "chainClass": "bitcoin", "screening": true, "reporting": true, "research": true }
  }
}

Each chain is keyed by its network name and carries a chainClass — the family key you pass to the other endpoints (for example ethereum → evm). The example above is trimmed to three chains; the live response lists every supported network. The sandbox covers EVM and Tron because both expose the full reporting tier, so every step below works on them.

Our running example is the sandbox address 0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704. Imagine it has just requested a withdrawal and you need to decide whether to allow it.

Step 1 — Screen at the gate

Screening is the lowest-latency SRR endpoint: a fast yes/no verdict you can put inline on a deposit, withdrawal, or counterparty check.

curl --request GET \
  --url 'https://svc.cipherowl.ai/api/screen/v1/chains/evm/addresses/0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704?config=co-sandbox' \
  --header 'accept: application/json' \
  --header "Authorization: Bearer $CO_TOKEN"

{
  "config": "co-sandbox",
  "chain": "evm",
  "address": "0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704",
  "foundRisk": true,
  "version": "9ro5xhnASL0DXNLJWTrU9mHJJDO4cvkS"
}

foundRisk is true. → Do not auto-approve. The address carries a risk signal, so you escalate to triage.

Step 2 — Triage: how severe, and what kind?

A yes/no isn't enough to decide. Next, get a sense of severity and category — still without pulling the full evidence.

Risk score gives you a single deterministic 0–100 number plus a band (Low Risk / Medium Risk / High Risk / Severe Risk), ideal for threshold rules and automated tiering:

curl --request GET \
  --url 'https://svc.cipherowl.ai/api/reason/v2/chains/evm/addresses/0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704/risk-score?config=co-sandbox' \
  --header 'accept: application/json' \
  --header "Authorization: Bearer $CO_TOKEN"

{
  "chain": "evm",
  "address": "0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704",
  "config": "co-sandbox",
  "riskProfile": "default",
  "riskScore": 100,
  "riskBand": "Severe Risk",
  "breakdown": [
    { "category": "hack", "direction": "DIRECT", "hops": 0, "riskContribution": 65 },
    { "category": "jp_sanctioned", "direction": "RECEIVE", "hops": 1, "usdValue": 8244129, "riskContribution": 82.32 },
    { "category": "ofac", "direction": "RECEIVE", "hops": 1, "usdValue": 8244129, "riskContribution": 82.32 }
  ],
  "timestamp": "2026-06-24T08:06:13Z"
}

Risk breakdown lists the matched risk categories and whether each exposure is direct or indirect — an at-a-glance profile for a dashboard or a case summary:

curl --request GET \
  --url 'https://svc.cipherowl.ai/api/reason/v2/chains/evm/addresses/0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704/risk-breakdown?config=co-sandbox' \
  --header 'accept: application/json' \
  --header "Authorization: Bearer $CO_TOKEN"

{
  "chain": "evm",
  "address": "0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704",
  "config": "co-sandbox",
  "risks": [
    { "type": "DIRECT", "category": "hack", "percentage": 100 },
    { "type": "INDIRECT", "category": "jp_sanctioned", "direction": "RECEIVE", "percentage": 99.95, "hops": 1, "totalUsdValue": 8244129.05 },
    { "type": "INDIRECT", "category": "ofac", "direction": "RECEIVE", "percentage": 99.95, "hops": 1, "totalUsdValue": 8244129.05 }
  ]
}

This address is itself a flagged hack entity (DIRECT), and it has also received funds from OFAC- and Japan-sanctioned entities one hop away (INDIRECT, ~$8.2M). → A severe score plus a direct hack and sanctions exposure can't be cleared automatically. You open an investigation and pull the evidence.

Step 3 — Investigate: pull the full evidence

The detail endpoint returns the complete evidence behind the verdict: for each matched category and transaction direction, the number of hops to the risky entity, total USD and percentage exposure, first/last exposure timestamps, and the actual transaction paths connecting the address to risky entities.

curl --request GET \
  --url 'https://svc.cipherowl.ai/api/reason/v2/chains/evm/addresses/0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704/detail?config=co-sandbox' \
  --header 'accept: application/json' \
  --header "Authorization: Bearer $CO_TOKEN"

{
  "chain": "evm",
  "address": "0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704",
  "config": "co-sandbox",
  "foundRisk": true,
  "riskLevel": "HIGH",
  "reasons": [
    { "category": "hack", "direction": "SEND", "totalUsdValue": "Infinity", "totalPercentage": 100 },
    { "category": "hack", "direction": "RECEIVE", "totalUsdValue": "Infinity", "totalPercentage": 100 },
    {
      "category": "jp_sanctioned",
      "direction": "RECEIVE",
      "hops": 1,
      "totalUsdValue": 8244129.049350821,
      "totalPercentage": 99.95125571490293,
      "firstExposureTimestamp": "1652499489",
      "lastExposureTimestamp": "1652499489",
      "paths": [
        { "addresses": ["0xf7b31119c2682c88d88d455dbb9d5932c65cf1be", "0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704"] }
      ]
    },
    {
      "category": "ofac",
      "direction": "RECEIVE",
      "hops": 1,
      "totalUsdValue": 8244129.049350821,
      "totalPercentage": 99.95125571490293,
      "firstExposureTimestamp": "1652499489",
      "lastExposureTimestamp": "1652499489",
      "paths": [
        { "addresses": ["0xf7b31119c2682c88d88d455dbb9d5932c65cf1be", "0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704"] }
      ]
    }
  ]
}

Each entry in reasons[] is one risk category with its exposure metrics and supporting transaction paths:

• The hack reasons are direct — the address is itself a flagged entity, so its hack exposure is total ("Infinity" / 100%).
• The jp_sanctioned and ofac reasons are indirect at 1 hop, and the paths show exactly how: this address received funds from 0xf7b31119c2682c88d88d455dbb9d5932c65cf1be (itself another sandbox address — see the catalog).

Step 4 — Document: generate a report

To close the case, generate a complete, human-readable risk assessment for your case file or audit trail. The Report API lives on the https://svc.cipherowl.ai base URL and also honors ?config=co-sandbox.

curl --request GET \
  --url 'https://svc.cipherowl.ai/api/report/v1/risk-assessment/chains/evm/addresses/0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704?config=co-sandbox' \
  --header 'accept: application/json' \
  --header "Authorization: Bearer $CO_TOKEN"

{
  "risk_level": "nondeterministic",
  "found_risk": true,
  "report": "## Risk Assessment\n\nThe address `0x93df2c9c8786242b8fdca3f96b3914b8b4a9f704` presents **HIGH** risk due to significant exposure across OFAC sanctions, Japan sanctions (jp_sanctioned), and hack-related activity...\n\nThe most critical exposure is a direct, single-hop receipt of **8,244,129.05 USD** (99.95% of activity) from `0xf7b31119c2682c88d88d455dbb9d5932c65cf1be`, flagged under both *ofac* and *jp_sanctioned*...\n\nImmediate account freezing, mandatory SAR filing, and regulatory disclosure are strongly recommended.",
  "error": null,
  "timestamp": "2026-06-24T09:25:36Z"
}

The report field is a Markdown narrative written from the same evidence you pulled in Step 3, summarizing the exposure in plain language for a reviewer. It is generated per request, so the exact wording varies between calls and this endpoint takes a few seconds longer than the others.

That is the full funnel: screen to gate in real time, score / breakdown to triage, detail to investigate, and report to document — all driven from a single address.

The other outcome — a clean address

Most addresses are not risky. To see the clean path your code must also handle, screen any address that is not in the curated set. It returns clean even if the address is risky under a production config — confirming the sandbox exposes nothing beyond the curated stories.

curl --request GET \
  --url 'https://svc.cipherowl.ai/api/screen/v1/chains/evm/addresses/0x0000000000000000000000000000000000000001?config=co-sandbox' \
  --header 'accept: application/json' \
  --header "Authorization: Bearer $CO_TOKEN"

{
  "config": "co-sandbox",
  "chain": "evm",
  "address": "0x0000000000000000000000000000000000000001",
  "foundRisk": false,
  "version": "9ro5xhnASL0DXNLJWTrU9mHJJDO4cvkS"
}

When foundRisk is false, there is nothing to triage — you let the transaction through.

Sandbox address catalog

These addresses return a risky verdict under ?config=co-sandbox. Each tells a different risk story — use them to exercise the scenarios your integration needs to handle (direct sanctions, direct hacks, and indirect exposure at one hop, across several risk bands).

EVM (chains/evm)

Tron (chains/tron)

📘

The catalog evolves

The curated address set is maintained by CipherOwl and may change over time. If an address ever returns clean, pick another from the catalog above.

Notes and limits

• Chains: the sandbox supports EVM and Tron only. Use the chain key evm or tron.
• APIs: the sandbox covers Screening, Risk Reason, and Reporting (screen, risk-score, risk-breakdown, detail, and report/risk-assessment).
• Scope: only the curated addresses return risk. Any other address — including production-risky ones — returns clean under co-sandbox.
• Going to production: when you upgrade, swap ?config=co-sandbox for the production config appropriate to your plan (for example the default config) and you immediately screen against the full CipherOwl risk graph. The request shapes are identical.
• Rate limits: sandbox requests are rate-limited like all API traffic. See Authentication for token and rate-limit notes.

Need help? Reach out to CipherOwl Support.