Update HPP Router documentation to reflect x402 wallet integration an…

hpp-router/api-reference/consumer-api.md

@@ -5,7 +5,7 @@ description: HPP Router Consumer API — OpenAI-compatible endpoints, schemas, a
 
 # API Reference
 
-HPP Router's request and response schemas are **OpenAI-compatible**, with HPP-specific extensions for smart routing headers and prepaid quota. At a high level, you use the same patterns as the OpenAI Chat API — point your client at `https://router.hpp.io` and authenticate with your API key.
+HPP Router's request and response schemas are **OpenAI-compatible**, with HPP-specific extensions for smart routing headers and wallet payments (on-chain USDC). At a high level, you use the same patterns as the OpenAI Chat API — point your client at `https://router.hpp.io` and authenticate with your API key.
 
 ## OpenAPI Specification
 
@@ -23,7 +23,8 @@ For live requests, use the [Router Playground](https://router.hpp.io/playground/
 ## Base URL & auth
 
 - **Base URL:** `https://router.hpp.io`
-- **Auth:** `apikey` header **or** `Authorization: Bearer <key>`. See [Authentication](../authentication).
+- **Auth:** `apikey` header **or** `Authorization: Bearer <key>` for billed endpoints. `GET /llm/v1/models` does not require a key.
+  - For x402 wallet payments, set `X-HPP-Payment-Rail: wallet` and use PAYMENT-SIGNATURE headers instead of API keys. See [Authentication](../authentication).
 - **Version:** Consumer API `0.1.0`.
 
 ## Endpoints
@@ -34,7 +35,7 @@ For live requests, use the [Router Playground](https://router.hpp.io/playground/
 | `GET` | `/llm/v1/models` | [List available models](#get-llmv1models) |
 | `POST` | `/v1/images/generations` | [Generate images](#post-v1imagesgenerations) |
 | `GET` | `/api/usage` | [Get current consumer usage](#get-apiusage) |
-| `GET` | `/api/quota-check` | [Check current consumer quota](#get-apiquota-check) |
+| `GET` | `/api/user/audit/:logId` | [Get user audit log](#get-apiuserauditlogid) |
 
 ---
 
@@ -56,20 +57,30 @@ OpenAI-compatible chat completion endpoint with HPP smart-routing headers.
 
 Additional properties are allowed and passed through.
 
+**Authentication:** Required. Use `apikey` header or `Authorization: Bearer <key>` for billing/usage tracking.
+
+For x402 wallet payments, append the `X-HPP-Payment-Rail: wallet` header and sign payments using the x402 protocol.
+
 **Responses:**
 
 - `200` — `ChatCompletionResponse` (`application/json`) or an SSE stream (`text/event-stream`). Response headers include `X-HPP-Router-Resolved-Model`, `X-HPP-Router-Basket`, `X-HPP-Router-Rule-Id`, `X-HPP-Router-Rules-Version`, and `X-HPP-Router-Tier`.
-- `400`, `401`, `429`, `500` — error envelope.
+- `401` — Authentication required.
+- `402` — Payment required (for wallet rail). Response includes `PAYMENT-REQUIRED` header with payment specifications.
+- `429`, `500` — error envelope.
 
 See [Chat Completions](../guides/chat-completions) and [Smart Routing](../smart-routing).
 
 ---
 
 ## `GET /llm/v1/models`
 
-Lists available models (OpenAI-compatible). Each `Model` has `id`, `object` (`"model"`), `owned_by`, and an optional `pricing` object (`input`, `output`, `cache_write`, `cache_read`).
+Lists available models (OpenAI-compatible). **Authentication is optional.**
+
+Each `Model` includes `id`, `object` (`"model"`), `owned_by`, optional catalog fields (`name`, `description`, `context`, `max_output`, `tool`, `structured`, `knowledge_cutoff`, `input_modalities`, `output_modalities`), and an optional `pricing` object.
+
+`pricing.input` / `pricing.output` / `pricing.cache_write` / `pricing.cache_read` are **USD per token** (may be `null`). For `hpprouter/auto`, `pricing` is `null` — billing uses the resolved model.
 
-**Responses:** `200` — `ModelListResponse`; `401`, `500` — error envelope.
+**Responses:** `200` — `ModelListResponse`; `500` — error envelope.
 
 See [Models & Pricing](../models-and-pricing).
 
@@ -99,23 +110,59 @@ See [Image Generation](../guides/image-generation).
 
 ## `GET /api/usage`
 
-Usage and quota summary for the authenticated consumer.
+Usage summary for the authenticated consumer.
 
-**Response `200`** (`UsageResponse`): `consumer_id`, `username`, `custom_id`, `quota`, `used`, `remaining`, `requests`, `total_tokens`, `total_cost`.
+**Response `200`** (`UsageResponse`): `consumer_id`, `username`, `custom_id`, `requests`, `total_tokens`, `total_cost`.
 
 **Errors:** `401`, `404`, `500`.
 
----
 
-## `GET /api/quota-check`
+## `GET /api/user/audit/:logId`
+
+Get a single audit log entry for the authenticated consumer.
+
+Access control:
+- Personal consumers can only access their own logs
+- Organization members can access any log from their organization's consumers
 
-Quota availability for the authenticated consumer.
+**Path params:**
+- `logId` — The audit log ID (UUID)
 
-**Response `200`** (`QuotaCheckResponse`): `has_quota`, `quota`, `used`, `remaining`.
+**Query params:**
+- `consumerId` — Filter by consumer (organization members only, must have access permission via `organization_members` table)
+
+**Response `200`:**
+
+```json
+{
+  "id": "log-xyz",
+  "consumer_id": "cons-123",
+  "provider": "openai",
+  "model": "gpt-4",
+  "prompt_tokens": 100,
+  "completion_tokens": 50,
+  "cache_creation_input_tokens": 0,
+  "cache_read_input_tokens": 0,
+  "total_tokens": 150,
+  "cost": 0.002,
+  "status": "success",
+  "blockchain_tx_hash": "0x...",
+  "payment_rail": "wallet",
+  "settle_status": "settled",
+  "settle_amount_micro": 25000,
+  "scope": "organization",
+  "organization": {
+    "id": "org-abc",
+    "name": "My Organization",
+    "consumerId": "cons-org-123",
+    "role": "admin"
+  }
+}
+```
 
-**Errors:** `401`, `503`, `500`.
+**Errors:** `401` (not authenticated), `403` (no access to consumer), `404` (log not found), `500`.
 
-See [Quota & Usage](../guides/quota-and-usage).
+See [Usage & Activity Logs](../guides/quota-and-usage) for more details.
 
 ---
 

hpp-router/api-reference/consumer-v1.yaml

@@ -64,15 +64,17 @@ paths:
     get:
       operationId: listModels
       summary: List available models
+      description: >
+        OpenAI-compatible model catalog with pricing and capability metadata.
+        Authentication is optional for this endpoint.
+      security: []
       responses:
         "200":
           description: OpenAI-compatible model list.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ModelListResponse"
-        "401":
-          $ref: "#/components/responses/ErrorResponse"
         "500":
           $ref: "#/components/responses/ErrorResponse"
   /v1/images/generations:
@@ -280,25 +282,66 @@ components:
           const: model
         owned_by:
           type: string
+        name:
+          oneOf:
+            - type: string
+            - type: "null"
+        description:
+          oneOf:
+            - type: string
+            - type: "null"
         pricing:
           oneOf:
             - $ref: "#/components/schemas/ModelPricing"
             - type: "null"
+        context:
+          oneOf:
+            - type: number
+            - type: "null"
+        max_output:
+          oneOf:
+            - type: number
+            - type: "null"
+        tool:
+          oneOf:
+            - type: boolean
+            - type: "null"
+        structured:
+          oneOf:
+            - type: boolean
+            - type: "null"
+        knowledge_cutoff:
+          oneOf:
+            - type: string
+            - type: "null"
+        input_modalities:
+          type: array
+          items:
+            type: string
+        output_modalities:
+          type: array
+          items:
+            type: string
     ModelPricing:
       type: object
+      description: USD rates per token (multiply by 1_000_000 for $/1M).
       properties:
         input:
           type: number
+          description: USD per input token.
         output:
           type: number
+          description: USD per output token.
         cache_write:
           oneOf:
             - type: number
             - type: "null"
+          description: USD per cache-write token, when applicable.
         cache_read:
           oneOf:
             - type: number
             - type: "null"
+          description: USD per cache-read token, when applicable.
     ImageGenerationRequest:
       type: object
       required:

hpp-router/authentication.mdx

@@ -9,7 +9,7 @@ import CodePanel from '@site/src/components/CodePanel';
 
 # Authentication
 
-Every request to HPP Router must be authenticated. The gateway uses the API key to identify the **consumer**, enforce per-consumer rate limits, and check the prepaid [quota](./guides/quota-and-usage) before forwarding the request to a provider.
+HPP Router uses **on-chain USDC payments** via x402 wallet. All requests require authentication with an API key for consumer identification.
 
 ## Getting an API key
 
@@ -23,11 +23,13 @@ HPP Router accepts two authentication schemes. Use whichever fits your client.
 
 <CodePanel>
 <Tabs groupId="auth-apikey" queryString>
-<TabItem value="curl" label="cURL" default>
+<TabItem value="curl" label="curl" default>
 
 ```bash showLineNumbers
-curl https://router.hpp.io/llm/v1/models \
-  -H "apikey: $HPPROUTER_API_KEY"
+curl https://router.hpp.io/llm/v1/chat/completions \
+  -H "apikey: $HPPROUTER_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/gpt-5","messages":[{"role":"user","content":"Hello"}]}'
 ```
 
 </TabItem>
@@ -38,11 +40,13 @@ curl https://router.hpp.io/llm/v1/models \
 
 <CodePanel>
 <Tabs groupId="auth-bearer" queryString>
-<TabItem value="curl" label="cURL" default>
+<TabItem value="curl" label="curl" default>
 
 ```bash showLineNumbers
-curl https://router.hpp.io/llm/v1/models \
-  -H "Authorization: Bearer $HPPROUTER_API_KEY"
+curl https://router.hpp.io/llm/v1/chat/completions \
+  -H "Authorization: Bearer $HPPROUTER_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/gpt-5","messages":[{"role":"user","content":"Hello"}]}'
 ```
 
 </TabItem>
@@ -53,15 +57,26 @@ The Bearer scheme is what most OpenAI-compatible SDKs send by default, which is
 
 ## Which endpoints require auth
 
-All consumer endpoints are authenticated:
+| Endpoint | Auth | Purpose |
+| --- | --- | --- |
+| `GET /llm/v1/models` | Optional | [List models](./models-and-pricing) |
+| `POST /llm/v1/chat/completions` | Required (wallet: also `X-HPP-Payment-Rail: wallet`) | [Chat completions](./guides/chat-completions) |
+| `POST /v1/images/generations` | Required (wallet: also `X-HPP-Payment-Rail: wallet`) | [Image generation](./guides/image-generation) |
+| `GET /api/usage` | Required | [Usage summary](./guides/quota-and-usage) |
 
-| Endpoint | Purpose |
-| --- | --- |
-| `POST /llm/v1/chat/completions` | [Chat completions](./guides/chat-completions) |
-| `GET /llm/v1/models` | [List models](./models-and-pricing) |
-| `POST /v1/images/generations` | [Image generation](./guides/image-generation) |
-| `GET /api/usage` | [Usage summary](./guides/quota-and-usage) |
-| `GET /api/quota-check` | [Quota check](./guides/quota-and-usage) |
+All requests to HPP Router require authentication with an API key. The API key identifies the consumer and is required for both wallet payments (via Kong).
+
+For wallet payments, also include the `X-HPP-Payment-Rail: wallet` header. See [Chat Completions](./guides/chat-completions) for examples.
+
+## x402 Wallet
+
+HPP Router supports **x402 Wallet** for on-chain USDC payments.
+
+When you send a request with `X-HPP-Payment-Rail: wallet`, the gateway prompts your client to sign payment authorization using the x402 protocol. The server will respond with `PAYMENT-REQUIRED` header containing payment specifications (wallet address, amount in micro-USDC, etc.).
+
+For detailed information about the x402 payment flow, see:
+- [x402 Protocol](https://docs.x402.com)
+- [Wallet Payments Guide](./guides/chat-completions#wallet)
 
 ## Errors
 

hpp-router/client-sdk/typescript.mdx

@@ -110,38 +110,42 @@ See [Streaming](../guides/streaming) for the streaming-fallback behavior of `hpp
 
 ## Models
 
+`models.list()` does **not** require an API key.
+
 <CodePanel>
 <Tabs groupId="typescript-sdk-models" queryString>
 <TabItem value="typescript" label="TypeScript" default>
 
 ```ts showLineNumbers
-const models = await client.models.list();
+const catalogClient = new HppRouter({
+  baseURL: 'https://router.hpp.io',
+});
+
+const models = await catalogClient.models.list();
 console.log(models.data.data);
 ```
 
 </TabItem>
 </Tabs>
 </CodePanel>
 
-## Usage and quota
+## Usage
 
 <CodePanel>
 <Tabs groupId="typescript-sdk-usage" queryString>
 <TabItem value="typescript" label="TypeScript" default>
 
 ```ts showLineNumbers
 const usage = await client.usage.get();
-const quota = await client.quota.check();
 
-console.log(usage.data.remaining);
-console.log(quota.data.has_quota);
+console.log(usage.data);
 ```
 
 </TabItem>
 </Tabs>
 </CodePanel>
 
-See [Quota & Usage](../guides/quota-and-usage).
+See [Usage & Settlement](../guides/quota-and-usage) for more details.
 
 ## Image generation
 

hpp-router/guides/chat-completions.mdx

@@ -15,15 +15,26 @@ The chat completions endpoint is the core of HPP Router. It is OpenAI-compatible
 POST https://router.hpp.io/llm/v1/chat/completions
 ```
 
-## Basic request
+## Payment methods
+
+HPP Router supports **x402 Wallet** for on-chain USDC payments. Set `X-HPP-Payment-Rail: wallet` and include your API key for authentication.
+
+See [Authentication](../authentication) for details.
+
+### Basic request (wallet)
+
+Include both the payment rail header and your API key:
+
+<a name="wallet"></a>
 
 <CodePanel>
-<Tabs groupId="chat-completions-request" queryString>
-<TabItem value="curl" label="cURL" default>
+<Tabs groupId="chat-completions-wallet" queryString>
+<TabItem value="curl" label="curl" default>
 
 ```bash showLineNumbers
 curl -X POST https://router.hpp.io/llm/v1/chat/completions \
   -H "apikey: $HPPROUTER_API_KEY" \
+  -H "X-HPP-Payment-Rail: wallet" \
   -H "Content-Type: application/json" \
   -d '{
     "model": "openai/gpt-5",
@@ -39,6 +50,8 @@ curl -X POST https://router.hpp.io/llm/v1/chat/completions \
 </Tabs>
 </CodePanel>
 
+The server will prompt for wallet payment authorization using the x402 protocol.
+
 ## Request fields
 
 | Field | Type | Notes |
@@ -89,4 +102,4 @@ The `usage` block drives [billing](../models-and-pricing). When you use `hpprout
 
 ## Errors
 
-Requests are checked against your quota before being forwarded. Insufficient quota returns **`429`**; auth failures return **`401`**. See [Errors](./errors).
+Requests are checked against your wallet balance before being forwarded. Insufficient funds return **`429`**; auth failures return **`401`**. Wallet requests may also return **`402 PAYMENT REQUIRED`** with payment instructions. See [Errors](./errors).