Crypto Detective Node.js / TypeScript SDK

Official server-side Node.js and TypeScript SDK for the Crypto Detective Investigation API.

Overview

The Crypto Detective SDK provides a typed server-side interface to the Crypto Detective REST API.

It allows applications to submit blockchain addresses for investigation and receive the canonical Crypto Detective investigation response, including:

• Final Risk Score
• Risk level
• Address validity
• Classification
• Hard-stop status
• Final score source
• Extended intelligence returned by the Crypto Detective API

The SDK does not calculate or reconstruct Crypto Detective risk scores. The authoritative Final Risk Score is returned by the Crypto Detective API as scan.score.

Requirements

• Node.js 18 or later
• Active Crypto Detective API subscription
• Crypto Detective API key

Installation

Install the Crypto Detective SDK in your server-side Node.js application:

npm install @cryptodetective/sdk

The SDK requires Node.js 18 or later.

After installation, import the client:

import { CryptoDetectiveClient } from "@cryptodetective/sdk";

For CommonJS applications:

const {
  CryptoDetectiveClient,
  CryptoDetectiveError,
} = require("@cryptodetective/sdk");

Security

The Crypto Detective API key is a server-side credential.

Do not expose the API key in:

• Browser JavaScript
• Client-side React or Next.js components
• Public repositories
• Mobile application bundles
• HTML source

Store the API key in a secure server-side environment variable or secrets-management system.

Configuration

Create the Crypto Detective client with your server-side API key:

import { CryptoDetectiveClient } from "@cryptodetective/sdk";

const client = new CryptoDetectiveClient({
  apiKey: process.env.CRYPTO_DETECTIVE_API_KEY!,
});

The SDK connects to the production Crypto Detective API by default.

For specialized environments, the API base URL can be overridden:

const client = new CryptoDetectiveClient({
  apiKey: process.env.CRYPTO_DETECTIVE_API_KEY!,
  baseUrl: "https://cryptodetective.app/api/v1",
});

For normal production integrations, the default base URL should be used.

Store the API key in a server-side environment variable or secrets-management system. Never send the API key to the browser.

Investigation Request

Submit an investigation with client.investigate():

const result = await client.investigate({
  address: "0x000000000000000000000000000000000000dEaD",
  chainSelected: "eth",
  scanMode: "full",
});

Request Fields

| Field | Required | Description | |---|---|---| | address | Yes | Blockchain address to investigate. | | chainSelected | Yes | Blockchain network to use for the investigation. | | scanMode | No | "quick" or "full". Defaults to "full". | | assetSymbol | No | Optional asset symbol. | | calldata | No | Optional transaction calldata for applicable investigations. | | spender | No | Optional spender address for applicable investigations. |

Supported Chains

The SDK currently accepts:

auto, btc, eth, bsc, base, polygon, arbitrum, optimism, avalanche, tron, sol, ada, ltc, doge, xrp, bch, bnb, atom

Use the exact lowercase chain identifier shown above.

Investigation Response

A successful investigation returns the canonical Crypto Detective API response:

const result = await client.investigate({
  address: "0x000000000000000000000000000000000000dEaD",
  chainSelected: "eth",
  scanMode: "full",
});

console.log(result.scan.score);
console.log(result.scan.risk_level);
console.log(result.scan.hard_stop_triggered);
console.log(result.scan.score_breakdown.final_score_source);

Error Handling

The SDK throws CryptoDetectiveError when the Crypto Detective API returns an error.

import {
  CryptoDetectiveClient,
  CryptoDetectiveError,
} from "@cryptodetective/sdk";

try {
  const result = await client.investigate({
    address: "0x...",
    chainSelected: "eth",
    scanMode: "full",
  });

  console.log(result.scan.score);
} catch (error) {
  if (error instanceof CryptoDetectiveError) {
    console.error("HTTP Status:", error.status);
    console.error("Error Code:", error.code);
    console.error("Message:", error.message);
  } else {
    throw error;
  }
}

Applications should make programmatic decisions using the HTTP status and error.code. Do not depend on exact error-message wording.

Common HTTP statuses include:

| Status | Meaning | |---:|---| | 400 | Invalid request JSON or invalid idempotency key. | | 401 | Missing or invalid API authentication. | | 403 | API subscription or entitlement required. | | 405 | HTTP method not allowed. | | 409 | Idempotency conflict or request already in progress. | | 422 | Request validation failed. | | 429 | Rate limit or monthly quota reached. | | 500 | Investigation or accounting failure. | | 503 | Required API service or production dependency unavailable. |

A failed API request should not be interpreted as a successful low-risk investigation. The integrating application determines the appropriate failure policy for its own workflow.

Idempotency

Crypto Detective supports optional idempotency keys for investigation requests.

Use an idempotency key when your application may retry the same investigation and you want to prevent duplicate processing:

const result = await client.investigate(
  {
    address: "0x000000000000000000000000000000000000dEaD",
    chainSelected: "eth",
    scanMode: "full",
  },
  {
    idempotencyKey: "investigation-12345",
  }
);

Idempotency keys:

• Are optional.
• May contain a maximum of 128 characters.
• May contain letters, numbers, ., _, :, and -.
• Should identify one logical investigation request.

Reusing the same idempotency key with the same request allows the API to return the completed result without performing the investigation again.

Reusing the same idempotency key with different request data results in an idempotency conflict.

If an investigation using the same key is still being processed, the API may return a conflict indicating that the request is already in progress.

Production Security and Integration Model

The Crypto Detective SDK is designed for server-side use.

A typical production integration follows this pattern:

User / Browser / Application
          ↓
Customer Backend
          ↓
Crypto Detective SDK
          ↓
Crypto Detective REST API
          ↓
Canonical Investigation Response
          ↓
Customer Application Policy

The customer's backend should submit the public blockchain address and investigation parameters to Crypto Detective. The Crypto Detective API returns the investigation result, and the customer application determines how that intelligence is used within its own workflow.

Security Requirements

• Keep Crypto Detective API keys on the server.
• Never expose API keys in browser JavaScript or client-side application bundles.
• Never commit API keys to source control.
• Use environment variables or a secure secrets-management system.
• Crypto Detective investigations require public blockchain information only.
• Never send private keys, wallet seed phrases, recovery phrases, or signing credentials to Crypto Detective.
• Treat API authentication credentials as secrets and rotate them if exposure is suspected.

Application Responsibility

Crypto Detective provides investigation and risk intelligence. It does not control the integrating application's business rules.

Applications may use Crypto Detective results to support workflows such as transaction review, risk warnings, compliance processes, fraud prevention, or other application-specific decisions.

The authoritative investigation result comes from the Crypto Detective API. Applications should not recreate Crypto Detective scoring logic locally.

Core Response Fields

| Field | Description | |---|---| | scan.id | Unique investigation identifier. | | scan.address | Address that was investigated. | | scan.chain_selected | Blockchain network used for the investigation. | | scan.asset_symbol | Asset symbol associated with the investigation. | | scan.scan_type | Investigation mode used. | | scan.scanned_at | Investigation timestamp. | | scan.validity | Address validity intelligence. | | scan.classification | Address classification intelligence. | | scan.score | Authoritative Crypto Detective Final Risk Score from 0–100. | | scan.risk_level | low, caution, high, or critical. | | scan.hard_stop_triggered | Indicates whether a Crypto Detective hard stop was triggered. | | scan.hard_stop_code | Hard-stop code when applicable. | | scan.hard_stop_title | Hard-stop title when applicable. | | scan.hard_stop_message | Hard-stop explanation when applicable. | | scan.score_breakdown.final_score_source | Identifies the source of the final score. |

Crypto Detective API v1 may return additional intelligence fields. Applications should tolerate additive response fields rather than rejecting an otherwise valid response.

Risk Levels

| Final Risk Score | Risk Level | |---:|---| | 0 to <30 | low | | 30 to <60 | caution | | 60 to <80 | high | | 80 to 100 | critical |

A critical result does not necessarily mean that a hard stop was triggered. Check scan.hard_stop_triggered when your application needs to distinguish a hard-stop result from another critical-risk result.

Basic Usage

import { CryptoDetectiveClient } from "@cryptodetective/sdk";

const client = new CryptoDetectiveClient({
  apiKey: process.env.CRYPTO_DETECTIVE_API_KEY!,
});

const result = await client.investigate({
  address: "0x...",
  chainSelected: "eth",
  scanMode: "full",
});

console.log(result.scan.score);
console.log(result.scan.risk_level);
console.log(result.scan.hard_stop_triggered);