Get API Key

API Documentation

Free access to nation-state crypto threat intelligence. Build compliance tools, research projects, or integrations.

Quick Links

Base URL

https://threats.osmansonmez.com/api/v1

Status

Operational

Getting Started

The NSCTIP API is free and open. No authentication required for public endpoints.

Quick Test
curl https://threats.osmansonmez.com/api/v1/nations

No API Key Required

Public endpoints are free to use. For higher rate limits, contact [email protected].

Endpoints

GET /api/v1/nations

Get overview of all tracked nations and global statistics.

{
  "success": true,
  "data": {
    "nations": [
      {
        "code": "north_korea",
        "name": "North Korea",
        "flag": "🇰🇵",
        "riskLevel": "critical",
        "totalVolumeUsd": 5200000000,
        "activeWallets": 207
      }
    ],
    "global": {
      "totalTrackedWallets": 329,
      "totalClusters": 15,
      "totalVolumeUsd": 25700000000
    }
  }
}
GET /api/v1/clusters

List all identified wallet clusters.

Query params: nation, status

Example: /api/v1/clusters?nation=north_korea&status=active
GET /api/v1/wallets

List all tracked sanctioned wallets.

Query params: nation, blockchain, cluster

GET /api/v1/incidents

List major crypto theft incidents by nation-state actors.

Query params: nation, status, limit

Address Check

Check if a cryptocurrency address is linked to sanctioned entities or nation-state threat actors.

GET /api/v1/check/{address}

Returns risk assessment for the given address.

Example Request

curl https://threats.osmansonmez.com/api/v1/check/0x098B716B8Aaf21512996dC57EB0615e2383E2f96

Response (Sanctioned Address)

{
  "success": true,
  "data": {
    "address": "0x098B716B8Aaf...",
    "isSanctioned": true,
    "riskScore": 100,
    "riskLevel": "critical",
    "nation": {
      "code": "north_korea",
      "name": "North Korea",
      "flag": "🇰🇵"
    },
    "entity": {
      "name": "Lazarus Group - Ronin Primary",
      "threatActor": "lazarus",
      "cluster": "DPRK-RONIN-2022"
    },
    "designation": {
      "source": "ofac",
      "date": "2022-04-14"
    },
    "recommendation": "DO NOT TRANSACT"
  }
}

Response (Clean Address)

{
  "success": true,
  "data": {
    "address": "0x123...",
    "isSanctioned": false,
    "riskScore": 0,
    "riskLevel": "unknown",
    "recommendation": "Address not found in NSCTIP database."
  }
}

Disclaimer

Absence from NSCTIP database does not guarantee an address is safe. Always conduct proper due diligence.

Address Profile

Get comprehensive profile including cluster analysis, related wallets, and threat context.

GET /api/v1/profile/{address}

Example Request

curl https://threats.osmansonmez.com/api/v1/profile/0x098B716B8Aaf21512996dC57EB0615e2383E2f96

Response

{
  "success": true,
  "data": {
    "address": "0x098B716B8Aaf...",
    "profile": {
      "isSanctioned": true,
      "riskScore": 100,
      "entityName": "Lazarus Group - Ronin Primary",
      "threatActor": "lazarus"
    },
    "nation": {
      "code": "north_korea",
      "name": "North Korea",
      "flag": "🇰🇵"
    },
    "cluster": {
      "id": "DPRK-RONIN-2022",
      "name": "Ronin Bridge Cluster",
      "walletCount": 86,
      "totalVolumeUsd": 620000000,
      "mixersUsed": ["Tornado Cash", "Sinbad"]
    },
    "relatedWallets": [...],
    "relatedIncident": {
      "name": "Ronin Bridge Hack",
      "amountUsd": 620000000
    }
  }
}

Alert Subscription

Subscribe to receive alerts when sanctioned wallets move funds or new designations occur.

POST /api/v1/alerts/subscribe

Request Body

{
  "email": "[email protected]",
  "alerts": ["transactions", "designations", "incidents"],
  "nations": ["north_korea", "iran", "russia"],
  "addresses": ["0x123..."],  // optional: specific addresses to watch
  "frequency": "instant"      // instant | daily | weekly
}

Response

{
  "success": true,
  "data": {
    "subscriptionId": "sub_1234567890",
    "email": "[email protected]",
    "alertTypes": ["transactions", "designations", "incidents"],
    "status": "active"
  },
  "message": "Successfully subscribed to alerts."
}

Webhook Integration

Receive real-time alerts via webhook to your own endpoint.

Webhook Payload 
POST https://your-endpoint.com/webhook

Headers:
  X-NSCTIP-Signature: sha256=...
  Content-Type: application/json

Body:
{
  "type": "transaction_alert",
  "severity": "critical",
  "timestamp": "2025-02-23T15:30:00Z",
  "data": {
    "address": "0x098B716B...",
    "nation": "north_korea",
    "threatActor": "lazarus",
    "transactionHash": "0xabc...",
    "amountUsd": 2500000,
    "direction": "outbound"
  }
}

Webhook Event Types

transaction_alert Wallet movement detected
new_designation New OFAC address added
cluster_activity Cluster-wide movement
major_incident New hack/breach detected

Webhook integration available for Researcher and Enterprise tiers. Contact us for access.

Rate Limits

Tier Requests/Day Features
Public 100 All endpoints, no auth required
Researcher 1,000 + Historical data, bulk queries
Enterprise Unlimited + Webhooks, SLA, priority support

Error Codes

Code Description
400 Bad Request - Invalid parameters
404 Not Found - Resource doesn't exist
429 Rate Limit Exceeded
500 Internal Server Error

Integration Examples

JavaScript / Node.js 
const response = await fetch(
  'https://threats.osmansonmez.com/api/v1/check/0x098B716B...'
);
const data = await response.json();

if (data.data.isSanctioned) {
  console.warn('⚠️ SANCTIONED ADDRESS:', data.data.entity.name);
}
Python 
import requests

response = requests.get(
    'https://threats.osmansonmez.com/api/v1/check/0x098B716B...'
)
data = response.json()

if data['data']['isSanctioned']:
    print(f"⚠️ SANCTIONED: {data['data']['entity']['name']}")

For Research & Public Interest

Free access for researchers, journalists, academics & compliance professionals