# AI agents

Source: https://ipvolt.com/docs/ai-agents
Markdown: https://ipvolt.com/docs/ai-agents.md

[Home](https://ipvolt.com/index.md) / [Docs](https://ipvolt.com/docs.md) / [AI agents](https://ipvolt.com/docs/ai-agents.md)

Section: API
Updated: 2026-11-18
Author: ipvolt

How an AI agent rents a mobile proxy for a day or 30 days, rotates its IP and extends it from your prepaid balance, with an API key and a daily limit.

An AI agent can run the whole loop on its own through the [API](/docs/api): check stock, add funds with its own USDC, rent a dedicated mobile proxy for 1 day or 30 days, get its connection details, rotate its IP and extend it. You set it up once with an API key; after that it needs no dashboard.

- API base address: `https://ipvolt.com/beta/api/v1`
- Payment address for top-ups: `https://ipvolt.com/api/v1`
- [API reference](/docs/api), [OpenAPI description](https://ipvolt.com/beta/api/v1/openapi.json) and [Proxy Toolkit MCP setup](/mcp)

## The loop

1. **Check stock:** `GET /stock`, no key needed.
2. **Add funds:** `GET /fund?amountMinor=N` answers `402` with an offer. The agent signs a USDC transfer on Base, sends it with its key and polls `statusUrl` until the payment is `credited`, usually within a few minutes. $1 to $500 per top-up; see Add funds from your agent in the [API reference](/docs/api).
3. **Rent:** `POST /rentals` with an `Idempotency-Key` and the most it may pay per device in `maxPriceMinor`, then `GET /orders/{orderId}` while the order is `paid`.
4. **Get connection details:** once the order is `fulfilled`, `GET /rentals/{id}` gives the proxy's host, ports, username and password.
5. **Rotate:** `POST /rentals/{id}/rotate` asks for a new IP.
6. **Extend:** `GET /rentals/{id}/extension-price`, then `POST /rentals/{id}/extend` with an `Idempotency-Key` and `maxPriceMinor`.

Renting and extending spend the balance and count against the key's daily limit. A top-up spends the agent's own USDC, never the customer's money, and is not refunded on chain: it stays as balance.

## Set it up once

1. Under **Account settings → API keys** in the [dashboard](https://ipvolt.com/dashboard), create a key with read-write access, an expiry of 30 or 90 days and a daily limit. Copy the key: it is shown once.
2. Give the key to the agent in the `IPVOLT_API_KEY` environment variable, never in a prompt.
3. For top-ups, give it a wallet that holds USDC on Base, with the private key in its environment too. You can also add funds yourself in the dashboard.

A key with read access lets an agent look without spending. The [API reference](/docs/api) has every endpoint, the errors and examples in cURL, Python and Node.js, one of them a top-up followed by a rental.

## Proxy Toolkit MCP

Run locally, the [Proxy Toolkit MCP](/mcp) server adds account tools when `IPVOLT_API_KEY` is set in its environment; they use the API with that key. Without the variable the local server has no account tools, and the hosted server at `https://mcp.ipvolt.com/mcp` keeps its four tools, which need no key.

```json
{
  "mcpServers": {
    "ipvolt-proxy-toolkit": {
      "command": "npx",
      "args": [
        "--yes",
        "@ipvolt/proxy-toolkit-mcp@0.3.0"
      ],
      "env": {
        "IPVOLT_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

The configuration holds the key, so keep the file private. To try the tools before you have an account, set `IPVOLT_SANDBOX` to `1` in place of the key: they then run on a simulated account inside the local server, send no request to ipvolt and charge nothing.

## Without an account

An agent can also rent a dedicated mobile proxy with no ipvolt account. It creates an order with `POST /guest/orders`, accepting the Terms, and gets an invoice ID once. It pays with its own USDC at the payment address above, sending the invoice ID in the `Authorization` header, and then rents with `POST /rentals`. `GET /guest` has the steps, the Terms version and the limits. The invoice ID is the only way back to the order: the agent must keep it secret and safe. Mobile rentals only; traffic per GB needs an account.

## Agent tokens

An agent can also get access through [auth.md](https://ipvolt.com/auth.md) instead of a key: you confirm it with a 6-digit code and choose view-only access or a spending cap.

The [Acceptable Use Policy](/acceptable-use) applies to everything an agent does through the API.

## More documentation

- Previous: [API reference](https://ipvolt.com/docs/api.md)
- Next: [Billing and renewals](https://ipvolt.com/docs/billing.md)
- [All documentation](https://ipvolt.com/docs.md)
