# HouseMath — Full Agent Reference (v1.0.0)

> Extended reference: every endpoint with full description, parameters, and an example JSON
> body. Compact version: https://api.housemath.dev/llms.txt · OpenAPI: https://api.housemath.dev/openapi.json

## Base URL & discovery surface
- API base: https://api.housemath.dev
- /llms.txt (compact) · /llms-full.txt (this) · /discovery (JSON enumeration)
- /openapi.json (OpenAPI 3.1) · /.well-known/x402 · /.well-known/agent-card.json
- Payment: x402 V2 · Networks: eip155:8453 + solana · Asset: USDC · Scheme: exact

## GET /v1/games   (FREE)
Free, no payment. Lists every tracked degen-game protocol (identity + category + chain + status + published risk grade). Use a protocol's `key` in the per-protocol routes.

Rate limit: 30/min.

Example response:
```json
[
  {
    "key": "fwa",
    "name": "FWA (Fake World Assets)",
    "category": "nft_gacha",
    "chainId": 1,
    "status": "tracked",
    "website": "https://fwa.example",
    "twitter": null,
    "riskGrade": "C",
    "description": "On-chain NFT gacha with backing-weighted draws."
  }
]
```

## GET /v1/games/:key   (FREE)
Free, no payment. One protocol's headline: identity + risk grade + LIVE analytics (EV per pull, house edge, pull price) computed from on-chain state, plus freshness. If a live read is temporarily unavailable, `analytics` is null with a note (never a 500).

Rate limit: 30/min.

Example response:
```json
{
  "key": "fwa",
  "name": "FWA (Fake World Assets)",
  "category": "nft_gacha",
  "chainId": 1,
  "status": "tracked",
  "riskGrade": "C",
  "analytics": {
    "evPerPullEth": -0.0091,
    "evPerPullWei": "-9100000000000000",
    "houseEdgePct": 0.12,
    "pullPriceWei": "75000000000000000"
  },
  "source": {
    "kind": "live",
    "chainId": 1,
    "at": "2026-08-15T00:00:00.000Z"
  }
}
```

## GET /v1/games/:key/audit   (FREE)
Free, no payment. The published contract risk audit for a protocol: overall risk, summary, methodology, scope, and the findings list (code / severity / category / title / summary / status). Full finding `detail` is omitted from the list; add ?full=1 to include it. 404 if no audit is published for that protocol.

Parameters:
- `full` (string, query, optional) — Set ?full=1 to include each finding's full markdown detail.

Rate limit: 30/min.

Example response:
```json
{
  "key": "fwa",
  "version": 1,
  "status": "published",
  "overallRisk": "elevated",
  "summary": "Backing-weighted gacha with elevated economic + admin risk.",
  "publishedAt": "2026-08-15T00:00:00.000Z",
  "findings": [
    {
      "code": "FWA-01",
      "severity": "high",
      "category": "economic",
      "title": "Negative expected value per pull",
      "summary": "House edge structurally favours the contract.",
      "status": "open"
    }
  ]
}
```

## Payment
Strictly pay-per-call. An unpaid paid-route request returns a 402 challenge whose accepts[] lists one exact USDC rail per network (Base or Solana). Sign one rail and retry with PAYMENT-SIGNATURE (x402 V2) or X-PAYMENT (legacy).