BS Data API (1.0.0)

All API endpoints require authentication using an API key. Include your API key in the request headers:

x-api-key: YOUR_API_KEY_HERE

Getting an API Key

1. Access the dashboard at https://data-api.blockscout.ai/dashboard
2. Sign in using Single Sign-On (SSO) with your Blockscout account
3. Navigate to the "API Keys" section
4. Create and manage your API keys

Example Request

curl -X GET "https://api.bs-data.com/v1/attributions/darknet/addresses" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Rate Limiting

Rate limits are enforced based on your subscription tier. Every response includes rate limit headers:

• X-RateLimit-Limit: Maximum requests allowed
• X-RateLimit-Remaining: Requests remaining
• X-RateLimit-Reset: When the rate limit resets

Error Responses

• 401 Unauthorized: Missing or invalid API key
• 403 Forbidden: Insufficient permissions for the requested resource
• 429 Too Many Requests: Rate limit exceeded

Welcome to Blockscout's Entity Intelligence API - the comprehensive blockchain attribution platform serving law enforcement, financial institutions, and compliance teams worldwide. Our platform provides real-time access to a curated catalogue of 30,000+ entities spanning legitimate businesses and illicit operations across Bitcoin and Ethereum networks.

Entity Attribution

Every blockchain address and transaction in our system maps to real-world entities through our proprietary attribution engine. Using advanced clustering algorithms and human intelligence gathering, we maintain the industry's most comprehensive entity database.

The Entity Catalogue

Our SOT (Source of Truth) database contains 30,000+ meticulously researched entities including:

• Legitimate Businesses: Centralized exchanges, DeFi protocols, payment processors, mining pools
• Illicit Operations: Darknet markets, ransomware groups, fraud schemes, sanctioned entities
• High-Risk Services: Mixers, gambling sites, unregistered money services
• Specialized Categories: Chemical vendors, weapons dealers, human trafficking networks

Primary Key Architecture

The entity_id field serves as the universal primary key across all Blockscout APIs. This unique identifier:

• Links blockchain addresses to their controlling entities
• Connects transaction flows to real-world organizations
• Enables cross-reference between different data products
• Maintains consistency across all attribution data

Standard Workflow

1. Address Lookup: Query an address through attribution endpoints
2. Entity Discovery: Receive entity_id in the response
3. Entity Enrichment: Use /entities/{entity_id} to retrieve full profile
4. Risk Assessment: Analyze entity metadata, risk scores, and compliance flags
5. Transaction Analysis: Track fund flows between entities

Cross-Endpoint Integration

• Use entity_id from transaction endpoints to retrieve full entity profiles
• Cross-reference addresses with their associated entities
• Build comprehensive compliance reports by joining entity metadata with transaction flows
• Create entity watchlists by filtering on risk scores and entity types

Compliance & KYC/AML

• Automated Screening: Build real-time screening against 30,000+ entities
• Risk Scoring: Leverage entity risk scores (0-100) for transaction monitoring
• Sanctions Checking: Identify OFAC and internationally sanctioned entities
• Enhanced Due Diligence: Access complete entity profiles with business information

Law Enforcement & Investigations

• Attribution Analysis: Link cryptocurrency addresses to real-world entities
• Network Mapping: Trace relationships between entities through transaction flows
• Darknet Investigations: Track marketplace vendors and illegal service providers
• Asset Recovery: Identify exchange accounts for freezing orders

Financial Intelligence

• Threat Intelligence: Monitor emerging threats and new entity classifications
• Pattern Recognition: Identify transaction patterns across entity types
• Regulatory Reporting: Generate compliance reports with full entity attribution
• Risk Management: Assess counterparty risk using comprehensive entity data

Global Intelligence Network

Our attribution data is powered by:

• Human Intelligence: Global network of researchers and analysts
• Technical Analysis: State-of-the-art blockchain clustering algorithms
• Open Source Intelligence: Continuous monitoring of public sources
• Partner Data: Collaboration with law enforcement and financial institutions

Real-Time Updates

• New entities added daily as they emerge
• Continuous enrichment of existing entity profiles
• Risk scores updated based on latest intelligence
• Immediate flagging of newly sanctioned entities

The Entity object represents a single entry in Blockscout's comprehensive catalogue. Each entity is uniquely identified by an entity_id that serves as the primary key across all APIs.

Core Identification

Primary fields that uniquely identify and classify the entity:

• entity_id: Unique identifier (primary key)
• proper_name: Official or commonly known name
• entity_type: Classification (exchange, darknet, mixer, etc.)
• url: Primary website or service URL

Business Information

Corporate and contact details, primarily for legitimate businesses:

• ceo: Chief Executive Officer name
• key_personnel: Notable team members
• year_founded: Establishment year
• ticker: Stock ticker symbol (if publicly traded)
• contact_email: Official contact email
• contact_phone: Business phone number
• contact_address: Physical address
• legal_info_url: Terms of service or legal documentation

Risk & Compliance

Risk assessment and regulatory information:

• risk_score: Risk rating from 0-100
• no_kyc_req: KYC requirement flag
• ofac: OFAC sanctions status
• centralized: Centralization indicator
• dead: Operational status

Geographic & Jurisdiction

Location and regulatory jurisdiction:

• associate_country_1: Primary country of operation
• associate_country_2: Secondary country
• jurisdiction: Legal jurisdiction

Chemical Tracking (Specialized)

For chemical and pharmaceutical entities:

• cas_1 through cas_27: Chemical Abstracts Service registry numbers
• Used for tracking precursor chemicals and controlled substances

Social & Communication

Online presence and communication channels:

• contact_twitter: Twitter/X handle
• contact_telegram: Telegram contact
• social_media_profile: Primary social media
• ens_address: Ethereum Name Service address

Metadata & Tags

Classification and search optimization:

• entity_tag1 through entity_tag7: Descriptive tags
• description_merged: Comprehensive description
• parent_id: Parent entity reference

Field completeness varies significantly by entity type:

Legitimate Businesses

• ✅ Full business information: CEO, contact details, jurisdiction
• ✅ Legal documentation: Terms of service, regulatory filings
• ✅ Social media presence: Official channels and websites
• ✅ Low risk scores: Typically 0-30

Illicit Entities

• ❌ Limited business information: Anonymous operations
• ❌ No legal documentation: Underground services
• ⚠️ Encrypted communications: Telegram, Tor sites
• 🔴 High risk scores: Typically 70-100

Sanctioned Entities

• ⚠️ Sanctions metadata: OFAC flags and details
• ⚠️ Restricted operations: Limited transaction capabilities
• 🔴 Maximum risk scores: Always 90-100

Financial Services

• centralized exchange: Licensed cryptocurrency exchanges
• decentralized exchange: DEX protocols and smart contracts
• payment processor: Crypto payment gateways
• otc broker: Over-the-counter trading desks
• custody provider: Digital asset custodians

Illicit Services

• darknet: Darknet marketplaces
• darknet_vendor: Individual marketplace vendors
• ransomware: Ransomware operation addresses
• mixer: Cryptocurrency mixing services
• fraud: Scam and theft operations

High-Risk Categories

• gambling: Online gambling platforms
• high_risk_exchange: Exchanges with poor compliance
• unregistered_msb: Unlicensed money services
• sanctioned: OFAC/UN sanctioned entities

Specialized Tracking

• chemical: Chemical and pharmaceutical vendors
• weapons: Arms and explosives dealers
• human_trafficking: Human exploitation networks
• csam: CSAM-related entities

This section provides actual entity objects from the Blockscout SOT catalogue, demonstrating the contrast between legitimate businesses and illicit operations. These examples illustrate field availability patterns and help developers understand the data structure.

A fully regulated cryptocurrency exchange with complete business information and regulatory compliance.

{
  "entity_id": "coinbase",
  "proper_name": "Coinbase",
  "entity_type": "centralized exchange",
  "url": "coinbase.com",
  "ticker": "COIN",
  "year_founded": "2012",
  "ceo": "Brian Armstrong",
  "key_personnel": "Brian Armstrong, Fred Ehrsam",
  "contact_email": "subpoenas@coinbase.com",
  "contact_phone": "+1 (888) 908-7930",
  "contact_address": "248 3rd St #434, Oakland CA, 94607",
  "contact_twitter": "@CoinbaseSupport",
  "legal_info_url": "https://www.coinbase.com/legal/licenses",
  "social_media_profile": "facebook.com/coinbase/",
  "social_media_profile_2": "github.com/coinbase",
  "social_media_profile_3": "www.linkedin.com/company/coinbase",
  "ens_address": "coinbase.eth",
  "description_merged": "Coinbase.com is a widely-used platform for buying, selling, and storing cryptocurrencies. It's known for its user-friendly interface and strong security measures",
  "entity_tag1": "custodian",
  "entity_tag2": "staking",
  "entity_tag3": "gateway",
  "entity_tag4": "derivatives",
  "entity_tag5": "debit card",
  "entity_tag6": "non custodial wallets",
  "entity_tag7": "bitcoin treasury",
  "associate_country_1": "United States",
  "associate_country_2": "Global",
  "centralized": true,
  "no_kyc_req": false,
  "ofac": false,
  "dead": false,
  "parent_id": "coinbase"
}

Key Attributes

• ✅ Fully regulated with legal documentation
• ✅ Complete contact information (email, phone, address)
• ✅ Known leadership (CEO: Brian Armstrong)
• ✅ KYC/AML compliance required
• ✅ Multiple service offerings (custody, staking, derivatives)
• ✅ Publicly traded company (NASDAQ: COIN)

An illegal vendor of controlled substances and precursor chemicals operating without regulatory oversight.

{
  "entity_id": "buymethcanberra",
  "proper_name": "Buy Meth Canberra",
  "entity_type": "chemical",
  "url": "buymethcanberra.com",
  "cas_numbers": "537-46-2",
  "description_merged": "Australian supplier of high-purity methamphetamine and precursor chemicals. Offers nationwide shipping with 'discrete' packaging. Active on multiple encrypted communication platforms.",
  "entity_tag1": "methamphetamine",
  "entity_tag2": "precursor_chemicals",
  "entity_tag3": "australia",
  "entity_tag4": "encrypted_messaging",
  "associate_country_1": "Australia",
  "centralized": false,
  "no_kyc_req": true,
  "ofac": false,
  "dead": false,
  "risk_score": 95
}

Key Attributes

• ⚠️ Illegal chemical vendor
• ⚠️ CAS number tracking for controlled substances
• ⚠️ No KYC requirements
• ⚠️ High risk score (95/100)
• ⚠️ Anonymous operations
• ⚠️ Limited metadata due to illicit nature

Compliance Screening

// Check if entity requires enhanced due diligence
if (entity.risk_score > 70 || entity.ofac === true) {
  flagForEnhancedReview(entity);
}

Entity Type Filtering

// Filter for darknet entities
const darknetEntities = entities.filter(e =>
  e.entity_type.includes('darknet')
);

Risk Assessment

// Categorize risk levels
const riskLevel = entity.risk_score > 80 ? 'CRITICAL' :
                 entity.risk_score > 50 ? 'HIGH' :
                 entity.risk_score > 30 ? 'MEDIUM' : 'LOW';

API endpoints for searching and retrieving entities from the SOT (Source of Truth) catalogue. See the Overview, Entity Documentation, and Examples sections for comprehensive platform information.

Complete attribution data across all categories - unrestricted access to all entity types

Darknet marketplaces, vendors, drugs, and related illicit services

Cryptocurrency ATM operators and kiosk services

Russian-linked money services and sanctioned exchangers

Human trafficking, CSAM, and organ trafficking entities

Weapons dealers, explosives, and military-grade materials

Opioid trade and precursor chemical entities

Child Sexual Abuse Material related entities

Access various data products

Monitor API usage and analytics

API key management