# Referencia de la API

Source: https://ipvolt.com/es/docs/api
Markdown: https://ipvolt.com/es/docs/api.md
Language: es

[Inicio](https://ipvolt.com/es.md) / [Documentación (en inglés)](https://ipvolt.com/docs.md) / Referencia de la API

Sección: API
Actualizado: 2026-11-22
Autor: ipvolt

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.

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](https://ipvolt.com/dashboard).

- 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](https://ipvolt.com/beta/api/v1/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](https://ipvolt.com/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 ruta | Requiere | Qué hace |
| --- | --- | --- |
| `GET /stock` | Nada | Países, operadores, duraciones y precios, y si cada oferta está disponible. Nunca una cantidad de existencias. |
| `GET /key` | Una clave de API | La clave que hace la petición: su nombre, acceso y límite diario, y lo que ha gastado y le queda hoy. |
| `GET /balance` | `read` | Saldo disponible y retenido. |
| `GET /rentals` | `read` | Alquileres activos con sus datos de conexión. |
| `GET /rentals/{id}` | `read` | Un alquiler activo con sus datos de conexión. |
| `GET /rentals/{id}/extension-price` | `read` | Cuánto cuesta ahora ampliar 1 o 30 días. |
| `POST /rentals` | `read_write` | Alquilar uno o más dispositivos. Cobra del saldo. |
| `POST /rentals/{id}/rotate` | `read_write` | Pedir una IP nueva. |
| `POST /rentals/{id}/extend` | `read_write` | Ampliar 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](https://ipvolt.com/auth.md) 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:

| Estado | Qué significa |
| --- | --- |
| 200 | `status: 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. |
| 202 | `status: checking`: el resultado aún no se conoce. No vuelvas a pagar; consulta `statusUrl`. |
| 402 | Rechazado, 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. |
| 400 | El pago no se pudo leer como x402 o MPP, o `amountMinor` no está entre 100 y 50000 (`invalid_amount`). |
| 401 | No hay una clave de API o un token de agente válidos. No se leyó ni se envió nada. |
| 409 | Tres recargas siguen en comprobación (`x402_open_limit`), o esta autorización ya se presentó para otra cuenta. |
| 429 | Un límite de la cuenta o de la dirección: `x402_rate_limit`, `x402_attempt_limit` o `rate_limited`. |
| 503 | Las 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)](/refunds) explica cuándo se reembolsa el saldo.

Puedes seguir añadiendo saldo tú mismo en el [panel](https://ipvolt.com/dashboard), 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](https://pypi.org/project/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](https://pypi.org/project/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](https://viem.sh) (`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
}
```

| Estado | `error` | Cuándo |
| --- | --- | --- |
| 400 | `invalid_request` | El cuerpo o los parámetros no son como se documentan. |
| 400 | `idempotency_key_required`, `invalid_idempotency_key` | Una petición con cobro sin una `Idempotency-Key` válida. |
| 400 | `max_price_required` | El cuerpo con país o una ampliación sin `maxPriceMinor`. |
| 400 | `invalid_json` | El cuerpo no es un objeto JSON. |
| 401 | `invalid_api_key` | La clave falta, es incorrecta, ha caducado o está revocada. |
| 403 | `read_only_api_key` | Una clave de solo lectura intentó alquilar, rotar o ampliar. |
| 403 | `usage_only_api_key` | Una clave creada antes de la API pública pidió los alquileres, el saldo u otros datos de la cuenta. |
| 403 | `insufficient_scope` | Un token de agente sin el ámbito necesario. |
| 403 | `https_required` | La petición llegó por HTTP sin cifrar. |
| 404 | `not_found` | Ruta desconocida. |
| 404 | `rental_not_found` | Alquiler desconocido o de otra cuenta. |
| 409 | `rental_ended` | Tu alquiler ha terminado. |
| 409 | `stock_unavailable` | Agotado para ese país, operador y duración. |
| 409 | `offer_changed_refresh` | La versión de precio de la oferta cambió. |
| 409 | `price_above_max` | El precio actual supera `maxPriceMinor`. Campos adicionales: `priceMinor`, `maxPriceMinor`. |
| 409 | `insufficient_balance` | El saldo no alcanza. Campos adicionales: `requiredMinor`, `availableMinor`, `missingMinor`. |
| 409 | `daily_limit_exceeded` | Se superaría el límite diario de la clave. Campos adicionales: `dailyLimitMinor`, `spentTodayMinor`, `remainingTodayMinor`, `resetsAt`. |
| 409 | `spend_cap_exceeded` | Se superaría el límite de gasto de un token de agente. Campos adicionales: `remainingMinor`. |
| 409 | `intent_conflict` | Una clave de idempotencia reutilizada con otra petición. |
| 409 | `renewal_pending` | Ya se está procesando una ampliación de este alquiler. |
| 409 | `proxy_control_unavailable` | El dispositivo no admite la acción. |
| 415 | `json_required` | Un POST sin `Content-Type: application/json`. |
| 429 | `rotation_cooldown` | Se rotó hace muy poco. Campos adicionales: `retryAfterSeconds`. |
| 429 | `try_again_later` | Un límite de frecuencia. |
| 503 | `balance_purchases_unavailable`, `supplier_unavailable`, `supplier_funding_unavailable`, `temporarily_unavailable` | Ahora 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)](/acceptable-use) 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.

## Más documentación

- Siguiente: [Agentes de IA](https://ipvolt.com/es/docs/ai-agents.md)
- [Toda la documentación (en inglés)](https://ipvolt.com/docs.md)
- [Leer el original en inglés](https://ipvolt.com/docs/api.md)
