---
title: "agvps reference"
description: "How a call is paid, the plans and routes, ordering and delivery, renewal, failures, limits, MCP and discovery. The machine-readable version is at /agents.md and /openapi.json."
canonical: "/docs"
updated: "2026-10-07"
---

# agvps reference

How a call is paid, the plans and routes, ordering and delivery, renewal, failures, limits, MCP and discovery. The machine-readable version is at /agents.md and /openapi.json.

## Overview and how a call is paid

agvps rents a Linux server by the month. Each call is paid over x402 on Base, Polygon and Solana or MPP on Base. There are no API keys, accounts or subscriptions.

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 in a `WWW-Authenticate: Payment` challenge (MPP).

Sign one and send the same body again with `PAYMENT-SIGNATURE` (x402) or `Authorization: Payment` (MPP). Both protocols are accepted on both paths, `/x402/<name>` and `/mpp/<name>`.

The payment settles only after the call is accepted. A call that cannot be served is not charged.

Errors the service produces are JSON: `{"error": code, "message": text}`. A request body over 64 KiB is refused with 413.

## Plans and routes

Two plans are sold. Both run Ubuntu 24.04 with a public IPv4 address, in Germany (`de`, the default) or Finland (`fi`).

RouteWhat it is

POST /x402/vps-smallServer, 1 vCPU 1 GB RAM

POST /x402/vps-small-renewRenew a small server

POST /x402/vps-mediumServer, 2 vCPU 2 GB RAM

POST /x402/vps-medium-renewRenew a medium server

Each plan has a renewal route, named with `-renew` after the plan. The same routes answer under `/mpp/` too. A renewal must use the route of the server's own plan.

## Order and delivery

The body is `{"location":"de","hostname":"my-server"}`. Both fields are optional. `location` is `de` or `fi`; `hostname` is 1 to 40 lowercase letters, digits or dashes.

The paid answer is a JSON array with one record: `id`, `secret`, `plan`, `specs`, `os`, `location`, `hostname`, `status` (`queued`), `status_url` and `next`. Keep the `id` and the `secret`. The secret is shown only in this answer; it is the login for the server's page.

The server is ordered only after the payment has settled. A payment that never settles orders nothing.

The server is ready about 5 to 10 minutes later. Poll `GET /v1/vps` with the id and the secret as HTTP Basic credentials: `curl -u ID:SECRET https://agvps.shveik.dev/v1/vps`.

`status` goes `queued`, `provisioning`, `active`. The first answer with `ssh_ready` true carries `host`, `port`, `user` and `command`.

The root `password` is shown once, in the answer that first carries it; that can come a little before `ssh_ready` is true. If you missed it, `POST /v1/vps/reset-password` makes a new one, once every 30 seconds. `POST /v1/vps/reboot` restarts the server.

## Renewal

A server is paid for one month. `expires_at` in the status says when it stops; renew before then.

`POST /x402/vps-small-renew` (or `/x402/vps-medium-renew`, or the same under `/mpp/`) with `{"id":"vps_...","months":1}`. `months` is 1 to 6, default 1. The price is the plan's monthly price times `months`. A server cannot be paid more than 12 months ahead.

The renewal answer is a JSON array with one record: `id`, `months` and `status` (`queued`). The extension is applied once the payment has settled; `GET /v1/vps` then shows the new `expires_at`. Anyone who knows the id can pay for a renewal; only the secret gives access.

Nothing renews by itself. A server that is not renewed stops at its expiry date.

## Failures and refunds

A call that cannot be served is refused before its payment settles, and is not charged. Reasons: the service is sold out right now, the server id is unknown, or the renewal route does not match the server's plan.

A payment that never settles is dropped. Its server is never ordered, and `GET /v1/vps` shows `cancelled`.

If an order fails after the payment, the service retries it. When it cannot be made, `GET /v1/vps` shows `failed`. Such a payment is refunded by the operator, by hand; the payment id is in your receipt.

## Limits

Capacity is capped. When it is reached, quotes say the service is sold out right now, and a payment sent anyway is refused before it settles. Try again later.

Servers run Ubuntu 24.04, with root access and a public IPv4 address.

Use a server within the supplier's rules: no spam, malware, botnets, attacks on other networks or mass scanning. A server used that way is shut down without a refund.

## MCP

The MCP server is at `https://agvps.shveik.dev/mcp`, with one tool per endpoint. A tool takes the same JSON as its endpoint and pays with x402 inside the tool call.

Listing the tools and getting quotes works in any MCP client. Paying needs a client that can sign x402 payments.

## 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.

There is no published order-completion time guarantee; delivery depends on capacity and supplier response. A failed order is retried and, if it cannot be made, refunded manually. Free GET document requests follow the shared limit below.

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

Server rental services organize orders around customer accounts; agvps quotes each order for stablecoin payment and orders after settlement.

## Discovery

`/agents.md`: the guide for agents (preferred; `/llms.txt` is the same text)

`/openapi.json`: request schemas and the payment information (OpenAPI 3.1)

`/.well-known/x402`: the x402 manifest

`/pricing.md`: generated endpoint prices and quote behavior

`/docs`: this API reference, with request examples

`/mcp`: the MCP server

`/health`: the service status

`POST /feedback`: a free note to the operator, with no payment and no account

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/agvps) · [Glama listing](https://glama.ai/mcp/connectors/dev.shveik/agvps) · [Smithery listing](https://smithery.ai/servers/shveik/agvps) · [Agent kit on GitHub](https://github.com/shveik-dev/agent-kit) · [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/<name>` and `/mpp/<name>` 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, Polygon and Solana 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

vps-small
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://agvps.shveik.dev/x402/vps-small' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"hostname":"my-server","location":"de"}
JSON`

Paid retry paths: `https://agvps.shveik.dev/x402/vps-small` (x402) or `https://agvps.shveik.dev/mpp/vps-small` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
vps-small-renew
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://agvps.shveik.dev/x402/vps-small-renew' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"id":"vps_0123456789abcdef","months":1}
JSON`

Paid retry paths: `https://agvps.shveik.dev/x402/vps-small-renew` (x402) or `https://agvps.shveik.dev/mpp/vps-small-renew` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
vps-medium
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://agvps.shveik.dev/x402/vps-medium' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"hostname":"my-server","location":"de"}
JSON`

Paid retry paths: `https://agvps.shveik.dev/x402/vps-medium` (x402) or `https://agvps.shveik.dev/mpp/vps-medium` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
vps-medium-renew
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://agvps.shveik.dev/x402/vps-medium-renew' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"id":"vps_0123456789abcdef","months":1}
JSON`

Paid retry paths: `https://agvps.shveik.dev/x402/vps-medium-renew` (x402) or `https://agvps.shveik.dev/mpp/vps-medium-renew` (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://agvps.shveik.dev/install.sh | sh
agvps help
agvps 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.