通过 ipvolt API,你的软件和 AI 智能体无需打开控制台,就能租用独享移动代理、轮换 IP 并续租。费用从你的预付余额中扣除。智能体可以用自己在 Base 上的 USDC 自行充值,详见下文“由智能体充值”;你也可以在控制台中充值。
- 基础 URL:
https://ipvolt.com/beta/api/v1 - 充值付款地址:
https://ipvolt.com/api/v1 - OpenAPI 3.1 描述:openapi.json
v1 是稳定版本。 地址中的 /beta 是历史遗留的名称,与 API 的状态无关。我们可能随时新增端点、响应字段和错误代码,请让客户端忽略它不认识的部分。任何会让正常运行的客户端出错的改动,例如删除或重命名端点或字段、更改地址,都会作为新版本(/v2)发布,并在本页末尾的“变更记录”中公布,v1 会继续运行。
认证
在 Authorization 请求头中以 Bearer $IPVOLT_API_KEY 的形式发送 API 密钥。在控制台的 Account settings → API keys(账户设置 → API 密钥)中创建密钥。每个密钥都有名称、30 天或 90 天的有效期,以及以下两种访问级别之一:
read:读取密钥信息、余额、租用列表和续租价格。read_write:此外还能租用、轮换和续租。usage:公共 API 开启之前创建的密钥。它保留原有权限(用量、会话和订单状态),不能读取租用或余额;如需这些,请创建新密钥。
密钥还可以设置每日限额,范围为 $1 到 $10,000,即该密钥每个 UTC 日在租用和续租上最多可花费的金额。不设限额时,余额就是上限。密钥只在创建时显示一次;ipvolt 只保存其 SHA-256 哈希。每个账户最多可有 10 个有效密钥,撤销的密钥会立即失效。
只通过 HTTPS 发送密钥:通过明文 HTTP 到达 ipvolt 的请求会在读取密钥之前被拒绝,返回 403 https_required。密钥缺失、错误、过期或已撤销时,返回 401 invalid_api_key。
通过 auth.md 获得的智能体访问令牌同样可用。读取需要其 account:read 权限范围;租用、轮换和续租需要 proxies:buy,其花费计入该智能体自身的支出上限。
请求与响应
请求和响应均为 JSON。POST 请求体须带 Content-Type: application/json(否则返回 415 json_required),最大 8 KiB。金额为以美分计的整数,例如 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} 对未知 id 或其他账户的租用返回 404 rental_not_found,对你自己已结束的租用返回 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/…"
}订单被接受时即从余额扣费,设备通常在几分钟内就绪。在 status 为 paid 期间轮询 GET /orders/{orderId}。变为 fulfilled 后,其 proxyIds 就是新租用的 id。如果开通失败,订单以 payment_failed 结束,款项退回你的余额。
POST /rentals/{id}/rotate
无需请求体(发送 {} 也可以)。响应为 {"rotated": true, "pending": false, "ip": "…", "message": "…"}。pending: true 表示轮换仍在进行;新 IP 通常在一分钟内出现在 GET /rentals/{id} 中。轮换过于频繁会返回 429 rotation_cooldown,并带有 retryAfterSeconds 和 Retry-After 响应头。控制台的限制同样适用:设备自身的冷却时间,以及每个账户每 15 分钟 30 次设备操作。不支持轮换的设备返回 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 下查询。
只接受 Base 主网上的原生 USDC(网络 eip155:8453,代币 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913),1 USDC 计为 $1.00。钱包签署一个 EIP-3009 transferWithAuthorization,由付款协调方(facilitator)提交上链,因此钱包需要 USDC,但不需要支付 gas 的 ETH。请求支持 x402 第 2 版和 Machine Payments Protocol(MPP),两者携带的是同一笔已签名的转账。
每笔充值 $1.00 到 $500.00,用 ?amountMinor= 以美分设定(100 到 50000;不设定时为 $10.00)。每个账户在任意 24 小时内:已入账或仍在核对的充值最多 10 笔,任何结果的尝试最多 30 次;同时未完成的最多 3 笔。每个客户端地址每 10 分钟最多发送 30 次付款。ipvolt 还限制所有账户在任意 24 小时内的充值总额;超过后,充值暂停并返回 503 x402_daily_limit。
1. 获取报价。 GET https://ipvolt.com/api/v1?amountMinor=2000,或基础 URL 下的 GET /fund?amountMinor=2000,无论带不带密钥都会返回 402 Payment Required,并且不保存任何内容。它的 PAYMENT-REQUIRED 头是 base64 编码的 JSON(x402 第 2 版),其中 accepts[0] 就是报价:scheme 为 exact,另有 network、以 USDC 基本单位表示的 amount(amountMinor × 10,000)、asset、payTo、maxTimeoutSeconds 300,extra 中是代币的 EIP-712 名称和版本。WWW-Authenticate: Payment 头向 MPP 客户端提供同一份报价,JSON 正文则用文字说明。
2. 付款。 用相同的 amountMinor 重复请求,在 Authorization: Bearer 中带上你的 API 密钥或智能体令牌,并附上付款。x402 的付款是一个 PAYMENT-SIGNATURE 头,内容为 base64 编码的 JSON,{"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 天租用的价格精确充值,等待入账,然后租用并打印连接信息。它需要在 IPVOLT_API_KEY 中提供一个读写 API 密钥,并在 WALLET_PRIVATE_KEY 中提供一个持有 Base 上 USDC 的钱包的私钥。不要把这两者放进提示词或日志。运行时会先花费 USDC,再花费余额。
cURL
需要 cURL 7.84 或更高版本和 jq,并用几行 Python 和 eth-account 完成签名。把 PAYMENT_ID、ORDER_ID 和 RENTAL_ID 换成前面应答中的 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));示例
每个示例执行相同的步骤:查看可租方案、租用、轮询订单、列出租用、轮换和续租。示例从环境变量 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。它绑定你的账户:用同一个键重复请求,会返回同一订单且绝不重复扣费,无论由你的哪个密钥或智能体令牌发送,也无论第一次尝试是成功、失败还是仍在进行。同一个键配不同的请求体会被拒绝,返回 409 intent_conflict。键会一直跟随其订单,因此不能用于新的租用。每个新订单请使用新的随机值(例如 UUID),重试时使用同一个值。
每日限额
下单前会检查密钥的每日限额,依据是该密钥自 UTC 00:00 起已下的订单:当天经它下的每笔租用和续租,款项已退回余额的订单除外。同一密钥的请求逐个处理,因此不会有两个请求同时通过检查。会超出限额的请求被拒绝,返回 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 | 只读密钥试图租用、轮换或续租。 |
| 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 | 距上次轮换时间太短。附加字段:retryAfterSeconds。 |
| 429 | try_again_later | 触发了频率限制。 |
| 503 | balance_purchases_unavailable, supplier_unavailable, supplier_funding_unavailable, temporarily_unavailable | 目前无法租用。没有扣费。 |
频率限制
请求按固定的 15 分钟窗口计数:
- 每个 API 密钥 900 个请求。
- 每个客户端 IP 地址(IPv6 按 /64 网段计):带密钥的请求 1,800 个,
GET /stock300 个。 - 每个密钥 30 个租用和续租请求。每个账户还受控制台自身的限制:30 次购买、30 次续租、30 次设备操作和 240 次设备读取。
超出限制时返回 429 try_again_later。
活动日志
使用 API 密钥发出的每个请求都会记入该密钥的日志:时间、操作、HTTP 状态码、结果(ok 或错误代码),对于租用和续租还有扣费金额和订单 id。日志从不保存密钥、代理凭据、请求体或地址。在 Account settings → API keys → Activity(账户设置 → API 密钥 → 活动)中可查看每个密钥最近 100 条记录。记录保存 90 天后删除。
可接受使用
通过 API 进行的一切操作均适用可接受使用政策(英文)。
变更记录
- 2026 年 11 月 18 日:发布本参考文档,包括库存、密钥、租用、轮换和续租。
- 2026 年 11 月 18 日:API 只在
https://ipvolt.com/beta/api/v1提供服务。发往/dashboard/api/v1(此前控制台自带的 API 页面显示的地址)的请求会以308重定向到那里,请求方法和请求体保持不变。 - 2026 年 11 月 18 日:新增“由智能体充值”,说明 USDC 充值接受什么、它的限额和应答,以及一个先充值再租用的示例。