FraudRadar API Documentation

{
  "status": "success",
  "data": {
    "ip": "8.8.8.8",
    "decision": "allow",          // allow | review | challenge | block
    "risk": {
      "score": 5,                 // 0-100 (higher = riskier)
      "level": "minimal",         // minimal | low | medium | high | critical
      "confidence": "high"        // high | medium | low
    },
    "connection_profile": {
      "type": "datacenter",       // residential | datacenter | mobile
      "isp": "Google LLC",
      "asn": 15169,
      "flags": {
        "vpn": false,
        "tor": false,
        "proxy": false,
        "datacenter": true,
        "proxy_type": ""          // VPN | TOR | DCH | PUB | WEB | RES | ...
      }
    },
    "geo": {
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "city": "Mountain View",
      "timezone": "America/Los_Angeles",
      "accuracy_km": 5
    },
    "explanation": ["IP belongs to Google datacenter"]
  }
}

# requirements.txt: requests>=2.28.0

import requests
from typing import Optional
import os

class IPHubClient:
    def __init__(self, api_key: Optional[str] = None):
        self.api_key = api_key or os.getenv("IPHUB_API_KEY")
        self.base_url = "https://api.iphub.live/api/v1"

    def check_ip(self, ip: str, context: str = None) -> dict:
        """
        Check IP risk score.

        Args:
            ip: IPv4 address to check
            context: Optional context (checkout, login, signup)

        Returns:
            API response dict with risk data
        """
        params = {"ip": ip}
        if context:
            params["context"] = context

        response = requests.get(
            f"{self.base_url}/ip/check",
            params=params,
            headers={"X-API-Key": self.api_key},
            timeout=5
        )
        response.raise_for_status()
        return response.json()

    def should_block(self, ip: str) -> bool:
        """Quick check if IP should be blocked."""
        result = self.check_ip(ip)
        return result["data"]["decision"] == "block"

# Usage
client = IPHubClient("hub_live_your_api_key")

# Check single IP
result = client.check_ip("8.8.8.8", context="checkout")
print(f"Decision: {result['data']['decision']}")
print(f"Is VPN: {result['data']['connection_profile']['flags']['vpn']}")

# Quick block check
if client.should_block(user_ip):
    return {"error": "Access denied"}

// npm install node-fetch (for Node.js < 18)

class IPHubClient {
  constructor(apiKey) {
    this.apiKey = apiKey || process.env.IPHUB_API_KEY;
    this.baseUrl = "https://api.iphub.live/api/v1";
  }

  async checkIP(ip, context = null) {
    const params = new URLSearchParams({ ip });
    if (context) params.append("context", context);

    const response = await fetch(
      `${this.baseUrl}/ip/check?${params}`,
      {
        headers: { "X-API-Key": this.apiKey },
        signal: AbortSignal.timeout(5000)
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error?.message || `HTTP ${response.status}`);
    }

    return response.json();
  }

  async shouldBlock(ip) {
    const result = await this.checkIP(ip);
    return result.data.decision === "block";
  }
}

// Usage
const client = new IPHubClient("hub_live_your_api_key");

// Express.js middleware example
app.use(async (req, res, next) => {
  const ip = req.ip || req.headers["x-forwarded-for"];

  try {
    const result = await client.checkIP(ip, "api");
    req.riskScore = result.data.risk.score;
    req.isVPN = result.data.connection_profile.flags.vpn;

    if (result.data.decision === "block") {
      return res.status(403).json({ error: "Access denied" });
    }
    next();
  } catch (error) {
    console.error("IP check failed:", error);
    next(); // Fail open
  }
});

<?php
// composer require guzzlehttp/guzzle (optional, for better HTTP client)

class IPHubClient {
    private $apiKey;
    private $baseUrl = "https://api.iphub.live/api/v1";

    public function __construct($apiKey = null) {
        $this->apiKey = $apiKey ?: getenv("IPHUB_API_KEY");
    }

    public function checkIP($ip, $context = null) {
        $params = ["ip" => $ip];
        if ($context) {
            $params["context"] = $context;
        }

        $url = $this->baseUrl . "/ip/check?" . http_build_query($params);

        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 5,
            CURLOPT_HTTPHEADER => [
                "X-API-Key: " . $this->apiKey
            ]
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200) {
            throw new Exception("API Error: HTTP " . $httpCode);
        }

        return json_decode($response, true);
    }

    public function shouldBlock($ip) {
        $result = $this->checkIP($ip);
        return $result["data"]["decision"] === "block";
    }
}

// Usage
$client = new IPHubClient("hub_live_your_api_key");

// Laravel middleware example
class CheckIPRisk {
    public function handle($request, Closure $next) {
        $client = new IPHubClient();
        $ip = $request->ip();

        try {
            $result = $client->checkIP($ip, "api");
            $request->attributes->set("risk_score", $result["data"]["risk"]["score"]);
            $request->attributes->set("is_vpn", $result["data"]["connection_profile"]["flags"]["vpn"]);

            if ($result["data"]["decision"] === "block") {
                return response()->json(["error" => "Access denied"], 403);
            }
        } catch (Exception $e) {
            Log::warning("IP check failed: " . $e->getMessage());
        }

        return $next($request);
    }
}

# Basic GET request
curl "https://api.iphub.live/api/v1/ip/check?ip=8.8.8.8" \
  -H "X-API-Key: hub_live_your_api_key"

# GET with query param auth
curl "https://api.iphub.live/api/v1/ip/check?ip=8.8.8.8&key=hub_live_your_api_key"

# POST request with context
curl -X POST "https://api.iphub.live/api/v1/ip/check" \
  -H "X-API-Key: hub_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"ip": "8.8.8.8", "context": "checkout"}'

# With custom request ID for tracing
curl "https://api.iphub.live/api/v1/ip/check?ip=8.8.8.8" \
  -H "X-API-Key: hub_live_your_api_key" \
  -H "X-Request-ID: my-trace-id-123"