// API REFERENCE

REST API

The Quiver backend is a plain JSON REST API. Everything is JSON, CORS is open, and write endpoints in Governance require a Bearer JWT obtained via wallet signature.

Base URL (dev):http://localhost:3001
// Index & Routing
GET/health
Service status and number of indexed offers.
GET/index
Full normalized price index, sorted by price ascending. Optional filters: source, gpuClass, region.
GET /index?gpuClass=H100&region=US
→ { updatedAt, count, offers: NormalizedOffer[] }
POST/route
Best single route for a job spec (a quote, not a job run). Sorted by effective price (price + reliability penalty).
{ "gpuClass": "H100", "durationHours": 5,
  "region": "US", "reliabilityFloor": 0.85 }
→ { offer, estimatedTotalUsd, routedAt }
POST/route/top
Top-N routes for showing alternatives in the UI. Body is a RouteRequest plus an optional limit (default 5).
GET/stats
Aggregated stats over the current index: totals and breakdowns by source / class / region, plus the 3 cheapest offers.
POST/index/refresh
Force a re-index now (heavy — admin/debug only).
// Auth (Solana wallet signature)
POST/auth/nonce
Request a nonce + the exact message string to sign with the wallet.
{ "wallet": "<base58 pubkey>" }
→ { nonce, message: "Sign in to Quiver\n\nnonce: ..." }
POST/auth/login
Exchange a base58 signature of the message for a JWT (valid 7 days).
{ "wallet": "<pubkey>", "signature": "<base58 sig>" }
→ { token: "<JWT>" }
GET/auth/meJWT
Current user for the supplied Bearer JWT.
// Governance (snapshot voting)
GET/governance/proposals
List proposals with vote tallies. Optional filter: status=active|passed|rejected.
GET/governance/proposals/:id
A single proposal (404 if not found).
POST/governance/proposalsJWT
Create a proposal. Body: { title, description, category?, durationDays? }. Author is taken from the JWT.
POST/governance/proposals/:id/voteJWT
Vote on a proposal. Body: { choice: "for" | "against" }. One wallet = one vote (re-voting overwrites).
// DATA MODEL
The core object returned by /index and embedded in route results:
interface NormalizedOffer {
  id: string;
  source: 'akash' | 'ionet' | 'nosana';
  providerId: string;
  gpuClass: GpuClass;        // 'H100' | 'A100' | ... | 'OTHER'
  gpuModelRaw: string;       // original model name
  availableCount: number;
  vramGb: number;
  region: 'US' | 'EU' | 'ASIA' | 'OTHER';
  pricePerHourUsd: number;
  priceNative?: { amount: number; token: string };
  reliability: number;       // 0..1
  reputationScore: number;   // 0..100
  ncuMultiplier: number;
  pricePerNcuUsd: number;    // = pricePerHourUsd / ncuMultiplier
  indexedAt: number;         // Unix ms
}
← Back to DocsSDK Quickstart →Try routing →