# SiloRail

SiloRail is an OpenAI-compatible LLM gateway that bills per call in USDC on
Monad mainnet using HTTP 402 and x402. A wallet holding USDC is the account.
It signs the payment authorization; a facilitator submits it on-chain and pays
the gas. The wallet does not need MON, Monad's gas token.

This is a public beta. Mainnet USDC has real value. The receipt shows the quoted, actual, and settled amounts.

## How payment works

A request without payment returns HTTP 402 with a JSON challenge listing
accepted payment requirements ("accepts"). Two schemes are offered:

- upto (preferred): sign a Permit2 authorization for a spending CEILING; the
  gateway settles the ACTUAL cost after the response, always <= the ceiling.
  Requires a one-time Permit2 allowance, which the gateway sponsors (see
  POST /v1/permit); the wallet still never needs gas.
- exact: sign an EIP-3009 transferWithAuthorization for a fixed quoted price.
  Works from a completely cold wallet with no allowance. This is the
  bootstrap path; the gateway sponsors an upgrade to upto after the first
  settled call.

The signature is sent in the PAYMENT-SIGNATURE header (base64 JSON, x402 v2).
Every settlement is a public transaction; GET /v1/settlements/{request_id}
returns what was quoted, what the call truly cost, and what settled, with the
transaction hash.

## Fastest paths to a working call

1. SDK: handles 402, signing, and scheme choice.
   npx -y @silorail/sdk proxy --gateway https://mainnet.silorail.com

2. Existing OpenAI client: run that local proxy, then use the OpenAI API
   as normal (the key is ignored):
   # then: OPENAI_BASE_URL=http://127.0.0.1:8403/v1  OPENAI_API_KEY=unused

3. Raw x402: implement the 402 round-trip yourself with @x402/fetch or
   @x402/evm (npm). Pin @x402/evm >= 2.12.0.

4. MCP: configure your MCP host to run this command:
   SILORAIL_GATEWAY_URL=https://mainnet.silorail.com npx -y @silorail/mcp
   The server creates a local wallet on first run. Its tools are chat,
   list_models, get_receipt, and wallet_status. Set SILORAIL_SESSION_MAX_USD
   and SILORAIL_PER_CALL_MAX_USD to impose local spending limits before an
   autonomous agent can sign anything.

## Endpoints

GET /health
  Liveness. -> {"ok":true,"network":"eip155:143"}

GET /status
  Public beta status: network, traffic availability, alert configuration, and
  links to readiness, models, and pricing. No secrets or private balances.

GET /ready
  Readiness including facilitator reachability and remaining gas runway, and
  settlement counts. Returns 503 when settling is not currently safe.

GET /v1/pricing
  The terms needed to derive a quote locally: rates source, margin percent,
  settlement gas, schemes, asset and network constants. The @silorail/pricing
  package (same repo) computes the identical ceiling the gateway does, which
  lets a client attach payment on the FIRST request and skip the 402
  round-trip.

GET /v1/models
  OpenAI-shaped model list. Only models the gateway can price are served;
  unknown models are refused instead of guessed at.

POST /v1/chat/completions
  OpenAI-compatible chat completions, streaming and non-streaming.
  Without PAYMENT-SIGNATURE: HTTP 402 with the payment challenge (JSON body
  and PAYMENT-REQUIRED header). With a valid PAYMENT-SIGNATURE: proxies
  upstream and returns the completion. Response headers:
    X-SiloRail-Request-Id   id for the settlement receipt
    X-SiloRail-Quoted       the quoted/authorized amount in USD
    X-SiloRail-True-Cost    actual cost (non-streaming only; for streaming,
                            read the receipt after the stream ends)
  Errors: 400 model_not_priced | unpriceable_content, 402 payment invalid or
  replayed, 412 insufficient Permit2 allowance (retryable via /v1/permit),
  429 exposure_cap (too much unsettled value for this payer), 502 upstream
  failure (nobody is charged).

POST /v1/permit
  Body: {"owner","spender","value","deadline","signature"}; an EIP-2612
  permit signed by the payer approving Permit2. The gateway broadcasts it and
  pays the gas. Only payers with at least one settled call qualify
  (403 unproven_payer otherwise); spender must be the canonical Permit2
  address. This is the exact->upto upgrade.

GET /v1/settlements/{request_id}
  The receipt: model, payer, quoted, true cost, authorized, settled amounts
  (micro-USD strings), scheme, state (billing|pending|settled|failed), and
  tx_hash once on-chain. Public; a billing claim nobody can audit is just a
  claim.

## Constants

network, RPC, USDC, explorer
                   GET https://mainnet.silorail.com/v1/pricing is authoritative for this deployment.
                   Do not copy payment constants from another network.
amounts            all micro-USD (1e-6 USD) strings unless noted

## Notes for agents

- The ceiling in an upto authorization is NOT a charge. Typical calls settle
  ~3% of the ceiling. Judge cost by the receipt's settled_micro, not by the
  authorization amount.
- Free-model capacity is a shared upstream quota. A 502 with payments still
  working means today's capacity is exhausted; retry tomorrow.
- A local wallet key is a spending credential. Keep it local, set the MCP/SDK
  budget limits, and never give its private key to a model, prompt, or website.