🛠️Check

The Check API is a RESTful HTTP endpoint that allows you to verify whether a given IP address is associated with a VPN, proxy, or any other anon ip provider.

Base URL

https://api.antivpn.io

---

Endpoint

GET /v2/check?ip={ip_address}

Parameter	Type	Required	Description
ip	string	Yes	The IPv4 or IPv6 address to check.

---

Authentication

All requests must include a valid API key in the Authorization header using the Bearer scheme.

Authorization: Bearer av_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key Format

• Prefix: av_live_

• Total length: 72 characters (av_live_ + 64 hex characters)

• The hex portion must only contain characters 0-9, a-f, or A-F.

If the key does not match this format, the request will be rejected immediately with a 401 Unauthorized response.

---

Response Format

All responses are returned as application/json.

Successful Response — 200 OK

When the IP address is valid and the lookup succeeds, you will receive:

{
  "success": true,
  "ip": "1.2.3.4",
  "proxy": true,
  "risk_score": 85,
  "processing_time": "12ms",
  "details": {
    "asn": "AS12345",
    "provider": "Example Hosting Inc.",
    "country": "US"
  }
}

Field	Type	Description
success	boolean	Always true for successful lookups.
ip	string	The IP address that was checked.
proxy	boolean	true if the IP is detected as a VPN, proxy, or non-residential anonymizer. false if it appears clean.
risk_score	integer	A numeric score (0–100) indicating the abuse confidence level of the IP. Higher values mean higher risk.
processing_time	string	Server-side latency for the lookup, formatted as milliseconds (e.g. "5ms").
details	object	Additional network information about the IP.
details.asn	string	The Autonomous System Number in AS{number} format (e.g. "AS13335"). "Unknown" if unavailable.
details.provider	string	The name of the network provider or ISP. Falls back to the ASN type if the description is empty.
details.country	string	ISO 3166-1 alpha-2 country code of the IP (e.g. "US", "DE"). "Unknown" if unavailable.

---

Error Responses

All error responses share the same structure:

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable explanation."
}

HTTP Status	error	message	Cause
401	unauthorized	Invalid API key.	Missing Authorization header, invalid format, or unknown key.
400	invalid_ip	Missing or invalid IP address.	The ip query parameter is missing or not a valid IP address.
500	internal_error	Failed to check IP address.	An internal error occurred while looking up the IP.

---

Proxy Detection Logic

An IP is flagged as proxy: true when any of the following conditions are met:

1. Blacklisted IP — The IP is present in the known abuser/blacklist database.

2. Non-residential ASN type — The ASN type is not one of: isp, business, education, government, or unknown.

3. High risk level — The risk level extracted from the abuse score is not one of: very low, low, or elevated (i.e., the IP has a high or very high risk level).

If none of these conditions apply, the IP is considered clean and proxy will be false.

Risk Score

The risk_score is an integer derived from the abuse confidence percentage associated with the IP's ASN data. A score of 0 means no abuse data was found.

---

Rate Limiting & Analytics

• Every request is logged and counted toward your account's usage analytics (approved vs. blocked counts).

• The last_used_at timestamp on your API key is updated (debounced to once per minute).

• If your account exceeds its plan limits, requests may be restricted.

---

Example Requests

cURL

curl -X GET "https://api.antivpn.io/v2/check?ip=1.2.3.4" \
  -H "Authorization: Bearer av_live_your_api_key_here"

Python

import requests

headers = {
    "Authorization": "Bearer av_live_your_api_key_here"
}

response = requests.get(
    "https://api.antivpn.io/v2/check",
    params={"ip": "1.2.3.4"},
    headers=headers
)

data = response.json()

if data["success"]:
    if data["proxy"]:
        print(f"Blocked: {data['ip']} (risk: {data['risk_score']}, provider: {data['details']['provider']})")
    else:
        print(f"Allowed: {data['ip']}")
else:
    print(f"Error: {data['message']}")

JavaScript (Node.js)

const response = await fetch("https://api.antivpn.io/v2/check?ip=1.2.3.4", {
  method: "GET",
  headers: {
    "Authorization": "Bearer av_live_your_api_key_here"
  }
});

const data = await response.json();

if (data.success) {
  console.log(`Proxy: ${data.proxy}, Risk: ${data.risk_score}`);
  console.log(`ASN: ${data.details.asn}, Provider: ${data.details.provider}, Country: ${data.details.country}`);
} else {
  console.error(`Error: ${data.message}`);
}

Java

import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.antivpn.io/v2/check?ip=1.2.3.4"))
    .header("Authorization", "Bearer av_live_your_api_key_here")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

---

Best Practices

• Cache results — If you are checking the same IP multiple times in a short window, cache the result on your side to reduce API calls.

• Validate IPs client-side — Avoid sending obviously invalid IPs (e.g., empty strings, local addresses) to save quota.

• Handle errors gracefully — Always check the success field before reading other fields. Network or server errors can happen.

• Keep your API key secret — Never expose your av_live_ key in client-side code, public repositories, or logs.