Migration Guide

Migrating from V2 to V3

This guide covers all changes required to migrate your integration from FailSafe Radar V2 to V3, including breaking changes, new features, and best practices.

V3 Key Improvements

Response time: 15-30s → <10s
Multi-chain: EVM → EVM + BTC + Tron + Solana + TON
AI-enhanced score calibration
Optimized batch processing

Feature Comparison

FeatureV2V3
Response Time15-30 seconds< 10 seconds
Chain SupportEVM onlyEVM, Bitcoin, Tron, Solana, TON, Dogecoin
Intelligence SourcesSingle sourceMultiple proprietary + external
Score CalibrationStaticAI-enhanced with context
Batch ProcessingLimitedOptimized with rate limit handling
Blacklist DetectionBasicReal-time USDT/USDC blacklists
HTTP MethodGET with query paramsPOST with JSON body

Breaking Changes

UnchangedBase URL Remains the Same

Both V2 & V3:https://api.radar.getfailsafe.com

Only the endpoint paths change (e.g., /api/v2/intel → /api/v3/intel)

BreakingHTTP Method: GET → POST

V2 Request

curl -H "x-api-key: YOUR_KEY" \
  "https://api.radar.getfailsafe.com/api/v2/intel?address=0x..."

V3 Request

curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "0x..."}' \
  "https://api.radar.getfailsafe.com/api/v3/intel"

BreakingAuthentication Header Changed

V2:x-api-key: YOUR_API_KEY
V3:Authorization: Bearer YOUR_API_KEY

BreakingResponse Structure Changed

V2 Response

{
  "success": true,
  "data": {
    "address": "0x...",
    "risk_assessment": {
      "risk_score": 45.67,
      "risk_level": "medium"
    },
    "recommendation": "..."
  }
}

V3 Response

{
  "address": "0x...",
  "score": 75,
  "risk_level": "high",
  "confidence": 0.89,
  "flags": {...},
  "recommendation": {
    "action": "REVIEW",
    "summary": "..."
  }
}

ImportantRisk Level Thresholds Changed

V2 Thresholds

CRITICAL80-100
HIGH60-79
MEDIUM30-59
LOW0-29

V3 Thresholds

CRITICAL85-100
HIGH60-84
MEDIUM35-59
LOW15-34
MINIMAL0-14

New V3 Features

Batch Endpoint

Process up to 25 addresses in a single request with /api/v3/intel/batch

Quick Blacklist Check

Fast stablecoin blacklist lookup with /api/v3/blacklist/:address - no auth required

AI-Enhanced Recommendations

Contextual summaries with recommendation.ai_enhanced flag and detailed reasoning

Boolean Flags

Quick boolean checks: flags.sanctioned, flags.blacklisted, flags.threat_actor

Confidence Score

New confidence field (0.0-1.0) indicates assessment reliability

Feedback Endpoint

Submit false positive/negative feedback via /api/v3/feedback to improve model accuracy

Code Migration Examples

JavaScript / TypeScript

V2 Code

const response = await fetch(
  `https://api.radar.getfailsafe.com/api/v2/intel?address=${address}`,
  {
    headers: { 'x-api-key': API_KEY }
  }
);
const data = await response.json();

if (data.success) {
  const riskScore = data.data.risk_assessment.risk_score;
  const riskLevel = data.data.risk_assessment.risk_level;
}

V3 Code

const response = await fetch(
  'https://api.radar.getfailsafe.com/api/v3/intel',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ address })
  }
);
const data = await response.json();

// V3 has flattened structure
const riskScore = data.score;
const riskLevel = data.risk_level;
const action = data.recommendation.action;

// New V3 features
const isSanctioned = data.flags.sanctioned;
const isBlacklisted = data.flags.blacklisted;
const confidence = data.confidence;

Python

V2 Code

import requests

response = requests.get(
    f"https://api.radar.getfailsafe.com/api/v2/intel",
    params={"address": address},
    headers={"x-api-key": API_KEY}
)
data = response.json()

risk_score = data["data"]["risk_assessment"]["risk_score"]

V3 Code

import requests

response = requests.post(
    "https://api.radar.getfailsafe.com/api/v3/intel",
    json={"address": address},
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
)
data = response.json()

risk_score = data["score"]
risk_level = data["risk_level"]
action = data["recommendation"]["action"]

Response Field Mapping

V2 FieldV3 FieldNotes
data.risk_assessment.risk_scorescoreFlattened to top level
data.risk_assessment.risk_levelrisk_levelFlattened to top level
data.recommendationrecommendation.summaryNow an object with action, summary, details
data.priorityrecommendation.actionValues: ALLOW, MONITOR, REVIEW, BLOCK
data.entity.typeentity.typeSame location
data.labelslabelsSame format
N/AflagsNEW: Boolean risk flags
N/AconfidenceNEW: Assessment confidence
N/AsignalsNEW: Contributing factors

Migration Checklist

Update endpoint path from /api/v2/intel to /api/v3/intel
Change HTTP method from GET to POST for intel endpoint
Update auth header from x-api-key to Authorization: Bearer
Update response parsing for flattened structure
Review risk level threshold changes (CRITICAL now 85-100)
Consider using new batch endpoint for multiple addresses
Leverage new flags object for quick boolean checks
Test with non-EVM addresses if supporting multi-chain

Ready to Migrate?

Explore the full V3 API documentation to get started.