{ API Reference }

Build with the ipvult API

Automate proxy purchasing, renewal, and management directly from your application. The API supports every proxy type — ISP, Static Residential, Premium Static Residential, and Rotating Residential — through a single, consistent interface.

Base URL: https://ipvult.com/api

Authentication

All API requests require an API key passed in the Authorization header. Generate your key from your dashboard under API settings.

curl https://ipvult.com/api/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
res = requests.get("https://ipvult.com/api/balance", headers=headers)
print(res.json())

const res = await fetch("https://ipvult.com/api/balance", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await res.json();

$ch = curl_init("https://ipvult.com/api/balance");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Rate Limits

API requests are limited to 120 requests per minute per API key. Exceeding this returns a 429 status code. Need a higher limit? Contact us via the Enterprise plan.

More documentation is coming soon This page currently covers our Premium Residential SOCKS5 API. Dedicated API docs for ISP, Static Residential, Premium Static Residential, and Rotating Residential plans will be released shortly — check back soon or contact us if you need early access.

Quick Start

Three steps to your first proxy purchase via API.

1

Generate API key

Create one from your dashboard under API settings.

2

Find a proxy

Call GET /api/proxies to browse available IPs.

3

Purchase it

Call POST /api/buy with the proxy ID and duration.

Libraries & SDKs

Official wrappers and community libraries to speed up integration.

Python SDK

pip install ipvult

Node.js SDK

npm i ipvult-sdk

PHP SDK

composer req ipvult/sdk

Postman Collection

Import collection →

GET List Proxies

Retrieve available proxies with optional filters for country, ISP, quality score, and more.

Parameter	Type	Description
`country`	string	ISO country code (e.g. US, GB)
`page`	int	Page number, default 1
`per_page`	int	Results per page, max 50
`iqs_level`	int	Max IPQualityScore (0-100)

curl "https://ipvult.com/api/proxies?country=US&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

params = {"country": "US", "per_page": 10}
headers = {"Authorization": "Bearer YOUR_API_KEY"}
res = requests.get("https://ipvult.com/api/proxies", params=params, headers=headers)
print(res.json())

const params = new URLSearchParams({ country: "US", per_page: 10 });
const res = await fetch(`https://ipvult.com/api/proxies?${params}`, {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await res.json();

$ch = curl_init("https://ipvult.com/api/proxies?country=US&per_page=10");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_API_KEY"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);

Response

{
  "success": true,
  "page": 1,
  "total": 40409,
  "proxies": [
    {
      "Id": "209",
      "ip": "98.127.*.*",
      "country": "US",
      "city": "Great Falls",
      "ISP": "Spectrum",
      "ipqualityscore": "100",
      "scamalytics": "0",
      "price_shared": "0.56",
      "price_private": "0.94"
    }
  ]
}

POST Calculate Price

Get the price for a proxy before purchasing, based on duration, quality score, and proxy type.

Parameter	Type	Description
`hours`	int	Duration in hours
`score`	int	IPQualityScore of the target proxy
`scamalytics`	int	Scamalytics score of the target proxy
`private`	bool	Whether to calculate private rate

curl -X POST https://ipvult.com/api/calculate_price \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hours":24,"score":100,"scamalytics":12,"private":false}'

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
body = {"hours": 24, "score": 100, "scamalytics": 12, "private": False}
res = requests.post("https://ipvult.com/api/calculate_price", json=body, headers=headers)
print(res.json())

const res = await fetch("https://ipvult.com/api/calculate_price", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ hours: 24, score: 100, scamalytics: 12, private: false })
});
const data = await res.json();

$ch = curl_init("https://ipvult.com/api/calculate_price");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "hours" => 24, "score" => 100, "scamalytics" => 12, "private" => false
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);

POST Buy Proxy

Purchase a proxy and receive connection credentials instantly. Funds are deducted from your wallet balance.

Parameter	Type	Description
`proxy_id`	string	ID of the proxy to purchase
`hours`	int	Duration in hours
`private`	bool	Purchase as Private Exclusive

curl -X POST https://ipvult.com/api/buy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy_id":"209","hours":24,"private":false}'

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
body = {"proxy_id": "209", "hours": 24, "private": False}
res = requests.post("https://ipvult.com/api/buy", json=body, headers=headers)
proxy = res.json()
print(proxy["proxy_ip"], proxy["proxy_port"])

const res = await fetch("https://ipvult.com/api/buy", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ proxy_id: "209", hours: 24, private: false })
});
const proxy = await res.json();

$ch = curl_init("https://ipvult.com/api/buy");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "proxy_id" => "209", "hours" => 24, "private" => false
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$proxy = json_decode(curl_exec($ch), true);

POST Renew Proxy

Extend an existing proxy's expiry by adding more hours.

curl -X POST https://ipvult.com/api/renew \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy_id":"209","hours":24}'

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
body = {"proxy_id": "209", "hours": 24}
res = requests.post("https://ipvult.com/api/renew", json=body, headers=headers)
print(res.json())

const res = await fetch("https://ipvult.com/api/renew", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ proxy_id: "209", hours: 24 })
});
const data = await res.json();

$ch = curl_init("https://ipvult.com/api/renew");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["proxy_id" => "209", "hours" => 24]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);

POST Refund Proxy

Request a refund for a non-working proxy. Only available for offline proxies — see our refund policy for full rules.

curl -X POST https://ipvult.com/api/refund \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"334229"}'

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
body = {"order_id": "334229"}
res = requests.post("https://ipvult.com/api/refund", json=body, headers=headers)
print(res.json())

const res = await fetch("https://ipvult.com/api/refund", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ order_id: "334229" })
});
const data = await res.json();

$ch = curl_init("https://ipvult.com/api/refund");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["order_id" => "334229"]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);

GET Get Balance

Check your current wallet balance.

curl https://ipvult.com/api/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
res = requests.get("https://ipvult.com/api/balance", headers=headers)
print(res.json()["balance"])

const res = await fetch("https://ipvult.com/api/balance", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const { balance } = await res.json();

$ch = curl_init("https://ipvult.com/api/balance");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_API_KEY"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
echo $data['balance'];

Error Codes

All errors return a JSON body with success: false and an error message.

Status	Meaning
`401`	Invalid or missing API key
`402`	Insufficient wallet balance
`404`	Proxy or order not found
`429`	Rate limit exceeded
`500`	Internal server error — contact support

Webhooks

Configure a webhook URL in your dashboard to receive real-time notifications for proxy expiry, auto-refunds, and renewal events. Webhook payloads are sent as POST requests with a JSON body matching the event type.

{
  "event": "proxy.expired",
  "proxy_id": "209",
  "order_id": "334229",
  "timestamp": "2026-06-30T12:00:00Z"
}

Available events: proxy.purchased, proxy.expired, proxy.refunded, proxy.renewed

Best Practices

Cache proxy lists locally Avoid calling GET /api/proxies on every request — cache results for a few minutes to stay well under rate limits.

Always check quality scores before purchase Filter by iqs_level to avoid buying flagged IPs that may trigger CAPTCHAs.

Handle 402 errors gracefully Check wallet balance before bulk purchases to avoid partial-batch failures mid-loop.

Use webhooks instead of polling Subscribe to proxy.expired events rather than repeatedly checking expiry status.