{"openapi":"3.1.0","info":{"title":"Compute State API","version":"1.0.0","contact":{"email":"StateAPI@proton.me"},"description":"Compute State API answers one question: which compute SKU is cheapest\nto run this job right now, from official vendor pages.\n\nOne paid route: GET /v1/cheapest, 0.005 USDC, x402 v2, PayAI, Base or Solana.\nNo API key. Agents: GET /healthz first (stop if stale or payments.ok is false),\nGET /v1/example for the shape, then unpaid GET /v1/cheapest for the 402.\nPay only the networks in that 402 accepts list.\n\nNo body, no settle; no settle, no charge. Paywall order is part of the\ncontract: unpaid GET /v1/cheapest always 402s (bare path or illegal work\nincluded) and pins nothing to rank. A valid query against a stale or empty\nbook is an unpaid 503 before any signature. A signed payment is verified\n(no money moves); a bad query after verify is an unpaid 400. Then rank the\npinned book, build the body, settle, and respond 200 or a paid no-match 404.\nYou are charged only when settlement succeeds and we have an answer in\nhand. 400, 402, unpaid 503, and 500 all happen before money moves. A 500\nis our crash, not a stale book — we do not settle if we cannot build the\nbody. If the HTTP response is lost after settlement, retry the same\nsignature; we will not charge twice. The pinned book is ranked even if\nstale_after_s elapsed during the wallet step.\n\nCurrent monitored fleet: 16 companies across 17 official feeds — 11\ninference feeds and 6 GPU feeds. The companies are OpenAI, Anthropic,\nGoogle, Groq, Together AI, DeepSeek, Mistral AI, Fireworks, xAI, RunPod,\nLambda, Crusoe, MiniMax, Cerebras, Nebius and Hyperstack. Fireworks has\ntwo feeds because it sells both serverless tokens and rented GPUs.\n\nOfficial feeds:\n\n| provider | work | source |\n|---|---|---|\n| openai | inference | https://platform.openai.com/docs/pricing |\n| anthropic | inference | https://docs.claude.com/en/docs/about-claude/pricing |\n| google | inference | https://ai.google.dev/gemini-api/docs/pricing |\n| groq | inference | https://console.groq.com/docs/models |\n| together | inference | https://www.together.ai/pricing |\n| deepseek | inference | https://api-docs.deepseek.com/quick_start/pricing |\n| mistral | inference | https://mistral.ai/pricing/api/ |\n| fireworks | inference | https://docs.fireworks.ai/serverless/pricing |\n| xai | inference | https://docs.x.ai/developers/models |\n| runpod | gpu | https://www.runpod.io/pricing |\n| lambda | gpu | https://lambda.ai/service/gpu-cloud |\n| fireworks | gpu | https://fireworks.ai/pricing |\n| crusoe | gpu | https://www.crusoe.ai/cloud/pricing |\n| minimax | inference | https://platform.minimax.io/docs/guides/pricing-paygo |\n| cerebras | inference | https://api.cerebras.ai/public/v1/models |\n| nebius | gpu | https://nebius.com/prices |\n| hyperstack | gpu | https://www.hyperstack.cloud/gpu-pricing |\n"},"servers":[{"url":"https://compute-state-api.replit.app","description":"Public origin"},{"url":"/","description":"Service root"}],"tags":[{"name":"health","description":"Health operations"},{"name":"cheapest","description":"The paid recommendation route"},{"name":"admin","description":"Operator routes, gated by the x-admin-secret header"}],"paths":{"/healthz":{"get":{"operationId":"healthCheck","tags":["health"],"summary":"Health check","description":"Book freshness and liveness. No payment.","security":[],"responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}}}}},"/v1/cheapest":{"get":{"operationId":"getCheapest","tags":["cheapest"],"summary":"Cheapest compute SKU for a job","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"description":"Paid. Returns the single cheapest SKU that satisfies the query, plus up\nto two alternatives and the disqualified rows with reasons.\n\nA listing probe of GET /v1/cheapest with no query string is a 402, not a 400.\nwork is required to rank. It is not required to see the challenge.\nAn unsigned call always gets the 402; a bad query is a 400 only after\na signed payment verifies, and it is never settled.\n\nA valid query is checked against a cheap freshness signal before any\npayment is taken; if the book cannot defend a number the response is\nan unpaid 503. A signed payment is verified with the\nfacilitator (no money moves), then the book is ranked and the full\nbody built, and only then is the payment settled. The 200 body is\ncomputed before money moves and sent after.\n\nScope: Compute State ranks current published list and effective rates\nfrom official vendor pages for the query you sent. It is a decision\naid, not a quote, invoice, or promise the vendor will accept the job or\nbill that amount. Confirm capacity, region, and the vendor's own price\nat purchase time. as_of is when we last successfully parsed that\nvendor; stale_after_s is when we will refuse to sell the row.\n","parameters":[{"name":"work","in":"query","required":true,"example":"inference","description":"Which ranker to run. Mixed stack optimisation is refused.","schema":{"$ref":"#/components/schemas/WorkKind"}},{"name":"model_tier","in":"query","required":false,"example":"cheap","description":"embed ranks the vendors' official embedding SKUs on input price\nalone: est_output_tokens is accepted and ignored, and a chat SKU\ncan never win. cheap and frontier stay output-price buckets over\ngenerative SKUs, so an embedding SKU can never win those.\n","schema":{"$ref":"#/components/schemas/ModelTier"}},{"name":"model","in":"query","required":false,"description":"Canonical model id when the caller already has one.","schema":{"type":"string"}},{"name":"context_tokens","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"est_input_tokens","in":"query","required":false,"example":2000,"description":"Inference only. Defaults to 1000.","schema":{"type":"integer","minimum":0}},{"name":"est_output_tokens","in":"query","required":false,"example":500,"description":"Inference only. Defaults to 1000.","schema":{"type":"integer","minimum":0}},{"name":"batch","in":"query","required":false,"description":"Inference only. Defaults to false. When true the ranker uses the\nvendor's own published batch rates — never a discount computed\nhere. A SKU whose official page publishes no batch rate is\ndisqualified with reason no_official_batch_rate rather than being\nquoted at its interactive price.\n","schema":{"type":"boolean"}},{"name":"cached_input_tokens","in":"query","required":false,"description":"Inference only. Defaults to 0, must be <= est_input_tokens, and is\npriced at the vendor's published cached-input / cache-hit rate; the\nremaining input tokens are priced at the ordinary input rate. A SKU\nwith no published cached-input rate is disqualified with reason\nno_official_cached_input_rate. Where a vendor publishes instead\nthat cached tokens bill at its standard input rate (Cerebras), the\ncached share is priced at that published input figure and the\ncomponent is named cached_input_at_input_rate.\n","schema":{"type":"integer","minimum":0}},{"name":"gpu_model","in":"query","required":false,"example":"h100","description":"GPU work only, e.g. h100, a100, b200. Matching is by GPU family, so\nh100 returns both H100 SXM and H100 PCIe as separate SKUs and the\ncheaper on-demand row wins; h200 never matches an H100 row.\n","schema":{"type":"string"}},{"name":"gpu_hours","in":"query","required":false,"example":1,"description":"GPU work only. Defaults to 1.","schema":{"type":"number","minimum":0}},{"name":"region","in":"query","required":false,"description":"Hint only in v1; does not filter.","schema":{"type":"string"}},{"name":"availability","in":"query","required":false,"description":"v1 accepts on_demand only. spot is refused with 400.","schema":{"type":"string"}},{"name":"exclude","in":"query","required":false,"description":"Comma-separated provider slugs to drop.","schema":{"type":"string"}}],"responses":{"200":{"description":"Verified, ranked, then settled. The recommendation body, computed\nbefore money moved and sent after.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheapestResponse"}}}},"400":{"description":"Invalid query, reported only after a signed payment verifies.\nUnpaid: never settled. An unsigned call with a bad or missing\nquery gets the 402 instead.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required, or the signature was rejected at verify or\nsettle. Unpaid. x402 v2 challenge, Base and Solana.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"404":{"description":"Paid: verified, ranked, no match, then settled. Carries the\ndisqualified list so the caller can see what came close. (A 404 for an unrecognised path,\nsuch as a typo or /README.md, is unpaid and does not carry this\nbody — see /llms.txt.)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoMatch"}}}},"500":{"description":"Unpaid: the process faulted before settlement. Operator fault.\nYou were not charged, and the body carries no recommendation.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The book has no fresh row for this query, checked before any\npayment is requested. Unpaid. Retry-After tells you when to come\nback.\n","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookStale"}}}}}}},"/v1/example":{"get":{"operationId":"getCheapestExample","tags":["cheapest"],"summary":"Canned example body","description":"A fixed sample of the paid shape. Not a live rank. Free.","security":[],"responses":{"200":{"description":"Example body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheapestExample"}}}}}}}},"components":{"schemas":{"WorkKind":{"type":"string","enum":["inference","gpu"]},"ModelTier":{"type":"string","enum":["frontier","cheap","embed"]},"CostTag":{"type":"string","description":"list — the vendor's published list price.\neffective — a published rate that already reflects the billable\ndiscount for this component (for example a published batch rate).\nunknown — the component exists for this SKU but no official number\ncould be read. A SKU with any unknown component on the path the query\nneeds cannot be rank 1.\n","enum":["list","effective","unknown"]},"HealthStatus":{"type":"object","properties":{"ok":{"type":"boolean","description":"Process and book liveness only. A facilitator outage never flips this to false — check payments.ok separately before paying."},"book":{"type":"object","properties":{"inference_as_of":{"type":["string","null"]},"gpu_as_of":{"type":["string","null"]},"stale":{"type":"boolean"},"inference_rows":{"type":"integer"},"gpu_rows":{"type":"integer"},"inference_providers":{"type":"integer","description":"Distinct official sellers with a fresh inference row."},"gpu_providers":{"type":"integer","description":"Distinct official sellers with a fresh GPU row."},"inference_skus":{"type":"integer","description":"Distinct inference SKUs with a fresh row. Rows may exceed this: one SKU can carry several priced components (input, output, ...)."},"gpu_skus":{"type":"integer","description":"Distinct GPU SKUs with a fresh row."},"oldest_as_of":{"type":["string","null"],"description":"The older of inference_as_of and gpu_as_of, skipping whichever side has no fresh rows. Null only when neither side has any."}},"required":["inference_as_of","gpu_as_of","stale","inference_rows","gpu_rows","inference_providers","gpu_providers","inference_skus","gpu_skus","oldest_as_of"]},"ingest":{"type":"object","description":"Per-vendor scrape state. A vendor whose scrape failed keeps its last\ngood rows until they age out, so book freshness alone cannot show a\nrefresh that is broken — this can.\n","properties":{"failing":{"type":"array","description":"Vendors whose last scrape failed and which have not succeeded\nsince. `code` is a short classification — `parse_shrink` means\nthe parse came back far smaller than that vendor's last good\nrun and was rejected rather than committed.\n","items":{"$ref":"#/components/schemas/IngestFailure"}}},"required":["failing"]},"payments":{"$ref":"#/components/schemas/PaymentsStatus"}},"required":["ok","book","ingest","payments"]},"PaymentsStatus":{"type":"object","description":"A reachability signal for the PayAI facilitator, cached for about 60 seconds. This is not a balance or signature check — Compute State does not sign, verify, or settle anything from this endpoint. `ok: true` means the facilitator's /supported listing is up and lists both configured networks; `ok: false` covers everything else (auth failure, unreachable, timeout, or an unexpected listing), with a short reason. A facilitator outage here never changes the top-level HTTP status or the top-level ok field.","properties":{"ok":{"type":"boolean"},"facilitator":{"type":"string","enum":["payai"]},"reachable":{"type":"boolean"},"checked_at":{"type":"string"},"reason":{"type":"string","description":"supported | unauthorized | forbidden | unreachable | timeout | unexpected"},"networks":{"type":"array","items":{"type":"string"}}},"required":["ok","facilitator","reachable","checked_at","reason","networks"]},"IngestFailure":{"type":"object","properties":{"provider":{"type":"string"},"work":{"type":"string"},"code":{"type":"string","description":"http_4xx | http_5xx | parse_empty | parse_shrink | parse_unreadable_split | timeout | dns | network | unknown"}},"required":["provider","work","code"]},"CostComponent":{"type":"object","properties":{"name":{"type":"string","description":"input | output | cached_input | gpu_hour, optionally composed with the vendor's published batch, peak/off-peak and long-context variants (batch_input, input_offpeak, cached_input_long), or cached_input_at_input_rate where the vendor publishes no cheaper cache-hit rate"},"tag":{"$ref":"#/components/schemas/CostTag"},"usd":{"type":"number","description":"What this component contributes to est_cost_usd for this job."},"rate_usd":{"type":"number","description":"The vendor's published rate the contribution was computed from."},"unit":{"type":"string","description":"usd_per_1m_tokens | usd_per_gpu_hour"}},"required":["name","tag","usd","rate_usd","unit"]},"Recommendation":{"type":"object","properties":{"provider":{"type":"string"},"sku":{"type":"string"},"est_cost_usd":{"type":"number"},"components":{"type":"array","items":{"$ref":"#/components/schemas/CostComponent"}},"why":{"type":"string"},"stale_after_s":{"type":"integer"},"source_url":{"type":"string"},"as_of":{"type":"string"}},"required":["provider","sku","est_cost_usd","components","why","stale_after_s","source_url","as_of"]},"Disqualified":{"type":"object","properties":{"provider":{"type":"string"},"sku":{"type":"string"},"reason":{"type":"string"}},"required":["provider","sku","reason"]},"PaymentEnvelope":{"type":"object","properties":{"network":{"type":"string"},"amount_atomic":{"type":"string"},"settled":{"type":"boolean"},"tx_ref":{"type":["string","null"]}},"required":["network","amount_atomic","settled"]},"CheapestResponse":{"type":"object","properties":{"as_of":{"type":"string"},"work":{"$ref":"#/components/schemas/WorkKind"},"unit":{"type":"string"},"recommendation":{"$ref":"#/components/schemas/Recommendation"},"alternatives":{"type":"array","items":{"$ref":"#/components/schemas/Recommendation"}},"disqualified":{"type":"array","items":{"$ref":"#/components/schemas/Disqualified"}},"payment":{"$ref":"#/components/schemas/PaymentEnvelope"}},"required":["as_of","work","unit","recommendation","alternatives","disqualified","payment"]},"CheapestExample":{"type":"object","properties":{"example":{"type":"boolean"},"scope":{"type":"string","description":"What a ranked answer is and is not. Present on the free example so\nan agent reading the contract sees it before it pays; the paid\nbody does not repeat it.\n"},"as_of":{"type":"string"},"work":{"$ref":"#/components/schemas/WorkKind"},"unit":{"type":"string"},"recommendation":{"$ref":"#/components/schemas/Recommendation"},"alternatives":{"type":"array","items":{"$ref":"#/components/schemas/Recommendation"}},"disqualified":{"type":"array","items":{"$ref":"#/components/schemas/Disqualified"}}},"required":["example","scope","as_of","work","unit","recommendation","alternatives","disqualified"]},"PaymentRequirement":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"amount":{"type":"string"},"asset":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object","additionalProperties":true}},"required":["scheme","network","amount","asset","payTo","maxTimeoutSeconds"]},"PaymentRequired":{"type":"object","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}},"required":["url","description","mimeType"]},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequirement"}}},"required":["x402Version","error","resource","accepts"]},"BookStale":{"type":"object","properties":{"error":{"type":"string"},"retry_after_s":{"type":"integer"}},"required":["error","retry_after_s"]},"NoMatch":{"type":"object","properties":{"error":{"type":"string"},"disqualified":{"type":"array","items":{"$ref":"#/components/schemas/Disqualified"}},"network":{"type":"string","description":"Present because this response follows a settled payment: the\nnetwork the call was paid on.\n"},"tx_ref":{"type":"string","nullable":true}},"required":["error","disqualified","network","tx_ref"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"AdminStats":{"type":"object","properties":{"paid_settles":{"type":"integer","description":"On-chain receipts. This is the only revenue number."},"unique_payers":{"type":"integer"},"http_200":{"type":"integer"},"unpaid_503":{"type":"integer"},"unpaid_404":{"type":"integer"},"challenges_402":{"type":"integer","description":"Asked to pay. Not revenue."},"failed_payments":{"type":"integer","description":"Stale or rejected signatures. Not a 5xx."},"unwritten_settlements":{"type":"integer","description":"Settled receipts currently queued in settlement_outbox, waiting for a database blip to clear. Already folded into paid_settles; not additional revenue. A rarer second backstop covers a receipt that fails even that queue: the settlement-attempt ledger records every payment as durably claimed before it is charged and confirmed once settled, and a background pass backfills paid_settles from that record if no receipt ever reached settlements or settlement_outbox for it. A third backstop, rarer still, covers the ledger's own settled confirmation failing too: a periodic pass asks the facilitator directly what happened to an attempt stuck unconfirmed, so it still resolves instead of aging forever unrecorded."},"wrong_pick_incidents":{"type":"integer"},"book":{"type":"object","properties":{"inference_rows":{"type":"integer"},"gpu_rows":{"type":"integer"},"inference_as_of":{"type":["string","null"]},"gpu_as_of":{"type":["string","null"]}},"required":["inference_rows","gpu_rows","inference_as_of","gpu_as_of"]}},"required":["paid_settles","unique_payers","http_200","unpaid_503","unpaid_404","challenges_402","failed_payments","unwritten_settlements","wrong_pick_incidents","book"]},"IngestProviderResult":{"type":"object","properties":{"provider":{"type":"string"},"work":{"type":"string"},"ok":{"type":"boolean"},"rows":{"type":"integer"},"error_code":{"type":["string","null"]}},"required":["provider","work","ok","rows","error_code"]},"IngestRequest":{"type":"object","properties":{"accept_shrink":{"type":"boolean","description":"Commit a provider's rows even when the parse came back far smaller\nthan that provider's last good run. For a vendor that really did\nretire most of a family; the background loop never sets it.\n"}},"required":[]},"IngestResult":{"type":"object","properties":{"generation":{"type":"string"},"started_at":{"type":"string"},"finished_at":{"type":"string"},"providers":{"type":"array","items":{"$ref":"#/components/schemas/IngestProviderResult"}}},"required":["generation","started_at","finished_at","providers"]},"WrongPickBody":{"type":"object","properties":{"note":{"type":"string","minLength":1}},"required":["note"]},"WrongPickRecorded":{"type":"object","properties":{"id":{"type":"integer"},"note":{"type":"string"},"created_at":{"type":"string"}},"required":["id","note","created_at"]}}}}