API ipvolt позволяет вашим программам и ИИ-агентам арендовать выделенные мобильные прокси, менять их IP и продлевать аренду без панели управления. Оплата идёт с вашего предоплаченного баланса. Агент может сам пополнить его своими USDC в сети Base, как описано ниже в разделе «Пополнение баланса агентом», а вы можете пополнить баланс и в панели управления.
- Базовый URL:
https://ipvolt.com/beta/api/v1 - Адрес оплаты для пополнений:
https://ipvolt.com/api/v1 - Описание OpenAPI 3.1: openapi.json
v1 стабильна. /beta в адресе — историческое название и ничего не говорит о статусе API. Мы можем в любой момент добавлять эндпоинты, поля ответов и коды ошибок, поэтому пропускайте те, которых ваш клиент не знает. Всё, что сломало бы работающий клиент, например удаление или переименование эндпоинта или поля либо смена адреса, выйдет новой версией (/v2), о которой мы объявим в разделе «Изменения» в конце этой страницы, а v1 продолжит работать.
Аутентификация
Передавайте API-ключ в заголовке Authorization в виде Bearer $IPVOLT_API_KEY. Ключи создаются в панели управления в разделе Account settings → API keys («Настройки аккаунта → API-ключи»). У каждого ключа есть название, срок действия 30 или 90 дней и один из двух уровней доступа:
read: читает данные ключа, баланс, аренды и цены продления.read_write: также может арендовать, менять IP и продлевать.usage: ключ, созданный до запуска публичного API. Он сохраняет прежний доступ (использование, сессии и статус заказов) и не читает аренды и баланс; для этого создайте новый ключ.
Для ключа можно задать дневной лимит от $1 до $10 000: максимальную сумму, которую он может потратить на аренду и продление за сутки по UTC. Без лимита ограничением служит баланс. Ключ показывается один раз, при создании; ipvolt хранит только его хеш SHA-256. В аккаунте может быть до 10 активных ключей, а отозванный ключ сразу перестаёт работать.
Отправляйте ключи только по HTTPS: запрос, пришедший в ipvolt по обычному HTTP, отклоняется с 403 https_required ещё до чтения ключа. Если ключ отсутствует, неверен, истёк или отозван, ответ — 401 invalid_api_key.
Подходит и токен доступа агента, полученный через auth.md. Для чтения нужна его область account:read; для аренды, смены IP и продления — proxies:buy, а его расходы учитываются в собственном лимите расходов агента.
Запросы и ответы
Запросы и ответы передаются в JSON. Тело POST-запроса отправляйте с Content-Type: application/json (иначе 415 json_required), не больше 8 КиБ. Суммы — целые числа в центах США, например priceMinor и chargedMinor; GET /balance по-прежнему возвращает центы десятичной строкой.
Эндпоинты
Пути указаны относительно базового URL. read — любой API-ключ или токен агента с account:read; read_write — ключ с доступом на чтение и запись или токен агента с proxies:buy.
| Метод и путь | Что нужно | Что делает |
|---|---|---|
GET /stock | Ничего | Страны, операторы, сроки и цены, а также есть ли каждое предложение в наличии. Количество в наличии не сообщается. |
GET /key | API-ключ | Ключ, которым сделан запрос: его название, доступ и дневной лимит, а также сколько потрачено и сколько осталось сегодня. |
GET /balance | read | Доступный и зарезервированный баланс. |
GET /rentals | read | Активные аренды с данными для подключения. |
GET /rentals/{id} | read | Одна активная аренда с данными для подключения. |
GET /rentals/{id}/extension-price | read | Сколько сейчас стоит продление на 1 или 30 дней. |
POST /rentals | read_write | Арендовать одно или несколько устройств. Списывает деньги с баланса. |
POST /rentals/{id}/rotate | read_write | Запросить новый IP. |
POST /rentals/{id}/extend | read_write | Продлить активную аренду. Списывает деньги с баланса. |
Существующие эндпоинты, например /catalog, /orders, /orders/{orderId} и /proxies, работают так, как сказано в описании OpenAPI. Любой API-ключ может читать /balance, /catalog, /orders и /proxies.
GET /stock
Ключ не нужен. Ответы берутся из кеша, который обновляется не чаще чем раз в 30 секунд, поэтому запрос обходится дёшево. Значения ниже — пример:
{
"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 — 1 или 30. available: false означает, что предложение сейчас распродано. includedGb есть у предложений с включённым объёмом трафика.
GET /key
{
"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 и remainingTodayMinor равны null, если у ключа нет дневного лимита.
GET /rentals и GET /rentals/{id}
Аренда выглядит так:
{
"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 — логин и пароль прокси, поэтому храните его как секрет. Его получает только аккаунт, которому принадлежит аренда. У устройств без SOCKS5 нет socks5, а includedGb есть у аренд с включённым объёмом трафика.
GET /rentals возвращает {"rentals": [ … ]} без завершённых аренд. GET /rentals/{id} отвечает 404 rental_not_found на неизвестный id или аренду другого аккаунта и 409 rental_ended на вашу завершённую аренду.
POST /rentals
Передайте заголовок Idempotency-Key (от 8 до 128 латинских букв, цифр, _ или -) и одно из двух тел запроса:
{"country": "US", "carrier": "Verizon", "days": 1, "maxPriceMinor": 2000, "quantity": 1}{"offerId": "OFFER_ID", "offerVersion": 123456, "quantity": 1}quantityнеобязателен: по умолчанию 1, не больше 20.- Первое тело арендует самое дешёвое предложение в наличии для страны (код ISO), оператора и срока. В нём обязателен
maxPriceMinor, максимум, который вы готовы заплатить за устройство: если после чтения/stockцена выросла выше него, запрос отклоняется с409 price_above_maxи ничего не списывается. - Второе тело арендует точное предложение и версию цены из
GET /catalog. Если версия цены изменилась, запрос отклоняется с409 offer_changed_refresh.
Ответ одинаков для нового заказа и для повторного запроса:
{
"orderId": "…",
"status": "paid",
"replayed": false,
"chargedMinor": 1900,
"currency": "USD",
"rentalIds": [],
"poll": "/beta/api/v1/orders/…"
}Деньги списываются с баланса, когда заказ принят, а устройство обычно готово через несколько минут. Опрашивайте GET /orders/{orderId}, пока его status равен paid. Когда статус станет fulfilled, его proxyIds — это id новых аренд. Если подготовить устройство не удалось, заказ завершается со статусом payment_failed, и деньги возвращаются на баланс.
POST /rentals/{id}/rotate
Тело не нужно ({} тоже подойдёт). Ответ — {"rotated": true, "pending": false, "ip": "…", "message": "…"}. pending: true означает, что смена IP ещё идёт; новый IP обычно появляется в GET /rentals/{id} в течение минуты. На слишком раннюю смену IP приходит ответ 429 rotation_cooldown с retryAfterSeconds и заголовком Retry-After. Действуют те же ограничения, что и в панели управления: собственная пауза устройства и 30 действий с устройствами на аккаунт за 15 минут. Устройство, которое не может сменить IP, отвечает 409 proxy_control_unavailable.
GET /rentals/{id}/extension-price
Добавьте ?days=1 или ?days=30. Ответ — {"rentalId": "…", "days": 30, "priceMinor": 13900, "currency": "USD", "endsAt": "…"}: текущая цена продления этого устройства, как в панели управления. Ничего не списывается.
POST /rentals/{id}/extend
Передайте заголовок Idempotency-Key и тело, например {"days": 1, "maxPriceMinor": 2000}. days — 1 или 30, maxPriceMinor обязателен. Цена продления рассчитывается так же, как в панели управления, и списывается, только если она не выше maxPriceMinor. В ответе есть orderId, status, replayed, chargedMinor, currency, rentalId, days и poll; повторный запрос возвращает тот же заказ без нового расчёта и списания. Продлить можно только активную аренду: на завершённую ответ — 409 rental_ended.
Пополнение баланса агентом
Агент может сам пополнить предоплаченный баланс, заплатив USDC с кошелька, которым он управляет. Аккаунт для зачисления определяет API-ключ или токен агента, отправленный вместе с платежом; подходит любой ключ, в том числе только для чтения. Баланс нельзя вывести, и агент никогда не может пополнить его за счёт денег клиента.
Пополнения принимают два адреса, и так задумано. https://ipvolt.com/api/v1 — адрес оплаты: он отвечает только на пополнения, и именно его /llms.txt указывает платёжным клиентам. https://ipvolt.com/beta/api/v1/fund — то же пополнение внутри API, рядом с GET /fund/{paymentId}, который показывает статус платежа. Оба адреса принимают одни и те же запросы и дают одни и те же ответы; статус платежа читается только по базовому URL.
Принимаются только нативные USDC в основной сети Base (сеть eip155:8453, токен 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913): 1 USDC добавляет $1.00. Кошелёк подписывает EIP-3009 transferWithAuthorization, а платёжный посредник (facilitator) отправляет его в блокчейн, поэтому кошельку нужны USDC, но не нужен ETH на оплату газа. Запрос поддерживает x402 версии 2 и Machine Payments Protocol (MPP); оба передают один и тот же подписанный перевод.
Одно пополнение — от $1.00 до $500.00; сумма задаётся параметром ?amountMinor= в центах США (от 100 до 50000; без него — $10.00). Для одного аккаунта за любые 24 часа: 10 пополнений, которые зачислены или ещё проверяются, и 30 попыток с любым исходом; одновременно открытыми могут быть не больше 3. С одного клиентского адреса можно отправить 30 платежей за 10 минут. Кроме того, ipvolt ограничивает общую сумму пополнений всех аккаунтов за любые 24 часа; сверх неё пополнения приостанавливаются и отвечают 503 x402_daily_limit.
1. Запросите предложение. GET https://ipvolt.com/api/v1?amountMinor=2000 или GET /fund?amountMinor=2000 по базовому URL отвечает 402 Payment Required с ключом или без него и ничего не сохраняет. Его заголовок PAYMENT-REQUIRED — это JSON в base64 (x402 версии 2), и accepts[0] в нём — предложение: scheme exact, network, amount в базовых единицах USDC (amountMinor × 10 000), asset, payTo, maxTimeoutSeconds 300, а в extra — имя и версия токена для EIP-712. Заголовок WWW-Authenticate: Payment делает то же предложение клиентам MPP, а тело JSON описывает его словами.
2. Оплатите. Повторите запрос с тем же amountMinor, своим API-ключом или токеном агента в Authorization: Bearer и платежом. Для x402 платёж — это заголовок PAYMENT-SIGNATURE с JSON в base64, {"x402Version": 2, "accepted": …, "payload": {"authorization": …, "signature": …} }: accepted — это accepts[0] без изменений, а шесть полей авторизации (from, to, value, validAfter, validBefore, nonce) переводят ровно amount на payTo. validAfter должен быть в прошлом, validBefore — не раньше чем через 30 секунд и не позже чем через 6 минут, а nonce — 32 случайных байта. Клиенты MPP вместо этого отправляют Payment-Authorization: Payment …, где nonce привязан к вызову сервера (challenge). Платёж без действительного ключа или токена отклоняется с кодом 401 и не читается, не проверяется и не отправляется.
Ответ на платёж:
| Статус | Что это значит |
|---|---|
| 200 | status: confirming: перевод отправлен; опрашивайте statusUrl. Та же подписанная авторизация, отправленная повторно, возвращает этот платёж с replayed: true и никогда не оплачивается дважды. |
| 202 | status: checking: результат пока неизвестен. Не платите повторно; опрашивайте statusUrl. |
| 402 | Отказ: причина в error и новое предложение. Если есть paymentId, перевода не было; statusUrl продолжает следить за платежом на случай, если авторизацию всё же используют в блокчейне, и тогда баланс всё равно пополняется. Чтобы попробовать снова, подпишите новую авторизацию. |
| 400 | Платёж не удалось прочитать как x402 или MPP, или amountMinor не от 100 до 50000 (invalid_amount). |
| 401 | Нет действительного API-ключа или токена агента. Ничего не прочитано и не отправлено. |
| 409 | Три пополнения ещё проверяются (x402_open_limit), или эту авторизацию уже предъявили для другого аккаунта. |
| 429 | Лимит аккаунта или адреса: x402_rate_limit, x402_attempt_limit или rate_limited. |
| 503 | Пополнения приостановлены или перегружены (x402_daily_limit, x402_verify_limit), или посредник не ответил (x402_facilitator_unavailable, с statusUrl). |
3. Дождитесь зачисления. Ответ посредника ничего не зачисляет. ipvolt сам читает блокчейн через два узла, ответы которых должны совпасть, и пополняет баланс, когда перевод подтверждён, обычно в течение нескольких минут. Опрашивайте statusUrl (GET https://ipvolt.com/beta/api/v1/fund/{paymentId} с ключом или токеном того же аккаунта), пока final не станет true: credited значит, что деньги на балансе (creditedAt говорит когда), а failed или expired — что перевода не было и ничего не списано.
Если платёж задерживается или его статус неясен. Платёж, чей перевод ipvolt не может сопоставить в течение двух часов или чей перевод выходит за срок действия авторизации, переходит в статус review: он не зачисляется и не закрывается автоматически. Напишите на hello@ipvolt.com и укажите его paymentId.
Пополнение не возвращается в блокчейне: уплаченное остаётся на аккаунте как баланс, то есть как предоплата услуг. Когда баланс возвращают, сказано в разделе 4 (Balance) Политики платежей и возвратов (на английском).
Вы по-прежнему можете сами пополнить баланс в панели управления, а на её странице Support видны пополнения, сделанные таким способом.
Пример: пополнить баланс, затем арендовать
Каждая версия читает предложения, пополняет баланс ровно на цену аренды в США на 1 день, ждёт зачисления, затем арендует прокси и печатает данные подключения. Нужны API-ключ с доступом на чтение и запись в IPVOLT_API_KEY и в WALLET_PRIVATE_KEY закрытый ключ кошелька с USDC в сети Base. Не передавайте их в промптах и не пишите в логи. При запуске тратятся USDC, а затем баланс.
cURL
cURL 7.84 или новее и jq, а для подписи — несколько строк на Python с eth-account. Замените PAYMENT_ID, ORDER_ID и RENTAL_ID идентификаторами из предыдущих ответов.
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
Стандартная библиотека и eth-account (pip install eth-account) для подписи.
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 или новее с viem (npm install viem) для подписи. Сохраните пример как файл .mjs в папке, где установлен viem.
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));Примеры
Каждый пример выполняет одни и те же шаги: список предложений, аренда, опрос заказа, список аренд, смена IP и продление. Ключ берётся из переменной окружения IPVOLT_API_KEY. Шаги аренды и продления списывают деньги с баланса.
cURL
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}'Замените ORDER_ID и RENTAL_ID на id из предыдущих ответов.
Python
Только стандартная библиотека. Укажите в User-Agent название своей программы.
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 или новее, файл с расширением .mjs. Укажите в User-Agent название своей программы.
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);Идемпотентность
POST /rentals и POST /rentals/{id}/extend требуют Idempotency-Key. Он привязан к вашему аккаунту: повтор запроса с тем же ключом идемпотентности возвращает тот же заказ и никогда не списывает деньги повторно, каким бы из ваших API-ключей или токенов агентов он ни был отправлен и независимо от того, удалась ли первая попытка, завершилась ошибкой или ещё выполняется. Тот же ключ идемпотентности с другим телом отклоняется с 409 intent_conflict. Ключ остаётся за своим заказом, поэтому для новой аренды его использовать нельзя. Для каждого нового заказа берите новое случайное значение, например UUID, а при повторе — то же самое.
Дневной лимит
Дневной лимит ключа проверяется до размещения заказа по сумме заказов, которые ключ оформил с 00:00 UTC: всех его аренд и продлений за этот день, кроме заказов, деньги за которые вернулись на баланс. Запросы одного ключа обрабатываются по очереди, поэтому два запроса не могут оба пройти проверку. Запрос, который превысил бы лимит, отклоняется с 409 daily_limit_exceeded, и ничего не списывается. Сколько осталось на сегодня, показывает GET /key.
Ошибки
Каждая ошибка — это JSON с постоянным кодом error, сообщением для человека message и, где это помогает, дополнительными полями:
{
"error": "insufficient_balance",
"message": "Your balance is $3.00 short for this order. Add funds and try again.",
"requiredMinor": 1900,
"availableMinor": 1600,
"missingMinor": 300
}| Статус | error | Когда |
|---|---|---|
| 400 | invalid_request | Тело или параметры запроса не соответствуют описанию. |
| 400 | idempotency_key_required, invalid_idempotency_key | Платный запрос без корректного Idempotency-Key. |
| 400 | max_price_required | Тело со страной или продление без maxPriceMinor. |
| 400 | invalid_json | Тело не является JSON-объектом. |
| 401 | invalid_api_key | Ключ отсутствует, неверен, истёк или отозван. |
| 403 | read_only_api_key | Ключ только для чтения пытался арендовать, сменить IP или продлить. |
| 403 | usage_only_api_key | Ключ, созданный до запуска публичного API, запросил аренды, баланс или другие данные аккаунта. |
| 403 | insufficient_scope | У токена агента нет нужной области. |
| 403 | https_required | Запрос пришёл по обычному HTTP. |
| 404 | not_found | Неизвестный путь. |
| 404 | rental_not_found | Неизвестная аренда или аренда другого аккаунта. |
| 409 | rental_ended | Ваша аренда завершилась. |
| 409 | stock_unavailable | Нет в наличии для этой страны, оператора и срока. |
| 409 | offer_changed_refresh | Версия цены предложения изменилась. |
| 409 | price_above_max | Текущая цена выше maxPriceMinor. Дополнительные поля: priceMinor, maxPriceMinor. |
| 409 | insufficient_balance | Недостаточно средств на балансе. Дополнительные поля: requiredMinor, availableMinor, missingMinor. |
| 409 | daily_limit_exceeded | Запрос превысил бы дневной лимит ключа. Дополнительные поля: dailyLimitMinor, spentTodayMinor, remainingTodayMinor, resetsAt. |
| 409 | spend_cap_exceeded | Запрос превысил бы лимит расходов токена агента. Дополнительные поля: remainingMinor. |
| 409 | intent_conflict | Ключ идемпотентности повторно использован с другим запросом. |
| 409 | renewal_pending | Продление этой аренды уже обрабатывается. |
| 409 | proxy_control_unavailable | Устройство не поддерживает это действие. |
| 415 | json_required | POST без Content-Type: application/json. |
| 429 | rotation_cooldown | IP меняли слишком недавно. Дополнительные поля: retryAfterSeconds. |
| 429 | try_again_later | Сработало ограничение частоты запросов. |
| 503 | balance_purchases_unavailable, supplier_unavailable, supplier_funding_unavailable, temporarily_unavailable | Сейчас арендовать нельзя. Ничего не списано. |
Ограничения частоты
Запросы считаются в фиксированных 15-минутных окнах:
- 900 запросов на API-ключ.
- На IP-адрес клиента (IPv6 считается по сетям /64): 1800 запросов с ключом и 300 к
GET /stock. - 30 запросов аренды и продления на ключ. Для каждого аккаунта действуют и ограничения панели управления: 30 покупок, 30 продлений, 30 действий с устройствами и 240 чтений данных устройств.
При превышении ограничения ответ — 429 try_again_later.
Журнал действий
Каждый запрос с API-ключом записывается в журнал этого ключа: время, действие, HTTP-статус, результат (ok или код ошибки), а для аренды и продления — списанная сумма и id заказа. В журнал никогда не попадают ключ, логин и пароль прокси, тела запросов и адреса. Последние 100 записей ключа видны в разделе Account settings → API keys → Activity. Записи удаляются через 90 дней.
Допустимое использование
Ко всему, что делается через API, применяются Правила допустимого использования (на английском).
Изменения
- 18 ноября 2026 года: опубликован этот справочник: наличие, ключи, аренды, смена IP и продление.
- 18 ноября 2026 года: API отвечает только по адресу
https://ipvolt.com/beta/api/v1. Запросы к/dashboard/api/v1, который до этого показывала страница API в панели управления, перенаправляются туда с кодом308, который сохраняет метод и тело запроса. - 18 ноября 2026 года: раздел «Пополнение баланса агентом» — что принимает пополнение в USDC, его лимиты и ответы, и пример, который пополняет баланс, а затем арендует прокси.