# API 参考

Source: https://ipvolt.com/zh/docs/api
Markdown: https://ipvolt.com/zh/docs/api.md
Language: zh-CN

[首页](https://ipvolt.com/zh.md) / [文档（英文）](https://ipvolt.com/docs.md) / API 参考

分类：API
更新于：2026-11-22
作者：ipvolt

通过 HTTPS 用预付余额租用、轮换和续租 ipvolt 独享移动代理的 API 参考：API 密钥的只读与读写权限、每日限额、全部端点、错误代码、频率限制、幂等性、活动日志，以及 cURL、Python 和 Node.js 代码示例，适合把代理接入自己的软件或 AI 智能体。

通过 ipvolt API，你的软件和 AI 智能体无需打开控制台，就能租用独享移动代理、轮换 IP 并续租。费用从你的预付余额中扣除。智能体可以用自己在 Base 上的 USDC 自行充值，详见下文“由智能体充值”；你也可以在[控制台](https://ipvolt.com/dashboard)中充值。

- 基础 URL：`https://ipvolt.com/beta/api/v1`
- 充值付款地址：`https://ipvolt.com/api/v1`
- OpenAPI 3.1 描述：[openapi.json](https://ipvolt.com/beta/api/v1/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](https://ipvolt.com/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 秒刷新一次的缓存，因此调用开销很低。以下数值仅为示例：

```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` 为 1 或 30。`available: false` 表示目前已售罄。包含流量额度的方案会带有 `includedGb`。

### `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` 和 `remainingTodayMinor` 为 `null`。

### `GET /rentals` 和 `GET /rentals/{id}`

一个租用的结构如下：

```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` 包含代理的用户名和密码，请当作机密保管。只有拥有该租用的账户才会收到它。没有 SOCKS5 的设备不含 `socks5`；包含流量额度的租用会带有 `includedGb`。

`GET /rentals` 返回 `{"rentals": [ … ]}`，不含已结束的租用。`GET /rentals/{id}` 对未知 id 或其他账户的租用返回 `404 rental_not_found`，对你自己已结束的租用返回 `409 rental_ended`。

### `POST /rentals`

发送 `Idempotency-Key` 请求头（8 到 128 个英文字母、数字、`_` 或 `-`），以及以下两种请求体之一：

```json
{"country": "US", "carrier": "Verizon", "days": 1, "maxPriceMinor": 2000, "quantity": 1}
```

```json
{"offerId": "OFFER_ID", "offerVersion": 123456, "quantity": 1}
```

- `quantity` 可选：默认 1，最多 20。
- 第一种请求体按国家（ISO 代码）、运营商和租期租用有货的最便宜方案，且必须带 `maxPriceMinor`，即每台设备你愿意支付的最高金额：如果你读取 `/stock` 后价格涨到它之上，请求会被拒绝并返回 `409 price_above_max`，不会扣费。
- 第二种请求体租用 `GET /catalog` 中确切的方案和价格版本。如果价格版本已变化，返回 `409 offer_changed_refresh`。

新订单和重复请求的响应相同：

```json
{
  "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/auth.md)决定入账的账户；任何密钥都可以，包括只读密钥。余额无法提取，智能体也无法动用客户的钱来充值。

接受充值的地址有两个，这是有意为之。`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`。

充值不会在链上退回：你支付的金额作为余额留在账户中，余额是服务抵用金。余额在什么情况下可以退款，见[付款与退款政策（英文）](/refunds)第 4 节 Balance。

你仍然可以在[控制台](https://ipvolt.com/dashboard)中自行充值，控制台的 **Support** 页面会列出通过这种方式完成的充值。

### 示例：先充值，再租用

每个版本都会读取可租方案，按美国 1 天租用的价格精确充值，等待入账，然后租用并打印连接信息。它需要在 `IPVOLT_API_KEY` 中提供一个读写 API 密钥，并在 `WALLET_PRIVATE_KEY` 中提供一个持有 Base 上 USDC 的钱包的私钥。不要把这两者放进提示词或日志。运行时会先花费 USDC，再花费余额。

#### cURL

需要 cURL 7.84 或更高版本和 jq，并用几行 Python 和 [eth-account](https://pypi.org/project/eth-account/) 完成签名。把 `PAYMENT_ID`、`ORDER_ID` 和 `RENTAL_ID` 换成前面应答中的 id。

```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

标准库加上用于签名的 [eth-account](https://pypi.org/project/eth-account/)（`pip install eth-account`）。

```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 或更高版本，使用 [viem](https://viem.sh)（`npm install viem`）签名。请把它保存为 `.mjs` 文件，放在安装了 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));
```

## 示例

每个示例执行相同的步骤：查看可租方案、租用、轮询订单、列出租用、轮换和续租。示例从环境变量 `IPVOLT_API_KEY` 读取密钥。租用和续租步骤会从余额扣费。

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

把 `ORDER_ID` 和 `RENTAL_ID` 替换为前面响应中的 id。

### Python

只用标准库。请把 `User-Agent` 设为你的软件名称。

```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 或更高版本，保存为 `.mjs` 文件。请把 `User-Agent` 设为你的软件名称。

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

## 幂等性

`POST /rentals` 和 `POST /rentals/{id}/extend` 需要 `Idempotency-Key`。它绑定你的账户：用同一个键重复请求，会返回同一订单且绝不重复扣费，无论由你的哪个密钥或智能体令牌发送，也无论第一次尝试是成功、失败还是仍在进行。同一个键配不同的请求体会被拒绝，返回 `409 intent_conflict`。键会一直跟随其订单，因此不能用于新的租用。每个新订单请使用新的随机值（例如 UUID），重试时使用同一个值。

## 每日限额

下单前会检查密钥的每日限额，依据是该密钥自 UTC 00:00 起已下的订单：当天经它下的每笔租用和续租，款项已退回余额的订单除外。同一密钥的请求逐个处理，因此不会有两个请求同时通过检查。会超出限额的请求被拒绝，返回 `409 daily_limit_exceeded`，不会扣费。`GET /key` 显示今天还剩多少。

## 错误

每个错误都是 JSON，包含稳定的错误代码 `error`、面向人的说明 `message`，以及在有帮助时附带的其他字段：

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

| 状态码 | `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 /stock` 300 个。
- 每个密钥 30 个租用和续租请求。每个账户还受控制台自身的限制：30 次购买、30 次续租、30 次设备操作和 240 次设备读取。

超出限制时返回 `429 try_again_later`。

## 活动日志

使用 API 密钥发出的每个请求都会记入该密钥的日志：时间、操作、HTTP 状态码、结果（`ok` 或错误代码），对于租用和续租还有扣费金额和订单 id。日志从不保存密钥、代理凭据、请求体或地址。在 **Account settings → API keys → Activity**（账户设置 → API 密钥 → 活动）中可查看每个密钥最近 100 条记录。记录保存 90 天后删除。

## 可接受使用

通过 API 进行的一切操作均适用[可接受使用政策（英文）](/acceptable-use)。

## 变更记录

- 2026 年 11 月 18 日：发布本参考文档，包括库存、密钥、租用、轮换和续租。
- 2026 年 11 月 18 日：API 只在 `https://ipvolt.com/beta/api/v1` 提供服务。发往 `/dashboard/api/v1`（此前控制台自带的 API 页面显示的地址）的请求会以 `308` 重定向到那里，请求方法和请求体保持不变。
- 2026 年 11 月 18 日：新增“由智能体充值”，说明 USDC 充值接受什么、它的限额和应答，以及一个先充值再租用的示例。

## 更多文档

- 下一页：[AI 智能体](https://ipvolt.com/zh/docs/ai-agents.md)
- [全部文档（英文）](https://ipvolt.com/docs.md)
- [阅读英文原文](https://ipvolt.com/docs/api.md)
