API reference

Rent, rotate and extend ipvolt mobile proxies over HTTPS from your prepaid balance: API keys, endpoints, errors, rate limits, idempotency and code examples.

All docs pages

The ipvolt API lets your software and AI agents rent dedicated mobile proxies, rotate their IP and extend them without the dashboard. It spends your prepaid balance. An agent can add funds itself by paying its own USDC on Base, as described under Add funds from your agent below, and you can also add funds in the dashboard.

  • Base URL: https://ipvolt.com/beta/api/v1
  • Payment address for top-ups: https://ipvolt.com/api/v1
  • OpenAPI 3.1 description: openapi.json

v1 is stable. The /beta in the address is historical and says nothing about the API's status. We may add endpoints, response fields and error codes at any time, so ignore the ones your client doesn't know. Anything that would break a working client, such as removing or renaming an endpoint or a field, or changing the address, comes as a new version (/v2), announced under Changes at the end of this page, and v1 keeps running.

Authentication

Send an API key in the Authorization header as Bearer $IPVOLT_API_KEY. Create keys in the dashboard under Account settings → API keys. Each key has a name, an expiry of 30 or 90 days and one of two access levels:

  • read: reads the key, the balance, rentals and extension prices.
  • read_write: can also rent, rotate and extend.
  • usage: a key created before the public API was turned on. It keeps its old access (usage, sessions and order status) and cannot read rentals or the balance; create a new key for that.

A key can also have a daily limit, from $1 to $10,000: the most it may spend on rentals and extensions per UTC day. Without one, the balance is the limit. The key is shown once, when you create it; ipvolt stores only its SHA-256 hash. An account can have up to 10 active keys, and revoking a key stops it at once.

Send keys over HTTPS only: a request that reaches ipvolt over plain HTTP is refused with 403 https_required before the key is read. A missing, wrong, expired or revoked key gets 401 invalid_api_key.

An agent access token from auth.md works too. Reads need its account:read scope; renting, rotating and extending need proxies:buy, and what it spends counts against the agent's own spending cap.

Requests and responses

Requests and responses are JSON. Send POST bodies with Content-Type: application/json (otherwise 415 json_required), at most 8 KiB. Amounts are integers in US cents, such as priceMinor and chargedMinor; GET /balance keeps its decimal-string cents.

Endpoints

Paths are relative to the base URL. read means any API key, or an agent token with account:read; read_write means a read-write key, or an agent token with proxies:buy.

Method and pathNeedsWhat it does
GET /stockNothingCountries, carriers, lengths and prices, and whether each is in stock. Never a stock count.
GET /keyAn API keyThe calling key: its name, access and daily limit, and what it has spent and has left today.
GET /balancereadAvailable and held balance.
GET /rentalsreadActive rentals with their connection details.
GET /rentals/{id}readOne active rental with its connection details.
GET /rentals/{id}/extension-pricereadWhat extending by 1 or 30 days costs now.
POST /rentalsread_writeRent one or more devices. Charges the balance.
POST /rentals/{id}/rotateread_writeAsk for a new IP.
POST /rentals/{id}/extendread_writeExtend an active rental. Charges the balance.

The existing endpoints, such as /catalog, /orders, /orders/{orderId} and /proxies, work as the OpenAPI description says. Any API key can read /balance, /catalog, /orders and /proxies.

GET /stock

No key needed. Answers come from a cache refreshed at most every 30 seconds, so it is cheap to call. The values below are an example:

json
{
  "currency": "USD",
  "observedAt": "2026-11-18T14:40:00.000Z",
  "purchasesOpen": true,
  "offers": [
    {"country": "US", "countryName": "United States", "carrier": "Verizon", "days": 1,
     "priceMinor": 1900, "price": "19.00", "available": true},
    {"country": "US", "countryName": "United States", "carrier": "Verizon", "days": 30,
     "priceMinor": null, "price": null, "available": false}
  ]
}

days is 1 or 30. available: false means sold out right now. includedGb appears on offers that include a data allowance.

GET /key

json
{
  "id": "…",
  "name": "scraper",
  "access": "read_write",
  "dailyLimitMinor": 5000,
  "spentTodayMinor": 1900,
  "remainingTodayMinor": 3100,
  "dayResetsAt": "2026-11-19T00:00:00.000Z",
  "expiresAt": "2027-02-16T14:00:00.000Z"
}

dailyLimitMinor and remainingTodayMinor are null when the key has no daily limit.

GET /rentals and GET /rentals/{id}

A rental looks like this:

json
{
  "id": "…",
  "orderId": "…",
  "status": "active",
  "country": "US", "countryName": "United States", "carrier": "Verizon",
  "endsAt": "2026-11-19T14:00:00.000Z",
  "online": true,
  "externalIp": "…",
  "canRotate": true,
  "canExtend": true,
  "connection": {
    "http":   {"host": "…", "port": 10000, "username": "…", "password": "…"},
    "socks5": {"host": "…", "port": 10001, "username": "…", "password": "…"}
  }
}

connection holds the proxy's username and password, so treat it as a secret. Only the account that owns the rental ever receives it. socks5 is absent on devices without SOCKS5, and includedGb appears on rentals with a data allowance.

GET /rentals answers {"rentals": [ … ]} and leaves out ended rentals. GET /rentals/{id} answers 404 rental_not_found for an unknown id or another account's rental, and 409 rental_ended for your own rental that has ended.

POST /rentals

Send an Idempotency-Key header (8 to 128 letters, digits, _ or -) and one of these two bodies:

json
{"country": "US", "carrier": "Verizon", "days": 1, "maxPriceMinor": 2000, "quantity": 1}
json
{"offerId": "OFFER_ID", "offerVersion": 123456, "quantity": 1}
  • quantity is optional: 1 by default, at most 20.
  • The first body rents the cheapest offer in stock for the country (ISO code), carrier and length. It needs maxPriceMinor, the most you accept per device: if the price rose above it after you read /stock, the request is refused with 409 price_above_max and nothing is charged.
  • The second body rents an exact offer and price version from GET /catalog. If the price version changed, it is refused with 409 offer_changed_refresh.

The answer, for a new order and for a repeated one alike:

json
{
  "orderId": "…",
  "status": "paid",
  "replayed": false,
  "chargedMinor": 1900,
  "currency": "USD",
  "rentalIds": [],
  "poll": "/beta/api/v1/orders/…"
}

The balance is charged when the order is accepted, and the device is usually ready within minutes. Poll GET /orders/{orderId} while its status is paid. Once it is fulfilled, its proxyIds are the new rental ids. If setup fails, the order ends payment_failed and the money goes back to your balance.

POST /rentals/{id}/rotate

No body is needed ({} is fine). The answer is {"rotated": true, "pending": false, "ip": "…", "message": "…"}. pending: true means the rotation is still running; the new IP is usually ready within a minute in GET /rentals/{id}. Rotating too soon gets 429 rotation_cooldown with retryAfterSeconds and a Retry-After header. The dashboard's limits apply: the device's own cooldown and 30 device actions per account per 15 minutes. A device that cannot rotate answers 409 proxy_control_unavailable.

GET /rentals/{id}/extension-price

Add ?days=1 or ?days=30. The answer is {"rentalId": "…", "days": 30, "priceMinor": 13900, "currency": "USD", "endsAt": "…"}: the dashboard's renewal price for this device now. It charges nothing.

POST /rentals/{id}/extend

Send an Idempotency-Key header and a body such as {"days": 1, "maxPriceMinor": 2000}. days is 1 or 30, and maxPriceMinor is required. The extension is priced as in the dashboard and charged only if the price is not above maxPriceMinor. The answer has orderId, status, replayed, chargedMinor, currency, rentalId, days and poll; a repeated request returns the same order without pricing or charging it again. Only an active rental can be extended: an ended one answers 409 rental_ended.

Add funds from your agent

An agent can add to the prepaid balance itself by paying USDC from a wallet it controls. The API key or agent token sent with the payment names the account that is credited, and any key will do, read-only included. The balance cannot be withdrawn, and an agent can never add funds from the customer's money.

Two addresses take top-ups, on purpose. https://ipvolt.com/api/v1 is the payment address: it answers only top-ups, and it is the address /llms.txt gives payment clients. https://ipvolt.com/beta/api/v1/fund is the same top-up inside the API, next to GET /fund/{paymentId}, which reads a payment's status. Both take the same requests and give the same answers; a payment's status is read only under the base URL.

It accepts native USDC on Base mainnet only (network eip155:8453, token 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913): 1 USDC adds $1.00. The wallet signs an EIP-3009 transferWithAuthorization and a payment facilitator submits it to the chain, so the wallet needs USDC but no ETH for gas. The request speaks x402 version 2 and the Machine Payments Protocol (MPP); both carry the same signed transfer.

Each top-up is $1.00 to $500.00, set with ?amountMinor= in US cents (100 to 50000; $10.00 without it). Per account, in any 24 hours: 10 top-ups that were credited or are still being checked, and 30 attempts of any outcome; at most 3 can be open at once. Each client address can send 30 payments per 10 minutes. ipvolt also caps the total of all accounts' top-ups in any 24 hours; past it, top-ups pause and answer 503 x402_daily_limit.

1. Ask for the offer. GET https://ipvolt.com/api/v1?amountMinor=2000, or GET /fund?amountMinor=2000 under the base URL, answers 402 Payment Required with or without a key, and stores nothing. Its PAYMENT-REQUIRED header is base64 JSON (x402 version 2), and accepts[0] in it is the offer: scheme exact, network, amount in USDC base units (amountMinor × 10,000), asset, payTo, maxTimeoutSeconds 300, and in extra the token's EIP-712 name and version. A WWW-Authenticate: Payment header makes the same offer to MPP clients, and the JSON body says it in words.

2. Pay. Repeat the request with the same amountMinor, your API key or agent token in Authorization: Bearer, and the payment. For x402 the payment is a PAYMENT-SIGNATURE header holding base64 JSON, {"x402Version": 2, "accepted": …, "payload": {"authorization": …, "signature": …} }: accepted is accepts[0] unchanged, and the authorization's six fields (from, to, value, validAfter, validBefore, nonce) move exactly amount to payTo. validAfter must be in the past, validBefore 30 seconds to 6 minutes ahead, and nonce 32 random bytes. MPP clients send Payment-Authorization: Payment … instead, with the nonce bound to the challenge. A payment without a valid key or token is refused with 401 and is never read, verified or submitted.

The answer to the payment:

StatusWhat it means
200status: confirming: the transfer was submitted; poll statusUrl. Sending the same signed authorization again returns this payment with replayed: true and never pays twice.
202status: checking: the outcome is not known yet. Do not pay again; poll statusUrl.
402Refused, with the reason in error and a fresh offer. With a paymentId, no transfer was made; statusUrl keeps following it in case the authorization is used on chain after all, and the balance is then still credited. Sign a new authorization to try again.
400The payment could not be read as x402 or MPP, or amountMinor is not 100 to 50000 (invalid_amount).
401No valid API key or agent token. Nothing was read or submitted.
409Three top-ups are still being checked (x402_open_limit), or this authorization was already presented for another account.
429An account or address limit: x402_rate_limit, x402_attempt_limit or rate_limited.
503Top-ups are paused or busy (x402_daily_limit, x402_verify_limit), or the facilitator did not answer (x402_facilitator_unavailable, with a statusUrl).

3. Wait for the credit. The facilitator's answer credits nothing. ipvolt reads the chain itself, through two chain endpoints that must agree, and credits the balance once the transfer is confirmed, usually within a few minutes. Poll statusUrl (GET https://ipvolt.com/beta/api/v1/fund/{paymentId}, with a key or token of the same account) until final is true: credited means the money is on the balance (creditedAt says when), and failed or expired means no transfer was made and nothing was taken.

If a payment is late or unclear. A payment whose transfer ipvolt cannot match within two hours, or whose transfer falls outside the authorization's time, moves to review: it is neither credited nor closed automatically. Write to hello@ipvolt.com with its paymentId.

A top-up is not reversed on chain: what you pay stays on the account as balance, which is service credit. Section 4, Balance, of the Payments and Refunds Policy says when balance is refunded.

You can still add funds yourself in the dashboard, and its Support page lists the top-ups made this way.

Example: top up, then rent

Each version reads the stock, tops up exactly the price of a 1-day US rental, waits for the credit, then rents and prints the connection details. It needs a read-write API key in IPVOLT_API_KEY and, in WALLET_PRIVATE_KEY, the private key of a wallet that holds USDC on Base. Keep both out of prompts and logs. Running it spends USDC, then balance.

cURL

cURL 7.84 or later and jq, plus a few lines of Python with eth-account to sign. Replace PAYMENT_ID, ORDER_ID and RENTAL_ID with the ids from the answers before them.

sh
API=https://ipvolt.com/beta/api/v1
AUTH="Authorization: Bearer $IPVOLT_API_KEY"

# Pick a 1-day US offer and its price in US cents
OFFER=$(curl -sS "$API/stock" | jq -c '[.offers[] | select(.available and .country == "US" and .days == 1)][0]')
CARRIER=$(echo "$OFFER" | jq -r .carrier)
PRICE=$(echo "$OFFER" | jq -r .priceMinor)

# 1. Ask for a top-up of exactly that price. The answer is 402, and its
#    PAYMENT-REQUIRED header holds the offer (base64 JSON, x402 version 2).
TOPUP="$API/fund?amountMinor=$PRICE"
ACCEPTS=$(curl -sS -o /dev/null -w '%header{payment-required}' "$TOPUP" | base64 -d | jq -c '.accepts[0]')

# 2. Sign an EIP-3009 transfer of exactly that amount to that address,
#    with the wallet in WALLET_PRIVATE_KEY (pip install eth-account)
PAYMENT=$(ACCEPTS="$ACCEPTS" python3 - <<'EOF'
import base64, json, os, secrets, time
from eth_account import Account

offer = json.loads(os.environ["ACCEPTS"])
wallet = Account.from_key(os.environ["WALLET_PRIVATE_KEY"])
now = int(time.time())
authorization = {"from": wallet.address, "to": offer["payTo"], "value": offer["amount"],
                 "validAfter": str(now - 60), "validBefore": str(now + 240),
                 "nonce": "0x" + secrets.token_hex(32)}
signed = wallet.sign_typed_data(
    domain_data={"name": offer["extra"]["name"], "version": offer["extra"]["version"],
                 "chainId": int(offer["network"].split(":")[1]),
                 "verifyingContract": offer["asset"]},
    message_types={"TransferWithAuthorization": [
        {"name": "from", "type": "address"}, {"name": "to", "type": "address"},
        {"name": "value", "type": "uint256"}, {"name": "validAfter", "type": "uint256"},
        {"name": "validBefore", "type": "uint256"}, {"name": "nonce", "type": "bytes32"}]},
    message_data={**authorization, "value": int(offer["amount"]),
                  "validAfter": now - 60, "validBefore": now + 240,
                  "nonce": bytes.fromhex(authorization["nonce"][2:])})
payment = {
    "x402Version": 2,
    "accepted": offer,
    "payload": {
        "authorization": authorization,
        "signature": "0x" + bytes(signed.signature).hex(),
    },
}
print(base64.b64encode(json.dumps(payment).encode()).decode())
EOF
)

# 3. Pay: the same request with the payment and your key.
#    200 means "confirming"; keep the paymentId of the answer.
curl -sS "$TOPUP" -H "$AUTH" -H "PAYMENT-SIGNATURE: $PAYMENT"

# 4. Poll the payment until "status" is "credited" (usually within a few minutes)
curl -sS "$API/fund/PAYMENT_ID" -H "$AUTH"

# 5. Rent the offer, paying at most its price, then poll the order
#    while its status is "paid"
curl -sS -X POST "$API/rentals" -H "$AUTH" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"country\": \"US\", \"carrier\": \"$CARRIER\", \"days\": 1, \"maxPriceMinor\": $PRICE}"
curl -sS "$API/orders/ORDER_ID" -H "$AUTH"

# 6. Once the order is "fulfilled", its proxyIds are the rental ids:
#    the rental holds the proxy's host, ports, username and password
curl -sS "$API/rentals/RENTAL_ID" -H "$AUTH"

Python

Standard library plus eth-account (pip install eth-account) to sign.

python
import base64
import json
import os
import secrets
import time
import urllib.error
import urllib.request
import uuid

from eth_account import Account

API = "https://ipvolt.com/beta/api/v1"
wallet = Account.from_key(os.environ["WALLET_PRIVATE_KEY"])  # holds USDC on Base


def call(method, path, body=None, headers=None):
    headers = {
        "Authorization": "Bearer " + os.environ["IPVOLT_API_KEY"],
        "User-Agent": "my-agent/1.0",
        **(headers or {}),
    }
    data = None
    if body is not None:
        data = json.dumps(body).encode()
        headers["Content-Type"] = "application/json"
    request = urllib.request.Request(API + path, data, headers, method=method)
    try:
        with urllib.request.urlopen(request, timeout=30) as response:
            return response.status, response.headers, json.load(response)
    except urllib.error.HTTPError as error:
        return error.code, error.headers, json.load(error)


def check(answer, *expected):
    status, _, data = answer
    if status not in expected:
        reason = data.get("message") or data.get("detail") or ""
        raise RuntimeError(f"{status} {data.get('error')}: {reason}")
    return data


# Pick a 1-day US offer
offers = check(call("GET", "/stock"), 200)["offers"]
offer = next(o for o in offers
             if o["available"] and o["country"] == "US" and o["days"] == 1)

# 1. Ask for a top-up of exactly its price. The answer is 402, and its
#    PAYMENT-REQUIRED header holds the offer (base64 JSON, x402 version 2).
topup = f"/fund?amountMinor={offer['priceMinor']}"
status, headers, _ = call("GET", topup)
if status != 402:
    raise RuntimeError(f"expected 402, got {status}")
accepts = json.loads(base64.b64decode(headers["PAYMENT-REQUIRED"]))["accepts"][0]

# 2. Sign an EIP-3009 transfer of exactly that amount to that address
now = int(time.time())
authorization = {
    "from": wallet.address, "to": accepts["payTo"], "value": accepts["amount"],
    "validAfter": str(now - 60), "validBefore": str(now + 240),
    "nonce": "0x" + secrets.token_hex(32),
}
signed = wallet.sign_typed_data(
    domain_data={"name": accepts["extra"]["name"], "version": accepts["extra"]["version"],
                 "chainId": int(accepts["network"].split(":")[1]),
                 "verifyingContract": accepts["asset"]},
    message_types={"TransferWithAuthorization": [
        {"name": "from", "type": "address"}, {"name": "to", "type": "address"},
        {"name": "value", "type": "uint256"}, {"name": "validAfter", "type": "uint256"},
        {"name": "validBefore", "type": "uint256"}, {"name": "nonce", "type": "bytes32"}]},
    message_data={**authorization, "value": int(accepts["amount"]),
                  "validAfter": now - 60, "validBefore": now + 240,
                  "nonce": bytes.fromhex(authorization["nonce"][2:])},
)
payment = {
    "x402Version": 2,
    "accepted": accepts,
    "payload": {
        "authorization": authorization,
        "signature": "0x" + bytes(signed.signature).hex(),
    },
}

# 3. Pay: the same request with the payment and your key
paid = check(call("GET", topup, headers={
    "PAYMENT-SIGNATURE": base64.b64encode(json.dumps(payment).encode()).decode(),
}), 200, 202)

# 4. Wait until the balance is credited (usually within a few minutes)
while paid["status"] in ("confirming", "checking"):
    time.sleep(15)
    paid = check(call("GET", paid["statusUrl"].removeprefix(API)), 200)
if paid["status"] != "credited":
    raise RuntimeError("top-up " + paid["status"] + ": see " + paid["statusUrl"])

# 5. Rent the offer, paying at most its price.
#    Keep the Idempotency-Key: the same request with it never charges twice.
body = {"country": "US", "carrier": offer["carrier"], "days": 1,
        "maxPriceMinor": offer["priceMinor"]}
rent = check(call("POST", "/rentals", body, {"Idempotency-Key": str(uuid.uuid4())}), 200)

# Poll the order while its status is "paid"
order = check(call("GET", f"/orders/{rent['orderId']}"), 200)
while order["status"] == "paid":
    time.sleep(10)
    order = check(call("GET", f"/orders/{rent['orderId']}"), 200)
if order["status"] != "fulfilled":
    raise RuntimeError("order " + order["status"])

# 6. The order's proxyIds are the rental ids: print the connection details
rental = check(call("GET", f"/rentals/{order['proxyIds'][0]}"), 200)
print(json.dumps(rental["connection"], indent=2))

Node.js

Node.js 18 or later with viem (npm install viem) to sign. Save it as an .mjs file in the folder where viem is installed.

js
import { randomBytes, randomUUID } from 'node:crypto';
import { privateKeyToAccount } from 'viem/accounts';

const API = 'https://ipvolt.com/beta/api/v1';
const wallet = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY); // holds USDC on Base

async function call(method, path, body, headers = {}) {
  const response = await fetch(API + path, {
    method,
    headers: {
      'Authorization': 'Bearer ' + process.env.IPVOLT_API_KEY,
      'User-Agent': 'my-agent/1.0',
      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
      ...headers,
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  return { status: response.status, headers: response.headers, data: await response.json() };
}

function check(answer, ...expected) {
  if (!expected.includes(answer.status)) {
    const reason = answer.data.message ?? answer.data.detail ?? '';
    throw new Error(answer.status + ' ' + answer.data.error + ': ' + reason);
  }
  return answer.data;
}

const wait = ms => new Promise(resolve => setTimeout(resolve, ms));

// Pick a 1-day US offer
const { offers } = check(await call('GET', '/stock'), 200);
const offer = offers.find(o => o.available && o.country === 'US' && o.days === 1);

// 1. Ask for a top-up of exactly its price. The answer is 402, and its
//    PAYMENT-REQUIRED header holds the offer (base64 JSON, x402 version 2).
const topup = '/fund?amountMinor=' + offer.priceMinor;
const asked = await call('GET', topup);
if (asked.status !== 402) throw new Error('expected 402, got ' + asked.status);
const accepts = JSON.parse(Buffer.from(asked.headers.get('payment-required'), 'base64')).accepts[0];

// 2. Sign an EIP-3009 transfer of exactly that amount to that address
const now = Math.floor(Date.now() / 1000);
const authorization = {
  from: wallet.address, to: accepts.payTo, value: accepts.amount,
  validAfter: String(now - 60), validBefore: String(now + 240),
  nonce: '0x' + randomBytes(32).toString('hex'),
};
const signature = await wallet.signTypedData({
  domain: {
    name: accepts.extra.name, version: accepts.extra.version,
    chainId: Number(accepts.network.split(':')[1]), verifyingContract: accepts.asset,
  },
  types: {
    TransferWithAuthorization: [
      { name: 'from', type: 'address' }, { name: 'to', type: 'address' },
      { name: 'value', type: 'uint256' }, { name: 'validAfter', type: 'uint256' },
      { name: 'validBefore', type: 'uint256' }, { name: 'nonce', type: 'bytes32' },
    ],
  },
  primaryType: 'TransferWithAuthorization',
  message: {
    ...authorization, value: BigInt(authorization.value),
    validAfter: BigInt(authorization.validAfter), validBefore: BigInt(authorization.validBefore),
  },
});
const payment = { x402Version: 2, accepted: accepts, payload: { authorization, signature } };

// 3. Pay: the same request with the payment and your key
let paid = check(await call('GET', topup, undefined, {
  'PAYMENT-SIGNATURE': Buffer.from(JSON.stringify(payment)).toString('base64'),
}), 200, 202);

// 4. Wait until the balance is credited (usually within a few minutes)
while (paid.status === 'confirming' || paid.status === 'checking') {
  await wait(15000);
  paid = check(await call('GET', paid.statusUrl.slice(API.length)), 200);
}
if (paid.status !== 'credited') throw new Error('top-up ' + paid.status + ': see ' + paid.statusUrl);

// 5. Rent the offer, paying at most its price.
//    Keep the Idempotency-Key: the same request with it never charges twice.
const rent = check(await call('POST', '/rentals', {
  country: 'US', carrier: offer.carrier, days: 1, maxPriceMinor: offer.priceMinor,
}, { 'Idempotency-Key': randomUUID() }), 200);

// Poll the order while its status is "paid"
let order = check(await call('GET', '/orders/' + rent.orderId), 200);
while (order.status === 'paid') {
  await wait(10000);
  order = check(await call('GET', '/orders/' + rent.orderId), 200);
}
if (order.status !== 'fulfilled') throw new Error('order ' + order.status);

// 6. The order's proxyIds are the rental ids: print the connection details
const rental = check(await call('GET', '/rentals/' + order.proxyIds[0]), 200);
console.log(JSON.stringify(rental.connection, null, 2));

Examples

Each example runs the same steps: list stock, rent, poll the order, list rentals, rotate and extend. They read your key from the IPVOLT_API_KEY environment variable. The rent and extend steps charge your balance.

cURL

sh
API=https://ipvolt.com/beta/api/v1
AUTH="Authorization: Bearer $IPVOLT_API_KEY"

# List stock (no key needed)
curl -sS "$API/stock"

# Rent one device for 1 day, paying at most $20.00.
# Keep RENT_KEY: sending the same request with it again never charges twice.
RENT_KEY=$(uuidgen)
curl -sS -X POST "$API/rentals" -H "$AUTH" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $RENT_KEY" \
  -d '{"country": "US", "carrier": "Verizon", "days": 1, "maxPriceMinor": 2000}'

# Poll the order while its status is "paid"
curl -sS "$API/orders/ORDER_ID" -H "$AUTH"

# List active rentals with their connection details
curl -sS "$API/rentals" -H "$AUTH"

# Ask for a new IP
curl -sS -X POST "$API/rentals/RENTAL_ID/rotate" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{}'

# Extend by 1 day, paying at most $20.00
EXTEND_KEY=$(uuidgen)
curl -sS -X POST "$API/rentals/RENTAL_ID/extend" -H "$AUTH" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $EXTEND_KEY" \
  -d '{"days": 1, "maxPriceMinor": 2000}'

Replace ORDER_ID and RENTAL_ID with the ids from the previous answers.

Python

Standard library only. Set the User-Agent to the name of your software.

python
import json
import os
import time
import urllib.error
import urllib.request
import uuid

API = "https://ipvolt.com/beta/api/v1"


def call(method, path, body=None, idempotency_key=None):
    headers = {
        "Authorization": "Bearer " + os.environ["IPVOLT_API_KEY"],
        "User-Agent": "my-agent/1.0",
    }
    data = None
    if body is not None:
        data = json.dumps(body).encode()
        headers["Content-Type"] = "application/json"
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    request = urllib.request.Request(API + path, data, headers, method=method)
    try:
        with urllib.request.urlopen(request, timeout=30) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:
        problem = json.load(error)
        raise RuntimeError(f"{error.code} {problem['error']}: {problem['message']}")


# List stock
offers = call("GET", "/stock")["offers"]
offer = next(o for o in offers
             if o["available"] and o["country"] == "US" and o["days"] == 1)

# Rent one device, paying at most the price just read.
# Keep rent_key: sending the same request with it again never charges twice.
rent_key = str(uuid.uuid4())
body = {"country": "US", "carrier": offer["carrier"], "days": 1,
        "maxPriceMinor": offer["priceMinor"]}
rent = call("POST", "/rentals", body, rent_key)

# Poll the order while its status is "paid"
order = call("GET", f"/orders/{rent['orderId']}")
while order["status"] == "paid":
    time.sleep(10)
    order = call("GET", f"/orders/{rent['orderId']}")

# List active rentals; the order's proxyIds are the new rental ids
rentals = call("GET", "/rentals")["rentals"]
rental = next(r for r in rentals if r["id"] in order["proxyIds"])
rental_path = f"/rentals/{rental['id']}"

# Ask for a new IP
print(call("POST", rental_path + "/rotate", {}))

# Extend by 1 day, paying at most the current extension price
price = call("GET", rental_path + "/extension-price?days=1")
extend_key = str(uuid.uuid4())
call("POST", rental_path + "/extend",
     {"days": 1, "maxPriceMinor": price["priceMinor"]}, extend_key)

Node.js

Node.js 18 or later, saved as an .mjs file. Set the User-Agent to the name of your software.

js
import { randomUUID } from 'node:crypto';

const API = 'https://ipvolt.com/beta/api/v1';

async function call(method, path, body, idempotencyKey) {
  const headers = {
    'Authorization': 'Bearer ' + process.env.IPVOLT_API_KEY,
    'User-Agent': 'my-agent/1.0',
  };
  if (body !== undefined) headers['Content-Type'] = 'application/json';
  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
  const response = await fetch(API + path, {
    method, headers, body: body === undefined ? undefined : JSON.stringify(body),
  });
  const data = await response.json();
  if (!response.ok) {
    throw new Error(response.status + ' ' + data.error + ': ' + data.message);
  }
  return data;
}

// List stock
const { offers } = await call('GET', '/stock');
const offer = offers.find(o => o.available && o.country === 'US' && o.days === 1);

// Rent one device, paying at most the price just read.
// Keep rentKey: sending the same request with it again never charges twice.
const rentKey = randomUUID();
const rent = await call('POST', '/rentals', {
  country: 'US', carrier: offer.carrier, days: 1, maxPriceMinor: offer.priceMinor,
}, rentKey);

// Poll the order while its status is "paid"
let order = await call('GET', '/orders/' + rent.orderId);
while (order.status === 'paid') {
  await new Promise(resolve => setTimeout(resolve, 10000));
  order = await call('GET', '/orders/' + rent.orderId);
}

// List active rentals; the order's proxyIds are the new rental ids
const { rentals } = await call('GET', '/rentals');
const rental = rentals.find(r => order.proxyIds.includes(r.id));
const rentalPath = '/rentals/' + rental.id;

// Ask for a new IP
console.log(await call('POST', rentalPath + '/rotate', {}));

// Extend by 1 day, paying at most the current extension price
const price = await call('GET', rentalPath + '/extension-price?days=1');
const extendKey = randomUUID();
await call('POST', rentalPath + '/extend',
  { days: 1, maxPriceMinor: price.priceMinor }, extendKey);

Idempotency

POST /rentals and POST /rentals/{id}/extend need an Idempotency-Key. It belongs to your account: repeating a request with the same key returns the same order and never charges again, whichever of your keys or agent tokens sends it, and whether the first attempt succeeded, failed or is still running. The same key with a different body is refused with 409 intent_conflict. A key stays with its order, so it cannot be used for a new rental. Use a new random value, such as a UUID, for each new order, and the same value when you retry it.

Daily limit

A key's daily limit is checked before an order is placed, against what the key has committed since 00:00 UTC: every rental and extension it placed that day, except orders whose money went back to the balance. Requests on one key are handled one at a time, so two cannot both pass the check. A request that would go over is refused with 409 daily_limit_exceeded, and nothing is charged. GET /key shows what is left today.

Errors

Every error is JSON with a stable error code, a message for people and, where they help, more fields:

json
{
  "error": "insufficient_balance",
  "message": "Your balance is $3.00 short for this order. Add funds and try again.",
  "requiredMinor": 1900,
  "availableMinor": 1600,
  "missingMinor": 300
}
StatuserrorWhen
400invalid_requestThe body or query is not as documented.
400idempotency_key_required, invalid_idempotency_keyA charging request without a valid Idempotency-Key.
400max_price_requiredThe country body or an extension without maxPriceMinor.
400invalid_jsonThe body is not a JSON object.
401invalid_api_keyThe key is missing, wrong, expired or revoked.
403read_only_api_keyA read-only key tried to rent, rotate or extend.
403usage_only_api_keyA key created before the public API asked for rentals, the balance or other account data.
403insufficient_scopeAn agent token without the scope.
403https_requiredThe request came over plain HTTP.
404not_foundUnknown path.
404rental_not_foundUnknown rental, or another account's.
409rental_endedYour rental has ended.
409stock_unavailableSold out for that country, carrier and length.
409offer_changed_refreshThe offer's price version changed.
409price_above_maxThe current price is above maxPriceMinor. Extra fields: priceMinor, maxPriceMinor.
409insufficient_balanceThe balance is too low. Extra fields: requiredMinor, availableMinor, missingMinor.
409daily_limit_exceededThe key's daily limit would be exceeded. Extra fields: dailyLimitMinor, spentTodayMinor, remainingTodayMinor, resetsAt.
409spend_cap_exceededAn agent token's cap would be exceeded. Extra fields: remainingMinor.
409intent_conflictAn idempotency key reused with a different request.
409renewal_pendingAn extension of this rental is already being processed.
409proxy_control_unavailableThe device does not support the action.
415json_requiredA POST without Content-Type: application/json.
429rotation_cooldownRotated too recently. Extra fields: retryAfterSeconds.
429try_again_laterA rate limit.
503balance_purchases_unavailable, supplier_unavailable, supplier_funding_unavailable, temporarily_unavailableRenting is not possible right now. Nothing was charged.

Rate limits

Requests are counted in fixed 15-minute windows:

  • 900 requests per API key.
  • Per client IP address, with IPv6 counted by /64 network: 1,800 requests with a key, and 300 to GET /stock.
  • 30 rent and extend requests per key. Each account also has the dashboard's limits: 30 purchases, 30 renewals, 30 device actions and 240 device reads.

Over a limit, the answer is 429 try_again_later.

Activity log

Each request made with an API key is recorded for that key: the time, the action, the HTTP status, the result (ok or the error code) and, for rentals and extensions, the amount charged and the order id. The log never holds the key, proxy credentials, request bodies or addresses. Account settings → API keys → Activity shows a key's last 100 entries. Entries are deleted after 90 days.

Acceptable use

The Acceptable Use Policy applies to everything done through the API.

Changes

  • 18 November 2026: this reference is published, with stock, keys, rentals, rotation and extensions.
  • 18 November 2026: the API answers only at https://ipvolt.com/beta/api/v1. Requests to /dashboard/api/v1, which the dashboard's own API page showed until then, are redirected there with 308, which keeps the method and the body.
  • 18 November 2026: Add funds from your agent: what the USDC top-up accepts, its limits and answers, and an example that tops up and then rents.

Plug in your first proxy.

Mobile from $9 a day. Residential from $0.60 per GB, in packs from $5.