Referencia de la API

Alquila, rota y amplía proxies móviles de ipvolt por HTTPS con tu saldo prepago: claves de API, endpoints, errores, límites, idempotencia y ejemplos de código.

En esta página

La API de ipvolt permite que tu software y tus agentes de IA alquilen proxies móviles dedicados, roten su IP y amplíen el alquiler sin usar el panel. Se paga con tu saldo prepago. Un agente puede añadir saldo por sí mismo pagando con sus propios USDC en Base, como se explica más abajo en «Añadir saldo desde tu agente», y tú también puedes añadir saldo en el panel.

  • URL base: https://ipvolt.com/beta/api/v1
  • Dirección de pago para recargas: https://ipvolt.com/api/v1
  • Descripción OpenAPI 3.1: openapi.json

La v1 es estable. El /beta de la dirección es histórico y no dice nada sobre el estado de la API. Podemos añadir endpoints, campos de respuesta y códigos de error en cualquier momento, así que ignora los que tu cliente no conozca. Cualquier cambio que rompa un cliente que funciona, como eliminar o renombrar un endpoint o un campo, o cambiar la dirección, llegará como una versión nueva (/v2), anunciada en «Cambios» al final de esta página, y la v1 seguirá funcionando.

Autenticación

Envía una clave de API en la cabecera Authorization como Bearer $IPVOLT_API_KEY. Las claves se crean en el panel, en Account settings → API keys (Ajustes de la cuenta → Claves de API). Cada clave tiene un nombre, una caducidad de 30 o 90 días y uno de dos niveles de acceso:

  • read: consulta la clave, el saldo, los alquileres y los precios de ampliación.
  • read_write: además puede alquilar, rotar y ampliar.
  • usage: una clave creada antes de que se activara la API pública. Conserva su acceso anterior (uso, sesiones y estado de los pedidos) y no lee los alquileres ni el saldo; para eso, crea una clave nueva.

Una clave también puede tener un límite diario, de US$1 a US$10 000: lo máximo que puede gastar en alquileres y ampliaciones por día UTC. Sin límite diario, el límite es el saldo. La clave se muestra una sola vez, al crearla; ipvolt guarda solo su hash SHA-256. Una cuenta puede tener hasta 10 claves activas, y una clave revocada deja de funcionar al instante.

Envía las claves solo por HTTPS: una petición que llega a ipvolt por HTTP sin cifrar se rechaza con 403 https_required antes de leer la clave. Si la clave falta, es incorrecta, ha caducado o está revocada, la respuesta es 401 invalid_api_key.

También sirve un token de acceso de agente obtenido con auth.md. Para leer necesita el ámbito account:read; para alquilar, rotar y ampliar, proxies:buy, y lo que gasta cuenta para el límite de gasto propio del agente.

Peticiones y respuestas

Las peticiones y las respuestas son JSON. Envía el cuerpo de los POST con Content-Type: application/json (si no, 415 json_required), con 8 KiB como máximo. Los importes son enteros en centavos de dólar estadounidense, como priceMinor y chargedMinor; GET /balance mantiene sus centavos como cadenas decimales.

Endpoints

Las rutas son relativas a la URL base. read significa cualquier clave de API o un token de agente con account:read; read_write, una clave de lectura y escritura o un token de agente con proxies:buy.

Método y rutaRequiereQué hace
GET /stockNadaPaíses, operadores, duraciones y precios, y si cada oferta está disponible. Nunca una cantidad de existencias.
GET /keyUna clave de APILa clave que hace la petición: su nombre, acceso y límite diario, y lo que ha gastado y le queda hoy.
GET /balancereadSaldo disponible y retenido.
GET /rentalsreadAlquileres activos con sus datos de conexión.
GET /rentals/{id}readUn alquiler activo con sus datos de conexión.
GET /rentals/{id}/extension-pricereadCuánto cuesta ahora ampliar 1 o 30 días.
POST /rentalsread_writeAlquilar uno o más dispositivos. Cobra del saldo.
POST /rentals/{id}/rotateread_writePedir una IP nueva.
POST /rentals/{id}/extendread_writeAmpliar un alquiler activo. Cobra del saldo.

Los endpoints existentes, como /catalog, /orders, /orders/{orderId} y /proxies, funcionan como indica la descripción OpenAPI. Cualquier clave de API puede leer /balance, /catalog, /orders y /proxies.

GET /stock

No necesita clave. Las respuestas salen de una caché que se actualiza como mucho cada 30 segundos, así que consultarlo es barato. Los valores de abajo son un ejemplo:

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 es 1 o 30. available: false significa agotado en este momento. includedGb aparece en las ofertas que incluyen un volumen de datos.

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 y remainingTodayMinor son null si la clave no tiene límite diario.

GET /rentals y GET /rentals/{id}

Un alquiler tiene este aspecto:

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 contiene el usuario y la contraseña del proxy, así que trátalo como un secreto. Solo lo recibe la cuenta propietaria del alquiler. socks5 no aparece en dispositivos sin SOCKS5, e includedGb aparece en los alquileres con un volumen de datos incluido.

GET /rentals responde {"rentals": [ … ]} y omite los alquileres terminados. GET /rentals/{id} responde 404 rental_not_found a un id desconocido o a un alquiler de otra cuenta, y 409 rental_ended a un alquiler tuyo que ya terminó.

POST /rentals

Envía una cabecera Idempotency-Key (de 8 a 128 letras latinas, dígitos, _ o -) y uno de estos dos cuerpos:

json
{"country": "US", "carrier": "Verizon", "days": 1, "maxPriceMinor": 2000, "quantity": 1}
json
{"offerId": "OFFER_ID", "offerVersion": 123456, "quantity": 1}
  • quantity es opcional: 1 por defecto, 20 como máximo.
  • El primer cuerpo alquila la oferta disponible más barata para el país (código ISO), el operador y la duración. Necesita maxPriceMinor, lo máximo que aceptas pagar por dispositivo: si el precio subió por encima después de leer /stock, la petición se rechaza con 409 price_above_max y no se cobra nada.
  • El segundo cuerpo alquila una oferta y una versión de precio exactas de GET /catalog. Si la versión de precio cambió, se rechaza con 409 offer_changed_refresh.

La respuesta es la misma para un pedido nuevo y para uno repetido:

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

El importe se cobra del saldo cuando se acepta el pedido, y el dispositivo suele estar listo en pocos minutos. Consulta GET /orders/{orderId} mientras su status sea paid. Cuando sea fulfilled, sus proxyIds son los id de los nuevos alquileres. Si la preparación falla, el pedido termina en payment_failed y el dinero vuelve a tu saldo.

POST /rentals/{id}/rotate

No hace falta cuerpo ({} también sirve). La respuesta es {"rotated": true, "pending": false, "ip": "…", "message": "…"}. pending: true significa que la rotación sigue en curso; la IP nueva suele aparecer en GET /rentals/{id} en menos de un minuto. Rotar demasiado pronto devuelve 429 rotation_cooldown con retryAfterSeconds y una cabecera Retry-After. Se aplican los límites del panel: la pausa propia del dispositivo y 30 acciones sobre dispositivos por cuenta cada 15 minutos. Un dispositivo que no puede rotar responde 409 proxy_control_unavailable.

GET /rentals/{id}/extension-price

Añade ?days=1 o ?days=30. La respuesta es {"rentalId": "…", "days": 30, "priceMinor": 13900, "currency": "USD", "endsAt": "…"}: el precio de renovación de este dispositivo ahora, el mismo que en el panel. No cobra nada.

POST /rentals/{id}/extend

Envía una cabecera Idempotency-Key y un cuerpo como {"days": 1, "maxPriceMinor": 2000}. days es 1 o 30, y maxPriceMinor es obligatorio. La ampliación se calcula como en el panel y solo se cobra si el precio no supera maxPriceMinor. La respuesta tiene orderId, status, replayed, chargedMinor, currency, rentalId, days y poll; una petición repetida devuelve el mismo pedido sin volver a calcular ni a cobrar. Solo se puede ampliar un alquiler activo: uno terminado responde 409 rental_ended.

Añadir saldo desde tu agente

Un agente puede añadir saldo prepago por sí mismo pagando USDC desde una cartera que controla. La clave de API o el token de agente que se envía con el pago identifica la cuenta a la que se acredita, y sirve cualquier clave, también una de solo lectura. El saldo no se puede retirar, y un agente nunca puede añadir saldo con el dinero del cliente.

Dos direcciones aceptan recargas, a propósito. https://ipvolt.com/api/v1 es la dirección de pago: solo responde a recargas y es la que /llms.txt indica a los clientes de pago. https://ipvolt.com/beta/api/v1/fund es la misma recarga dentro de la API, junto a GET /fund/{paymentId}, que da el estado de un pago. Las dos aceptan las mismas peticiones y dan las mismas respuestas; el estado de un pago solo se consulta bajo la URL base.

Solo acepta USDC nativos en la red principal de Base (red eip155:8453, token 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913): 1 USDC añade US$1.00. La cartera firma un transferWithAuthorization de EIP-3009 y un facilitador de pagos lo envía a la cadena, así que la cartera necesita USDC pero no ETH para el gas. La petición admite x402 versión 2 y el Machine Payments Protocol (MPP); los dos llevan la misma transferencia firmada.

Cada recarga es de US$1.00 a US$500.00 y se elige con ?amountMinor= en centavos de dólar (de 100 a 50000; sin él, US$10.00). Por cuenta, en cualquier periodo de 24 horas: 10 recargas acreditadas o aún en comprobación y 30 intentos con cualquier resultado; como máximo 3 abiertas a la vez. Cada dirección de cliente puede enviar 30 pagos cada 10 minutos. ipvolt también limita el total de recargas de todas las cuentas en cualquier periodo de 24 horas; por encima de él, las recargas se pausan y responden 503 x402_daily_limit.

1. Pide la oferta. GET https://ipvolt.com/api/v1?amountMinor=2000, o GET /fund?amountMinor=2000 bajo la URL base, responde 402 Payment Required con o sin clave y no guarda nada. Su cabecera PAYMENT-REQUIRED es JSON en base64 (x402 versión 2), y accepts[0] en ella es la oferta: scheme exact, network, amount en unidades base de USDC (amountMinor × 10 000), asset, payTo, maxTimeoutSeconds 300 y, en extra, el nombre y la versión EIP-712 del token. Una cabecera WWW-Authenticate: Payment hace la misma oferta a los clientes MPP, y el cuerpo JSON la explica con palabras.

2. Paga. Repite la petición con el mismo amountMinor, tu clave de API o token de agente en Authorization: Bearer y el pago. En x402 el pago es una cabecera PAYMENT-SIGNATURE con JSON en base64, {"x402Version": 2, "accepted": …, "payload": {"authorization": …, "signature": …} }: accepted es accepts[0] sin cambios, y los seis campos de la autorización (from, to, value, validAfter, validBefore, nonce) mueven exactamente amount a payTo. validAfter debe estar en el pasado, validBefore entre 30 segundos y 6 minutos en el futuro, y nonce son 32 bytes aleatorios. Los clientes MPP envían en su lugar Payment-Authorization: Payment …, con el nonce ligado al desafío (challenge) del servidor. Un pago sin una clave o un token válidos se rechaza con 401 y nunca se lee, verifica ni envía.

La respuesta al pago:

EstadoQué significa
200status: confirming: la transferencia se envió; consulta statusUrl. La misma autorización firmada enviada otra vez devuelve este pago con replayed: true y nunca paga dos veces.
202status: checking: el resultado aún no se conoce. No vuelvas a pagar; consulta statusUrl.
402Rechazado, con el motivo en error y una oferta nueva. Si hay un paymentId, no se hizo ninguna transferencia; statusUrl sigue el pago por si la autorización se usa en la cadena después, y entonces el saldo se acredita igualmente. Firma una autorización nueva para volver a intentarlo.
400El pago no se pudo leer como x402 o MPP, o amountMinor no está entre 100 y 50000 (invalid_amount).
401No hay una clave de API o un token de agente válidos. No se leyó ni se envió nada.
409Tres recargas siguen en comprobación (x402_open_limit), o esta autorización ya se presentó para otra cuenta.
429Un límite de la cuenta o de la dirección: x402_rate_limit, x402_attempt_limit o rate_limited.
503Las recargas están pausadas u ocupadas (x402_daily_limit, x402_verify_limit), o el facilitador no respondió (x402_facilitator_unavailable, con un statusUrl).

3. Espera la acreditación. La respuesta del facilitador no acredita nada. ipvolt lee la cadena por sí mismo, a través de dos nodos que deben coincidir, y acredita el saldo cuando la transferencia está confirmada, normalmente en pocos minutos. Consulta statusUrl (GET https://ipvolt.com/beta/api/v1/fund/{paymentId}, con una clave o un token de la misma cuenta) hasta que final sea true: credited significa que el dinero está en el saldo (creditedAt dice cuándo), y failed o expired, que no hubo transferencia y no se cobró nada.

Si un pago llega tarde o no está claro. Un pago cuya transferencia ipvolt no puede emparejar en dos horas, o cuya transferencia queda fuera del plazo de la autorización, pasa a review: no se acredita ni se cierra automáticamente. Escribe a hello@ipvolt.com con su paymentId.

Una recarga no se revierte en la cadena: lo que pagas queda en la cuenta como saldo, que es crédito de servicio. La sección 4, Balance, de la Política de pagos y reembolsos (en inglés) explica cuándo se reembolsa el saldo.

Puedes seguir añadiendo saldo tú mismo en el panel, y su página Support muestra las recargas hechas así.

Ejemplo: recargar y luego alquilar

Cada versión consulta las ofertas, recarga exactamente el precio de un alquiler de 1 día en EE. UU., espera la acreditación y luego alquila y muestra los datos de conexión. Necesita una clave de API de lectura y escritura en IPVOLT_API_KEY y, en WALLET_PRIVATE_KEY, la clave privada de una cartera con USDC en Base. Mantén las dos fuera de los prompts y de los registros. Al ejecutarla se gastan USDC y después saldo.

cURL

cURL 7.84 o posterior y jq, más unas líneas de Python con eth-account para firmar. Sustituye PAYMENT_ID, ORDER_ID y RENTAL_ID por los ids de las respuestas anteriores.

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

Biblioteca estándar más eth-account (pip install eth-account) para firmar.

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 o posterior con viem (npm install viem) para firmar. Guárdalo como archivo .mjs en la carpeta donde está instalado viem.

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));

Ejemplos

Cada ejemplo sigue los mismos pasos: consultar las ofertas, alquilar, consultar el pedido, listar los alquileres, rotar y ampliar. Leen tu clave de la variable de entorno IPVOLT_API_KEY. Los pasos de alquilar y ampliar cobran de tu saldo.

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}'

Sustituye ORDER_ID y RENTAL_ID por los id de las respuestas anteriores.

Python

Solo la biblioteca estándar. Pon en User-Agent el nombre de tu 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 o posterior, guardado como archivo .mjs. Pon en User-Agent el nombre de tu 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);

Idempotencia

POST /rentals y POST /rentals/{id}/extend necesitan una Idempotency-Key. Pertenece a tu cuenta: repetir una petición con la misma clave devuelve el mismo pedido y nunca vuelve a cobrar, sea cual sea la clave de API o el token de agente que la envíe, y tanto si el primer intento salió bien como si falló o sigue en curso. La misma clave con otro cuerpo se rechaza con 409 intent_conflict. Una clave queda unida a su pedido, así que no sirve para un alquiler nuevo. Usa un valor aleatorio nuevo, como un UUID, para cada pedido nuevo, y el mismo valor al reintentarlo.

Límite diario

El límite diario de una clave se comprueba antes de hacer un pedido, frente a lo que la clave ha comprometido desde las 00:00 UTC: cada alquiler y ampliación que hizo ese día, salvo los pedidos cuyo dinero volvió al saldo. Las peticiones de una misma clave se atienden de una en una, así que dos no pueden pasar la comprobación a la vez. Una petición que lo supere se rechaza con 409 daily_limit_exceeded y no se cobra nada. GET /key muestra lo que queda hoy.

Errores

Cada error es un JSON con un código error estable, un message para personas y, cuando ayudan, más campos:

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
}
EstadoerrorCuándo
400invalid_requestEl cuerpo o los parámetros no son como se documentan.
400idempotency_key_required, invalid_idempotency_keyUna petición con cobro sin una Idempotency-Key válida.
400max_price_requiredEl cuerpo con país o una ampliación sin maxPriceMinor.
400invalid_jsonEl cuerpo no es un objeto JSON.
401invalid_api_keyLa clave falta, es incorrecta, ha caducado o está revocada.
403read_only_api_keyUna clave de solo lectura intentó alquilar, rotar o ampliar.
403usage_only_api_keyUna clave creada antes de la API pública pidió los alquileres, el saldo u otros datos de la cuenta.
403insufficient_scopeUn token de agente sin el ámbito necesario.
403https_requiredLa petición llegó por HTTP sin cifrar.
404not_foundRuta desconocida.
404rental_not_foundAlquiler desconocido o de otra cuenta.
409rental_endedTu alquiler ha terminado.
409stock_unavailableAgotado para ese país, operador y duración.
409offer_changed_refreshLa versión de precio de la oferta cambió.
409price_above_maxEl precio actual supera maxPriceMinor. Campos adicionales: priceMinor, maxPriceMinor.
409insufficient_balanceEl saldo no alcanza. Campos adicionales: requiredMinor, availableMinor, missingMinor.
409daily_limit_exceededSe superaría el límite diario de la clave. Campos adicionales: dailyLimitMinor, spentTodayMinor, remainingTodayMinor, resetsAt.
409spend_cap_exceededSe superaría el límite de gasto de un token de agente. Campos adicionales: remainingMinor.
409intent_conflictUna clave de idempotencia reutilizada con otra petición.
409renewal_pendingYa se está procesando una ampliación de este alquiler.
409proxy_control_unavailableEl dispositivo no admite la acción.
415json_requiredUn POST sin Content-Type: application/json.
429rotation_cooldownSe rotó hace muy poco. Campos adicionales: retryAfterSeconds.
429try_again_laterUn límite de frecuencia.
503balance_purchases_unavailable, supplier_unavailable, supplier_funding_unavailable, temporarily_unavailableAhora no se puede alquilar. No se cobró nada.

Límites de frecuencia

Las peticiones se cuentan en ventanas fijas de 15 minutos:

  • 900 peticiones por clave de API.
  • Por dirección IP del cliente, con IPv6 contado por red /64: 1800 peticiones con clave y 300 a GET /stock.
  • 30 peticiones de alquiler y ampliación por clave. Cada cuenta tiene además los límites del panel: 30 compras, 30 renovaciones, 30 acciones sobre dispositivos y 240 lecturas de dispositivos.

Si se supera un límite, la respuesta es 429 try_again_later.

Registro de actividad

Cada petición hecha con una clave de API queda registrada para esa clave: la hora, la acción, el estado HTTP, el resultado (ok o el código de error) y, en alquileres y ampliaciones, el importe cobrado y el id del pedido. El registro nunca guarda la clave, credenciales del proxy, cuerpos de peticiones ni direcciones. Account settings → API keys → Activity muestra las últimas 100 entradas de una clave. Las entradas se borran a los 90 días.

Uso aceptable

La Política de uso aceptable (en inglés) se aplica a todo lo que se hace a través de la API.

Cambios

  • 18 de noviembre de 2026: se publica esta referencia, con stock, claves, alquileres, rotación y ampliaciones.
  • 18 de noviembre de 2026: la API responde solo en https://ipvolt.com/beta/api/v1. Las peticiones a /dashboard/api/v1, que la página de API del panel mostraba hasta entonces, se redirigen allí con 308, que conserva el método y el cuerpo.
  • 18 de noviembre de 2026: «Añadir saldo desde tu agente»: qué acepta la recarga con USDC, sus límites y respuestas, y un ejemplo que recarga y luego alquila.

Conecta tu primer proxy.

Móvil desde US$9 al día. Residencial desde US$0.60 por GB, en paquetes desde US$5.