# Inferrail Hosted

> Per-run dollar budgets for AI agents. A call that would push a run past its ceiling is refused before it reaches OpenAI or Anthropic. The ceiling is shared by every agent and machine using the same workspace and work id. Bring your own provider key; it is never stored. Receipts hold costs and ids, never prompts or responses.

## Start (no account)
1. POST https://inferrail-cost-gateway.onrender.com/hosted/v1/workspaces -> {"api_key": "irw_..."}. Shown once; keep it.
2. Send every call with:
   - workspace key: `Authorization: Bearer <api_key>` or `x-api-key: <api_key>`
   - provider key: `X-Provider-Api-Key: <your OpenAI or Anthropic key>`
   - run id: `X-Inferrail-Attribute-Work-Id: <id>` (one id per task/run)
   - ceiling: `X-Inferrail-Budget-Usd: <usd>` (e.g. 0.50; max 100)
3. OpenAI shape: POST https://inferrail-cost-gateway.onrender.com/hosted/v1/chat/completions (OpenAI SDK base_url = https://inferrail-cost-gateway.onrender.com/hosted/v1, api_key = workspace key).
   Anthropic shape: POST https://inferrail-cost-gateway.onrender.com/hosted/v1/messages (Anthropic SDK base_url = https://inferrail-cost-gateway.onrender.com/hosted, api_key = workspace key).

## Budgets
- The first ceiling declared for a work id is kept for the whole run; a different value later is refused (400).
- Without X-Inferrail-Budget-Usd a call is metered and receipted but not capped.
- Over the ceiling: HTTP 402, error.type BudgetExceededError, code INFERRAIL_E010. Nothing reached the provider. Not retryable as-is.

## Usage and receipts
- GET https://inferrail-cost-gateway.onrender.com/hosted/v1/workspace: runs this month, free runs left, credits left.
- GET https://inferrail-cost-gateway.onrender.com/hosted/v1/work/<work id>: the run's calls, cost and receipts.
- GET https://inferrail-cost-gateway.onrender.com/hosted/v1/workspace/ledger: credit purchases, refunds and pending payments.

## Price
- A governed run is a distinct work id (X-Inferrail-Attribute-Work-Id) in a UTC month. It is billed only if at least one of its calls is answered by the provider; runs whose calls all fail or are refused by their own budget cost nothing. Calls without a work id are each their own run.
- 250 governed runs per workspace per month free (resets 00:00 UTC on the 1st), then $0.001 per run from prepaid credits. No subscription, no auto top-up, no overage.
- Allowance and credits used up: HTTP 402 with detail.error allowance_exhausted, before the provider is called.
- Model spend is billed by your provider on your own key.
- Machine-readable: GET https://inferrail-cost-gateway.onrender.com/hosted/pricing

## Buying credits
- USDC over x402 (eip155:8453): POST https://inferrail-cost-gateway.onrender.com/hosted/v1/credits/x402 with your workspace key. The first response is HTTP 402 with a PAYMENT-REQUIRED header (x402 v2, scheme exact, $1.00 to 0xe6177736853CED6E958ae4F6d1B885098D46a7fb). Sign it with your wallet and repeat the same request with the PAYMENT-SIGNATURE header. One pack = 1,000 governed runs. No account.
- Each signed payment adds credits at most once; re-sending the same signed payment can't charge twice. Its id is payment_ref = '<payer>:<nonce>' (both lower-case, from the authorization you signed).
- After you send PAYMENT-SIGNATURE:
  - HTTP 200 (status settled): paid and credited. See GET /v1/workspace.
  - HTTP 402, or a timeout: do NOT sign a new payment yet. Look up your payment_ref in GET /v1/workspace/ledger -> purchases:
    - pending: wait; it is settled or failed from on-chain state within a few minutes;
    - settled: you were charged once and credited;
    - failed, or not listed: you were not charged; you may pay again.
  - HTTP 503: a sales limit is reached; nothing is charged. Retry later.

## Errors and retries
- 400: missing provider key, bad budget header or conflicting ceiling. Fix the request.
- 401: missing or invalid workspace key.
- 402: run ceiling (BudgetExceededError) or allowance_exhausted. Not retryable as-is.
- 413: request body too large.
- 429: workspace rate limit; wait for the Retry-After seconds.
- 502/504: provider error or timeout; error.remediation says whether to retry.

## Free alternative
The open-source gateway does the same per-run enforcement on one machine: pip install inferrail. Hosted is for many agents or machines sharing one budget ledger without running it yourself.

OpenAPI: https://inferrail-cost-gateway.onrender.com/hosted/openapi.json