openapi: 3.0.3
info:
  title: DarkScout Intelligence — Surikata-X API
  version: "1.0"
  description: |
    REST API for accessing DarkScout Intelligence darknet crypto intelligence data.
    Surikata-X provides comprehensive darknet intelligence for blockchain addresses,
    including entity attribution, transaction tags, and evidence verification.

    Focused on CSAM and human trafficking cryptocurrency address detection.
    Identifies addresses hours to days before first funding occurs.
  contact:
    name: DarkScout Intelligence
    url: https://darkscoutintel.com/contact.html
  license:
    name: Proprietary
    url: https://darkscoutintel.com/data-license.html

servers:
  - url: https://data-api.blockscout.ai/api/v1
    description: Production

security:
  - apiKey: []

paths:
  /surikata-x:
    get:
      operationId: lookupAddress
      summary: Look up darknet intelligence for a blockchain address
      description: |
        Retrieve comprehensive darknet intelligence for a blockchain address,
        including entity attribution, transaction tags, and evidence verification.
        Supports Bitcoin, Ethereum, Litecoin, Solana, TRON, and Dogecoin addresses.
      parameters:
        - name: address
          in: query
          required: true
          description: The blockchain address to query
          schema:
            type: string
          examples:
            bitcoin:
              value: bc1qfxvrffsztzugcpg5msss2lhlc880g285lu0d0a
              summary: Bitcoin address
            ethereum:
              value: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
              summary: Ethereum address
            solana:
              value: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
              summary: Solana address
            tron:
              value: TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW
              summary: TRON address
        - name: noCache
          in: query
          required: false
          description: Set to true to bypass 15-minute response cache
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Intelligence data for the queried address
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SurikataXResponse"
              examples:
                entityAttributed:
                  summary: Address attributed to a known entity
                  value:
                    success: true
                    data:
                      address: 1BXwhiB1YoXCW6s5QcwX3ff3NUUMsSaWFo
                      chain: bitcoin
                      entity_id: example_entity_id
                      entity_type: exchange
                      proper_name: Example Exchange
                      first_seen: "2025-10-15T08:23:41.000Z"
                      urls:
                        - https://example.com
                      entity_id_evidence:
                        - https://darkscoutintel.com/evidence.html?entity=example_entity_id&hash=abc12345
                    meta:
                      queryTime: 3847
                      timestamp: "2025-12-02T21:02:25.730Z"
                tagsOnly:
                  summary: Address with transaction tags but no entity attribution
                  value:
                    success: true
                    data:
                      address: 1PBXdHa8kgrsxjZFdiGUf5hcxr4xY8D3y1
                      chain: bitcoin
                      entity_id: null
                      entity_type: null
                      proper_name: null
                      first_seen: null
                      tags:
                        - tag: csam consumer
                          txid: 0fdcc3da34cdae427388076f8451927cd72b1d2b6e608a7e289b593eca755cdd
                          cp_addr: bc1qy5d4dvmp87tyhjl97chu5x0a2cwxxtgxmvrzl3
                          related_entity_id: counterparty_entity_id
                          proper_name: Counterparty Entity
                          url: https://counterparty.com
                          tag_evidence: https://darkscoutintel.com/evidence.html?entity=counterparty_entity_id&hash=def67890
                    meta:
                      queryTime: 2789
                      timestamp: "2025-12-02T23:31:50.479Z"
                noData:
                  summary: Address not found in intelligence database
                  value:
                    success: true
                    data:
                      address: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
                      chain: bitcoin
                      entity_id: null
                      entity_type: null
                      proper_name: null
                      first_seen: null
                    meta:
                      queryTime: 1259
                      timestamp: "2025-12-02T21:02:25.730Z"
        "400":
          description: Missing or invalid address parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key obtained from https://data-api.blockscout.ai/dashboard

  schemas:
    SurikataXResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was successful
        data:
          $ref: "#/components/schemas/AddressIntelligence"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    AddressIntelligence:
      type: object
      properties:
        address:
          type: string
          description: The queried blockchain address
        chain:
          type: string
          enum: [bitcoin, ethereum, litecoin, solana, tron, dogecoin]
          description: Blockchain network detected from the address format
        entity_id:
          type: string
          nullable: true
          description: Unique entity identifier if attributed to a known entity
        entity_type:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          nullable: true
          description: "Entity classification (e.g., exchange, darknet, mixer, csam, human_trafficking)"
        proper_name:
          type: string
          nullable: true
          description: Business or entity name associated with the address
        first_seen:
          type: string
          format: date-time
          nullable: true
          description: When this address was first observed on the darknet
        urls:
          type: array
          items:
            type: string
            format: uri
          description: URLs associated with the entity
        entity_id_evidence:
          type: array
          items:
            type: string
            format: uri
          description: Links to evidence screenshots proving entity attribution
        tags:
          type: array
          items:
            $ref: "#/components/schemas/TagEntry"
          description: Transaction tags and counterparty information

    TagEntry:
      type: object
      properties:
        tag:
          type: string
          description: "Tag classification (e.g., csam consumer, human_trafficking)"
        txid:
          type: string
          description: Transaction ID where the tag was identified
        cp_addr:
          type: string
          description: Counterparty address in the tagged transaction
        related_entity_id:
          type: string
          nullable: true
          description: Entity ID of the counterparty
        proper_name:
          type: string
          nullable: true
          description: Counterparty entity name
        url:
          type: string
          format: uri
          nullable: true
          description: Counterparty associated URL
        tag_evidence:
          type: string
          format: uri
          nullable: true
          description: Link to evidence screenshot proving the tag

    ResponseMeta:
      type: object
      properties:
        queryTime:
          type: integer
          description: Query execution time in milliseconds
        timestamp:
          type: string
          format: date-time
          description: Response timestamp

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Error message
        data:
          nullable: true