---
name: amplerun
description: Rent GPUs and run AI models on AmpleRun, or list this machine's GPU to earn. Covers signing up (wallet signature or API key), funding (deposit address or x402 in USDC), picking a model or GPU, deploying with a hard budget cap, checking status, calling the OpenAI-compatible endpoint, stopping and reading the bill, and hosting. Use when the user wants GPU compute, a hosted open model, cheaper inference, or to earn from a GPU, or mentions AmpleRun.
compatibility: Needs HTTPS access to amplerun.com. Works over MCP (https://amplerun.com/api/mcp), the REST API, or the TypeScript and Python SDKs.
metadata:
  author: amplerun
  version: "1.0.0"
  homepage: https://amplerun.com/docs/agents
---

# AmpleRun

AmpleRun is a GPU marketplace with escrow. Independent hosts list GPUs; you rent one for a model or a container and pay by the millisecond from verified readiness, out of a prepaid USDC or USDT balance. A start that never gets ready is not charged.

Base URL: `https://amplerun.com`. Machine-readable contract: `https://amplerun.com/openapi/openapi.json`.

## Safety rules (read first)

1. **Never spend more than the user allowed.** Every rental needs `budget_micro`, a hard cap: nothing is charged above it. Set it to the user's budget, not higher.
2. **Ask before spending** if the user asked to confirm purchases, or gave no budget. Quote first (free), show the price, then rent.
3. **Ask before installing anything** on a machine. The host installer needs the owner's yes.
4. **Keep secrets secret.** Never print or log an API key (`ark_...`) or a wallet private key. Never send a private key to any tool or API.
5. **Stop what you start.** When the task is done, stop the rental. Metering stops with it.
6. Money is integer strings in micro-units: `"1000000"` is 1 USDC. Never use floats for money.

## Choose how to connect

- **MCP (preferred):** `https://amplerun.com/api/mcp`, Streamable HTTP, header `Authorization: Bearer ark_...`. Without a key it serves only the two sign-up tools. Tools: [references/mcp-tools.md](references/mcp-tools.md).
- **REST:** any HTTP client. Cheatsheet with curl: [references/api.md](references/api.md).
- **SDKs:** `npm i @amplerun/sdk` (TypeScript, can pay over x402). Python: `sdk/python` in the repo, not yet on PyPI.

## 1. Get an account

Either the user gives you an API key (created at https://amplerun.com/account#api-keys; the `renter` scope can rent, without it the key is read-only), or you sign yourself up with a wallet, no email:

1. `POST /api/v1/agents/accounts/challenge` with `{"address":"0x..."}`. Returns `message` (single use, five minutes). Signing it accepts the Terms it names.
2. Sign `message` exactly as returned (personal_sign, EIP-191).
3. `POST /api/v1/agents/accounts` with `{"message","signature","agent":{"name","vendor"}}`. Add `"scopes":["renter","host"]` to host too. Returns `api_key.secret`, shown once. Store it securely.

The same wallet always returns the same account. There is no free credit.

## 2. Fund the balance

- **x402 (no deposit address):** `POST /api/v1/billing/x402/top-up?amount_micro=5000000` with the key. It answers 402 with `accepts` (one entry per network; Base by default). Sign one entry as an EIP-3009 `transferWithAuthorization` and repeat the request with the `PAYMENT-SIGNATURE` header. The credit lands after the network's finality.
- **Deposit:** `GET /api/v1/billing/deposit-address` and send USDC or USDT there on a listed network.
- Check with `GET /api/v1/billing` (spendable, held, withdrawable).

## 3. Rent and run

1. **Pick.** `GET /api/v1/templates` (models and runtimes, no key) and `GET /api/v1/offers?template_id=<id>` (live machines, cheapest first; each offer carries `fit.fits`). Choose an offer whose `fit.fits` is true.
2. **Quote (free, 60 s).** `POST /api/v1/quotes` with `offer_id`, `template_id`, `duration_limit_s`, `budget_micro` and an `Idempotency-Key` header. Read the price and `platform_fee_bps` from the quote.
3. **Rent.** `POST /api/v1/jobs` with `quote_id` (and `ssh_public_key` for SSH templates) and an `Idempotency-Key`. Retrying with the same key never rents twice.
4. **Wait for RUNNING.** Poll `GET /api/v1/jobs/{id}`: RESERVED, STARTING, RUNNING (the meter starts here), then STOPPING, STOPPED. FAILED means a named reason and no charge for an unready start.
5. **Use it.** `GET /api/v1/jobs/{id}/access` gives endpoints and the SSH host-key fingerprint. For model templates, point any OpenAI client at `https://amplerun.com/api/v1/jobs/{id}/openai/v1` with your AmpleRun key (`/models`, `/chat/completions`, `/completions`, `/embeddings`).
6. **Stop.** `POST /api/v1/jobs/{id}/stop` with `{"reason":"done"}` and an `Idempotency-Key`. Repeating is harmless.
7. **Read the bill.** `GET /api/v1/billing/receipts/{id}` for the itemized receipt.

Over MCP the same flow is `list_templates`, `search_offers`, `get_quote`, `create_rental`, `get_rental`, `stop_rental`. `pay_for_rental` reserves and, when the USDC balance does not cover the budget, returns an x402 payment for the shortfall. The payment is credited like a deposit. That rental offers mainnet only when the operator set `X402_MAINNET_ENABLED`. Top-ups keep the networks already offered. Base Sepolia is `eip155:84532`.

## 4. Host a GPU (earn for the owner)

Only with the machine owner's yes.

- Linux (NVIDIA or AMD), needs root: `curl -fsSL https://amplerun.com/host | sudo bash -s -- --json`
- Mac (Apple silicon), no sudo: `curl -fsSL https://amplerun.com/host | bash -s -- --json`
- Modes (Linux, `--mode`): `dedicated` (never interrupted), `idle` (only while the owner is away), `colisted` (also listed on other platforms). Idle and co-listed rentals are sold as Interruptible.

With `--json` it prints one JSON object per line: checks, then `pairing_code` and `approve_url`, then `live`. The owner opens `approve_url`, or an agent account with the `host` scope approves with `POST /api/v1/hosts/pairings/approve`. The approving account is paid in USDC on Base. Nothing is listed without an approval, and rentals are not promised. Over MCP, `host_this_machine` mints an enrollment token and returns the install command. `list_my_machines`, `set_price` and `get_earnings` manage a host fleet. Pass `owner_account_id` when an owner delegated that fleet.

## Fees

A 10% platform fee is included in the listed price; hosts receive 90%. The renter pays the price shown and nothing is added on top. Every quote states the fee in `platform_fee_bps` and the total in `estimated_total_micro`; when this file and a quote disagree, the quote is right. No other platform fees. You pay network gas on your own deposit.

## Errors

Errors are `{"error":{"code","message","retryable","request_id"}}`. Retry only when `retryable` is true, with the same `Idempotency-Key`. Common codes: `QUOTE_EXPIRED` (quote again), `INSUFFICIENT_FUNDS` (top up or lower the budget), `UNAUTHENTICATED` (bad key), 403 (key lacks the `renter` or `host` scope), 429 (slow down).

## More

- Agents guide: https://amplerun.com/docs/agents.md
- Everything in one file: https://amplerun.com/llms-full.txt