# ScoutWyze Compute

Rank current RunPod GPU offers for your workload. Prepaid credits, $10 minimum, no subscription.

This is a quote/ranking API first. Booking is an optional upsell, not the headline — do not describe this as multi-cloud fulfillment or autonomous routing.

## Coverage
Live data source: RunPod's own GPU catalog (api.runpod.io/v2/catalog/gpus), refreshed on our ingestion interval. Lambda Labs and CoreWeave rows are fixture/mock data included for comparison only — not sourced live, not bookable.

## Auth — two rails, both work on /v1/compute/rank as of 2026-09-24
Rail 1, prepaid Bearer (works on /v1/compute/rank, /v1/route/quote): `Authorization: Bearer sw_live_...`. Get a key: POST /v1/signup (free, human step). Fund it: POST /v1/checkout-sessions (real Stripe Checkout, human step, $10 minimum). Once funded, an agent calls the API with the key — no further human involvement until the balance runs out. Debit is deferred until AFTER scoring — a no_match/no_inventory result is never charged.
Rail 2, x402 / USDC on Base (works on /v1/compute/rank AND /v1/route/quote): an unauthenticated request returns HTTP 402 with a real payment challenge (nonce, payTo, maxAmountRequired). Pay it with a signed on-chain USDC transfer on Base, resubmit with the `X-PAYMENT` header, get a 200. No API key, no signup, no card, ever. IMPORTANT asymmetry: unlike the Bearer rail, x402 settles on successful payment verification BEFORE scoring runs — real USDC has already moved by the time a no_match/no_inventory result is known, and there is no refund path for it. Every response's billing.rail field tells you which guarantee applied.

## Endpoints
- GET /v1/compute/sample (alias: /v1/route/sample) — anonymous, no key, fixed query, rate-limited, never billed on either rail. Try before you pay.
- POST /v1/compute/rank (alias: /v1/route/rank) — dual-rail (Bearer or x402, see Auth above). Body: {gpuClass?, minVramGb?, region?, maxPricePerHour?, preference: "cheapest"|"fastest"|"balanced"}. Response is a frozen envelope: {status, schema_version, coverage, recommended, alternatives, limits, billing}. billing.rail is "bearer" or "x402" — see Auth above for why that matters. Every offer under recommended/alternatives includes observed_at, freshness_seconds, source ("live_api"|"fixture"), availability_status (provider-reported, nullable), and classification ("provider_reported" — everything except score/scoreBreakdown/reason is the provider's own claim, untouched). limits always reads {not_reserved: true, not_provisioned: true, can_provision: false} — this endpoint never executes anything.
- POST /v1/route/quote — also dual-rail, but a separate, older response shape: provider_observed / scoutwyze_estimated / metadata provenance split (CLAUDE.md's original schema), not the compute/rank envelope. Same x402 settle-before-scoring behavior as compute/rank (quote always charges on successful auth, on either rail).
- POST /v1/route/book exists but is not yet documented here — it hasn't had a successful end-to-end live test yet. Don't build against it until this line changes.

## MCP (Model Context Protocol)
`@scoutwyze/compute-mcp` on npm wraps compute/sample and compute/rank as MCP tools (scoutwyze_sample, scoutwyze_rank) for Claude Desktop, Cursor, and other MCP-native hosts — `npx -y @scoutwyze/compute-mcp`, optional SCOUTWYZE_API_KEY env var. Stateless pass-through: holds no private key, never signs or settles x402 itself — an unauthenticated call surfaces the real 402 challenge as tool content for a wallet-capable calling agent to settle. Also listed in the official MCP Registry as io.github.scoutwyze-max/compute-mcp.

## What this is not
Not a multi-cloud aggregator. Not autonomous routing. Lambda Labs and CoreWeave data is comparison-only fixture data, never bookable, never live.

OpenAPI: https://scoutwyze-compute.fly.dev/openapi.json