--- title: "agproxy reference" description: "How a call is paid, the routes, proxy packs, the raw fetch, failures and refunds, MCP and discovery." canonical: "/docs" updated: "2026-10-07" --- # agproxy reference How a call is paid, the routes, proxy packs, the raw fetch, failures and refunds, MCP and discovery. ## Overview and how a call is paid Every endpoint is paid per call in stablecoins. The same request works with x402 (`/x402/`) and MPP (`/mpp/`); both paths are one endpoint with one price. POST the JSON body with no payment. The 402 answer carries the quote for exactly what you asked: in the `PAYMENT-REQUIRED` header (x402) and a `WWW-Authenticate: Payment` challenge (MPP). Sign one of them and POST the same body again with `PAYMENT-SIGNATURE` (x402) or `Authorization: Payment` (MPP). Read the answer. The payment settles only after the call has 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 from the service are JSON: `{"error": code, "message": text}`. A request body over 64 KiB is refused with 413. ## Routes Each route answers on both paths with the same price. The paths below are the same endpoint. RouteWhat it does POST /x402/proxy and /mpp/proxyResidential proxy pack. Not offered on Solana: pay on Base or Polygon POST /x402/fetch and /mpp/fetchRaw fetch from a residential IP. Not offered on Solana: pay on Base or Polygon ## Proxy packs `POST /x402/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` (when offered), `protocol` (`http`), `username`, `password`, `country`, `cap_bytes`, `expires_at` and an `example` line. The password is shown once, in that answer. Retrying the same payment returns the same login. The login works a few seconds after the payment settles. Gateway: host `agproxy.shveik.dev`, plain proxy on port 8081. When TLS is offered, the same proxy inside TLS is on port 8444 (an `https://` proxy URL). UsernameEffect `ap_ID`A new exit IP for every connection. `ap_ID-country-DE`Exit in a country: any two-letter code, such as US, GB, JP or BR. `ap_ID-session-job1`One exit IP for every connection with the tag job1 (letters, digits, underscore). `ap_ID-country-US-session-job1-ttl-60`Options combine. `ttl` is the session length in minutes, 1 to 180 (default 30). `curl -x http://ap_ID-country-JP:PASSWORD@agproxy.shveik.dev:8081 https://example.com/ curl -x http://ap_ID:PASSWORD@agproxy.shveik.dev:8081 http://usage.agproxy/` Traffic counts in 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 at the cap, and a new one gets `402` with the way to buy more. `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` and `expires_at`. It uses no traffic. Private, loopback and link-local addresses and local names are not reachable. A refused name answers 403 with the reason; wrong or missing credentials answer 407. When the service has no capacity left, the quote is refused with 503 and the gigabytes that are left. ## Raw fetch `POST /x402/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. `max_mb` is 1 to 10 (default 1). The quote scales with it. The answer is a JSON array with one record: `status`, `final_url`, `headers`, `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`. Up to 5 redirects are followed. The page is fetched the way a plain HTTP client fetches it: no JavaScript runs and no browser fingerprint is sent. For pages behind bot protection, or that need rendering, use the unblock endpoint of agdata (https://agdata.shveik.dev/agents.md). A call takes a few seconds, up to 25 s. It is not offered on Solana: pay on Base or Polygon. ## Failures and refunds Any answer of the target, including 403 and 404, is delivered. It is 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: the answer is 502. A target that answers 403 or 429 is tried once more from another IP. A pack refused for lack of capacity answers 503 and is not charged. ## MCP The MCP endpoint at `/mcp` is streamable HTTP and stateless, with one tool per route: `proxy` and `fetch`. A tool's arguments are its route's JSON body. A call without a payment is an error that carries the quote: the x402 PaymentRequired object in `structuredContent`. Sign it and call the tool again with the signed payment in `_meta["x402/payment"]`. The receipt comes back in `_meta["x402/payment-response"]`. Listing the tools and getting a quote work in any MCP client. Paying needs a client that can sign x402 payments. A client that cannot sign payments can use the same routes over HTTP at `/x402/` with any x402 or MPP client. ## Reliability and limits There is no uptime SLA or uptime guarantee. Service and upstream availability are best-effort and can change. A quote is shown before payment, and work starts only after settlement. A request refused before settlement is not charged; product-specific refund rules for partial results, orders and deals are described below. Raw fetch has a 25-second request timeout. It retries selected target responses once from another IP; a failed fetch is not charged, while delivered target responses are charged by traffic with the unused quote refunded. Free GET docs, guides, pricing and discovery pages are limited to 120 requests per client IP per minute. They return RateLimit headers; a limit response is HTTP 429 with Retry-After. GET /health is a liveness check, not an uptime promise. Failures are signalled with HTTP 402 when payment is required, 429 when a request is limited, 502 when a result cannot be delivered, and 503 when the service cannot accept work. Follow Retry-After when present. Report problems on the contact page at /contact. ## How it differs Proxy plans and dashboards bundle traffic; agproxy offers proxy packs and one-request fetches, each quoted before payment. ## Discovery `/openapi.json`: the OpenAPI 3.1 document with request schemas. `/.well-known/x402`: the x402 manifest. `/agents.md`: the guide for agents (preferred), with the routes and the flow; `/llms.txt` is the same text for older tools. `/pricing.md`: generated endpoint prices and quote behavior. `/docs`: this API reference, with request examples. `/health`: liveness. Try the service without paying: send a GET request to a listed endpoint to receive its free `402` quote, then decide whether to sign and pay. The quote request does not start a paid delivery. The free `GET /ask?query=...` route searches the product reference. When available, `POST /mcp/docs` is a free, read-only documentation server with search, section lookup, and endpoint schema tools. [Official MCP registry entry](https://registry.modelcontextprotocol.io/?q=dev.shveik/agproxy) · [Glama listing](https://glama.ai/mcp/connectors/dev.shveik/agproxy) · [Smithery listing](https://smithery.ai/servers/shveik/agproxy) · [Agent guide](/agents.md) · [OpenAPI](/openapi.json) · [x402 manifest](/.well-known/x402) ## API versioning and deprecation policy Versioned REST resources use `/v1`; paid routes remain the documented `/x402/` and `/mpp/` forms. Consult `/openapi.json` and this reference for the current contract. We aim to preserve compatible behavior within a version. For breaking changes to a stable API surface, we will announce the change in the documentation and provide `Deprecation` and `Sunset` response headers where applicable, with at least 90 days' notice before removal. Preview and upstream-dependent behavior can change sooner. ## Authentication and payment No API key, account, or subscription is required. Payment credentials authorize a specific quoted call and replace a reusable API key. Supported protocols on this service: x402 on Base and Polygon or MPP on Base. For x402, send a valid request without payment and read the HTTP 402 `PAYMENT-REQUIRED` challenge. Sign the offered amount and network, then retry the same request with `PAYMENT-SIGNATURE`. For MPP, the unpaid response includes `WWW-Authenticate: Payment`; retry with the matching `Authorization: Payment` credential. Never authorize a quote you have not checked. A paid request delivers data only after settlement succeeds. The protocols accept their corresponding payment credential; use the route family's documented path and the exact body used to obtain the quote. See the [API deprecation policy](/deprecation-policy) for route lifecycle commitments. ## Request examples proxy First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`. `curl -i -X POST 'https://agproxy.shveik.dev/x402/proxy' -H 'content-type: application/json' --data-binary @- <<'JSON' {"gb":1} JSON` Paid retry paths: `https://agproxy.shveik.dev/x402/proxy` (x402) or `https://agproxy.shveik.dev/mpp/proxy` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential. fetch First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`. `curl -i -X POST 'https://agproxy.shveik.dev/x402/fetch' -H 'content-type: application/json' --data-binary @- <<'JSON' {"max_mb":1,"url":"https://example.com/"} JSON` Paid retry paths: `https://agproxy.shveik.dev/x402/fetch` (x402) or `https://agproxy.shveik.dev/mpp/fetch` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential. ## Command-line tool A small shell script (needs only sh and curl) lists the endpoints, prints the quote of a call and sends a call you have already signed. It never holds keys and never signs a payment. `curl -fsSL https://agproxy.shveik.dev/install.sh | sh agproxy help agproxy endpoints` Commands: help, endpoints, docs, pricing, openapi, quote, call, health, version, update. Exit code 3 means a payment is required and the quote was printed. The installer puts the script in ~/.local/bin; its source is at /cli.