Getting Started

Complete Integration Guide

Everything you need to integrate Predax into your application, from signup to production deployment.

Sign Up and Get Your API Key

Create a free account at predax.io/register. You'll get 1,000 requests per day free (5,000/month) with no credit card required.

After signing up:

Navigate to your dashboard
Click "API Keys" in the sidebar
Copy your API key (starts with prdx_...)
Store it securely (environment variables, secrets manager)

Make Your First API Request

Test your API key with a simple cURL command. Replace YOUR_API_KEY with your actual key.

cURL Example

curl -i https://predax.io/api/v1/check/ip \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip":"8.8.8.8"}'

Python Example

import requests

response = requests.post(
    'https://predax.io/api/v1/check/ip',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'ip': '8.8.8.8'}
)

data = response.json()
print(f"Risk Score: {data['classification']['risk_score']}")
print(f"Risk Level: {data['classification']['risk_level']}")

Node.js Example

const response = await fetch('https://predax.io/api/v1/check/ip', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ ip: '8.8.8.8' })
});

const data = await response.json();
console.log(`Risk Score: ${data.classification.risk_score}`);
console.log(`Risk Level: ${data.classification.risk_level}`);

PHP Example

<?php
$ch = curl_init('https://predax.io/api/v1/check/ip');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['ip' => '8.8.8.8']));

$response = curl_exec($ch);
$data = json_decode($response, true);

echo "Risk Score: " . $data['classification']['risk_score'] . "\n";
echo "Risk Level: " . $data['classification']['risk_level'] . "\n";
?>

Understand the Response

Every response contains rich threat intelligence data. Here are the most important fields:

Risk Score & Level

classification.risk_scoreclassification.risk_level

Score ranges from 0–100. Level is derived from the score: minimal (0–19), low (20–49), medium (50–79), high (80–100).

The score is not a probability — it is a weighted sum of the signals detected on the IP. By default a Tor exit node alone scores 85, an anonymous proxy 75, a VPN 45, and a plain datacenter IP 35. An IP carrying several signals (e.g. VPN + bad reputation) scores higher than any single signal. That means which flags fired usually matters more than the exact number: a 35 that is “datacenter only” is routine hosting traffic, while a 75 that is “anonymous proxy” deserves scrutiny.

Classification Flags

classification.is_proxyclassification.is_vpnclassification.is_torclassification.is_datacenterclassification.is_crawlerclassification.is_malicious

Boolean flags — but they are not all “threats”, and they are not mutually exclusive:

is_tor / is_malicious — strong abuse signals. Tor exits and IPs on active threat feeds are almost never legitimate customers.
is_proxy — open/anonymous proxies; a strong fraud signal.
is_vpn — anonymized, but a large share of ordinary consumers use VPNs. Blocking on this flag alone will block real users; prefer monitoring or extra verification.
is_datacenter — a hosting fact, not a verdict. It catches bots and scrapers, but also monitoring tools, corporate egress, and search engines. Most VPN IPs are also datacenter IPs, so if you act on datacenter first you will mislabel VPN traffic.
is_crawler — a positive signal: a verified search-engine crawler (Googlebot, Bingbot). Never block these, or you risk deindexing.

classification.reasons lists why each flag was set ({flag, source, detail?}), and classification.confidence gives per-signal confidence — useful when you need to explain a decision to a customer or in a manual review queue.

Network & Location

network.asnnetwork.as_namelocation.country_codelocation.city

Network ownership and geographic location data

Debugging & Support

meta.request_idX-Request-ID header

Use these IDs when contacting support for faster resolution

Monitor Your Quota Usage

Every API response includes quota headers. Use them to track usage and avoid hitting limits.

Daily Quota Headers:

X-Quota-Limit-DayYour daily limit

X-Quota-Used-TodayRequests used today

X-Quota-Remaining-TodayRequests remaining today

X-Quota-Reset-DailyNext reset timestamp

Monthly Quota Headers:

X-Quota-Limit-MonthYour monthly limit

X-Quota-Used-MonthRequests used this month

X-Quota-Remaining-MonthRequests remaining this month

How billing actually works:

Quotas are per account, not per key — usage from all your active API keys counts against the same daily and monthly limits.
Only successful (2xx) checks are billed. If we return an error, you are not charged.
Re-checking the same IP with the same key within 5 minutes is not billed. The X-Quota-Billed response header is 1 when the request counted against your quota and 0 when it was a free repeat. (Bulk requests always bill every IP.)
At the limit the API returns HTTP 402 with an explanation in detail. The daily quota resets at 00:00 UTC (see X-Quota-Reset-Daily); the monthly quota resets on the 1st.

Example: Reading Headers in Python

response = requests.post(...)

# Check quota before each request
remaining_today = int(response.headers.get('X-Quota-Remaining-Today', 0))
remaining_month = int(response.headers.get('X-Quota-Remaining-Month', 0))

if remaining_today < 100:
    print("Warning: Low on daily quota!")
if remaining_month < 1000:
    print("Warning: Low on monthly quota!")

Implement Risk-Based Logic

Use the risk score to make intelligent decisions. Here are common patterns:

Block vs. monitor — how to choose:

Start in monitor mode. Log the score and flags for a week of real traffic before blocking anything. You will learn what your legitimate audience looks like — some sites have 20%+ VPN readership, others nearly none.
Match the action to the cost of being wrong. A wrongly blocked visitor never files a support ticket — they just leave. Reserve hard blocks for signals that are almost never legitimate in your context (Tor at checkout, known-malicious IPs); use step-up verification (MFA, email confirmation, manual review) for the ambiguous middle.
Act on flags, not just the number. With default weights the score distribution is driven by which signals fired, so “block above N” is a blunt instrument. “Block Tor and malicious, challenge proxies, monitor VPN and datacenter” is usually a better policy than any single threshold.
Never block is_crawler IPs — verified search-engine crawlers come from datacenter ranges and blocking them removes you from search results.

Example: Tiered Response

def handle_user_action(ip_address, user_id):
    result = check_ip(ip_address)
    risk_score = result['classification']['risk_score']

    if risk_score >= 80:
        # Critical risk - block immediately
        return "BLOCK"

    elif risk_score >= 60:
        # High risk - require additional verification
        require_2fa(user_id)
        log_suspicious_activity(ip_address, risk_score)
        return "CHALLENGE"

    elif risk_score >= 40:
        # Medium risk - monitor closely
        log_for_review(ip_address, risk_score)
        return "MONITOR"

    else:
        # Low risk - allow
        return "ALLOW"

Example: Check Specific Threats

classification = result['classification']

# Block VPNs and proxies on payment pages
if classification.get('is_vpn') or classification.get('is_proxy'):
    if current_page == '/checkout':
        return redirect_to_verification()

# Allow Tor on public pages but require extra verification
if classification.get('is_tor'):
    if requires_authentication:
        require_2fa()

# Flag datacenter IPs for fraud review
if classification.get('is_datacenter'):
    flag_for_manual_review(user_id, "Datacenter IP detected")

Production Best Practices

Follow these guidelines for reliable production deployment:

✓ Use Timeouts

Set a 1-3 second timeout on API requests. Don't let a slow API call block your users.

requests.post(..., timeout=2.0)

✓ Implement Retries

Retry on 429 (rate limit) and 5xx errors with exponential backoff.

✓ Cache Results

Cache IP checks for 24 hours to reduce API calls and improve response time.

✓ Log Request IDs

Always log the X-Request-ID header for debugging and support requests.

✓ Handle Errors Gracefully

If the API is down or quota exceeded, fail open (allow the request) rather than blocking users.

Next Steps

API Reference

Complete endpoint documentation

Best Practices

Advanced patterns and optimization

SDK Reference

Official Python SDK

API Playground

Test the API in your browser

← Docs Home Best Practices →