# agproxy

> Residential proxies for AI agents: buy a pack of traffic (gigabytes) and get a proxy login, or fetch one URL from a residential IP. Each call is paid in stablecoins: x402 on Base and Polygon or MPP on Base. No API keys, accounts or subscriptions.

## How a call is paid

- POST the JSON body to the endpoint with no payment. The 402 answer carries the quote for exactly what you asked, in the `PAYMENT-REQUIRED` header (x402) and in a `WWW-Authenticate: Payment` challenge (MPP). Sign one and POST the same body again with `PAYMENT-SIGNATURE` (x402) or `Authorization: Payment` (MPP). Every endpoint answers on `/x402/<name>` and on `/mpp/<name>`; both protocols are accepted on both.
- The payment settles only after the call succeeded. A call that cannot be served (no exit, a refused tunnel, no capacity) is not charged. Retrying with the same payment returns the stored answer.
- Errors the service itself produces are JSON: `{"error": code, "message": text}`. A request body over 64 KiB is refused (413).

## Proxy packs

- POST `/x402/proxy` (or `/mpp/proxy`) with `{"gb":1,"country":"DE"}`. `gb` is a whole number of gigabytes, 1 to 100 (default 1); `country` is an optional two-letter default exit country.
- The answer is a JSON array with one record: `host`, `port`, `tls_port` (only when the proxy inside TLS is offered), `protocol` (`http`), `username`, `password`, `country`, `cap_bytes`, `expires_at` and an `example` curl line. The password is shown once, in this answer; retrying the same payment returns the same login. The login works as soon as the payment has settled (a few seconds).
- Use it as an HTTP proxy: `curl -x http://USERNAME:PASSWORD@HOST:PORT https://example.com/`. HTTPS targets go through CONNECT, plain http targets through the proxy request. When `tls_port` is present it is the same proxy inside TLS (an `https://` proxy URL) for clients that should not send the password in the clear.
- Username options, appended with dashes: `-country-DE` picks the exit country (any two-letter code the network has), `-session-TAG` keeps one exit IP for connections that use the same tag (letters, digits, underscore), `-ttl-60` is how many minutes a session lasts (1 to 180, default 30). Without a session tag every connection gets a new IP. Example: `ap_0123456789abcdef-country-DE-session-job1`.
- Traffic counts on both directions through the upstream, including the tunnel set-up. A pack ends at its byte cap or after 90 days; an open connection is closed when the cap is reached and a new one gets `402` with the way to buy more. `GET http://usage.agproxy/` through the proxy, or `GET /v1/usage` on this site with the proxy username and password as HTTP Basic auth, returns `{used_bytes, cap_bytes, remaining_bytes, expires_at}` and uses no traffic.
- Not reachable through the proxy: private, loopback and link-local addresses and local names. A name the service refuses answers `403` with the reason; wrong or missing credentials answer `407`; a pack whose payment has not settled yet answers `407` with that text.
- When the service has no capacity left the quote is refused with `503` and the gigabytes that are left; ask for fewer or try later.

## Fetch

- POST `/x402/fetch` (or `/mpp/fetch`) with `{"url":"https://example.com/","method":"GET","country":"DE","max_mb":1}`. `url` is required; `method` is GET (default), HEAD or POST; `headers` is an object of request headers; `body` is the POST body (at most 1 MiB); `country` is a two-letter exit country; `max_mb` is 1 to 10 (default 1) and is what the quote scales with.
- The answer is a JSON array with one record: `status`, `final_url`, `headers` (content-type, last-modified, etag, location, cache-control and a few more), `body` (UTF-8 text) or `body_base64` (anything else), `bytes`, `truncated` (true when the body was cut at `max_mb`), `elapsed_ms` and `wire_bytes`.
- Any answer of the target, 403 and 404 included, is delivered and charged by the traffic it took, rounded up to whole megabytes (at least one); the rest of the quote is refunded on-chain to the paying address. A request that fails on the way is not charged: `502`. A target that answers 403 or 429 is tried once more from another IP. Up to 5 redirects are followed.
- It fetches the page as a plain HTTP client does: no JavaScript is run and no browser fingerprint is sent. For pages behind bot protection or that need rendering, use agdata's unblock endpoint at https://agdata.shveik.dev/llms.txt.
- A call takes a few seconds and up to 25 s. It is not offered on Solana: pay on Base or Polygon.

## Try also agdata

- Need the page rendered, unblocked and returned as Markdown, or structured data from social, maps, search, news and jobs? agdata does that, paid the same way. Site: https://agdata.shveik.dev, docs: https://agdata.shveik.dev/llms.txt

## Endpoints

- [POST /x402/proxy](https://agproxy.shveik.dev/x402/proxy): Residential proxy pack. Example body: `{"gb":1}`
- [POST /x402/fetch](https://agproxy.shveik.dev/x402/fetch): Raw fetch from a residential IP. Example body: `{"max_mb":1,"url":"https://example.com/"}`

## Machine-readable

- [OpenAPI 3.1](https://agproxy.shveik.dev/openapi.json): full request schemas and x-payment-info
- [x402 manifest](https://agproxy.shveik.dev/.well-known/x402)
- [MCP server](https://agproxy.shveik.dev/mcp): one tool per endpoint, payments with x402 inside the tool call
- [Health](https://agproxy.shveik.dev/health)