From 9710d561d1d3e1169bbc726fbbb1c5c5906f28cc Mon Sep 17 00:00:00 2001 From: croa Date: Wed, 15 Jul 2026 09:51:18 +0900 Subject: [PATCH 1/2] Update HPP Router documentation to reflect x402 wallet integration and on-chain USDC payments. Key changes include: - Revised authentication requirements to include x402 wallet payments. - Updated API endpoints and examples to demonstrate wallet payment integration. - Enhanced descriptions of usage tracking and billing processes. - Clarified error handling for insufficient funds and payment requirements. - Adjusted sections on models and pricing to align with new billing methods. These updates ensure comprehensive guidance for users on utilizing the new payment system effectively. --- hpp-router/api-reference/consumer-api.md | 75 ++++++++++++++++++----- hpp-router/api-reference/consumer-v1.yaml | 48 ++++++++++++++- hpp-router/authentication.mdx | 45 +++++++++----- hpp-router/client-sdk/typescript.mdx | 16 +++-- hpp-router/guides/chat-completions.mdx | 21 +++++-- hpp-router/guides/errors.md | 8 +-- hpp-router/guides/image-generation.mdx | 25 +++++--- hpp-router/guides/openai-sdk.mdx | 2 +- hpp-router/guides/quota-and-usage.mdx | 41 ++++++------- hpp-router/guides/streaming.mdx | 38 +++++++++++- hpp-router/guides/vision-multimodal.mdx | 7 ++- hpp-router/intro.md | 15 +++-- hpp-router/models-and-pricing.mdx | 73 +++++++++++++++------- hpp-router/quickstart.mdx | 7 ++- hpp-router/smart-routing.mdx | 4 +- 15 files changed, 312 insertions(+), 113 deletions(-) diff --git a/hpp-router/api-reference/consumer-api.md b/hpp-router/api-reference/consumer-api.md index b7caf51..1bec0f9 100644 --- a/hpp-router/api-reference/consumer-api.md +++ b/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 `. See [Authentication](../authentication). +- **Auth:** `apikey` header **or** `Authorization: Bearer ` 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,10 +57,16 @@ 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 ` 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). @@ -67,9 +74,13 @@ See [Chat Completions](../guides/chat-completions) and [Smart Routing](../smart- ## `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. --- diff --git a/hpp-router/api-reference/consumer-v1.yaml b/hpp-router/api-reference/consumer-v1.yaml index cde2429..cb97a65 100644 --- a/hpp-router/api-reference/consumer-v1.yaml +++ b/hpp-router/api-reference/consumer-v1.yaml @@ -64,6 +64,10 @@ 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. @@ -71,8 +75,6 @@ paths: application/json: schema: $ref: "#/components/schemas/ModelListResponse" - "401": - $ref: "#/components/responses/ErrorResponse" "500": $ref: "#/components/responses/ErrorResponse" /v1/images/generations: @@ -167,7 +169,6 @@ components: - anthropic/claude-sonnet-4 - moonshotai/kimi-k2.6 - ollama/gpt-oss:120b - - ollama/solidity-master:2 messages: type: array items: @@ -280,25 +281,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: diff --git a/hpp-router/authentication.mdx b/hpp-router/authentication.mdx index 490eb0b..dc44790 100644 --- a/hpp-router/authentication.mdx +++ b/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. - + ```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"}]}' ``` @@ -38,11 +40,13 @@ curl https://router.hpp.io/llm/v1/models \ - + ```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"}]}' ``` @@ -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 diff --git a/hpp-router/client-sdk/typescript.mdx b/hpp-router/client-sdk/typescript.mdx index 485b645..c57ebaa 100644 --- a/hpp-router/client-sdk/typescript.mdx +++ b/hpp-router/client-sdk/typescript.mdx @@ -110,12 +110,18 @@ See [Streaming](../guides/streaming) for the streaming-fallback behavior of `hpp ## Models +`models.list()` does **not** require an API key. + ```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); ``` @@ -123,7 +129,7 @@ console.log(models.data.data); -## Usage and quota +## Usage @@ -131,17 +137,15 @@ console.log(models.data.data); ```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); ``` -See [Quota & Usage](../guides/quota-and-usage). +See [Usage & Settlement](../guides/quota-and-usage) for more details. ## Image generation diff --git a/hpp-router/guides/chat-completions.mdx b/hpp-router/guides/chat-completions.mdx index 699798e..94eddad 100644 --- a/hpp-router/guides/chat-completions.mdx +++ b/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: + + - - + + ```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 \ +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). diff --git a/hpp-router/guides/errors.md b/hpp-router/guides/errors.md index b2b1f4c..1938958 100644 --- a/hpp-router/guides/errors.md +++ b/hpp-router/guides/errors.md @@ -5,7 +5,7 @@ description: HTTP status codes and the error envelope returned by HPP Router. # Errors -HPP Router returns standard HTTP status codes and a JSON error envelope. Handle these in your client to distinguish auth, quota, and upstream failures. +HPP Router returns standard HTTP status codes and a JSON error envelope. Handle these in your client to distinguish auth, wallet balance, and upstream failures. ## Status codes @@ -13,9 +13,9 @@ HPP Router returns standard HTTP status codes and a JSON error envelope. Handle | --- | --- | --- | | `400` | Bad Request | Malformed body, or an unroutable/unsupported model. | | `401` | Unauthorized | Missing or invalid API key. See [Authentication](../authentication). | -| `429` | Too Many Requests / Quota Exceeded | Rate limit hit, or insufficient [quota](./quota-and-usage). | +| `429` | Too Many Requests / Insufficient Funds | Rate limit hit, or insufficient wallet balance. See [Wallet Payments](../authentication#x402-wallet) for details. | | `500` | Internal Server Error | Unexpected gateway or upstream error. | -| `503` | Service Unavailable | Quota state could not be verified (fail-closed). | +| `503` | Service Unavailable | Wallet settlement could not be verified (fail-closed). | ## Error envelope @@ -66,6 +66,6 @@ When using [`hpprouter/auto`](../smart-routing), you may encounter: ## Handling guidance - **`401`** — fix your API key; do not retry blindly. -- **`429`** — back off and retry; if it's a quota issue, top up via [HPP Hub](https://hub.hpp.io). +- **`429`** — back off and retry; if it's an insufficient funds issue, top up your wallet via the x402 protocol. - **`5xx`** with `retryable: true` — retry with exponential backoff. - **`5xx`** with `retryable: false` — surface the error; retrying will not help. diff --git a/hpp-router/guides/image-generation.mdx b/hpp-router/guides/image-generation.mdx index 3050f50..cb481b3 100644 --- a/hpp-router/guides/image-generation.mdx +++ b/hpp-router/guides/image-generation.mdx @@ -17,13 +17,18 @@ POST https://router.hpp.io/v1/images/generations ## Request +### Wallet + +Include both the payment rail header and your API key: + - + ```bash showLineNumbers curl -X POST https://router.hpp.io/v1/images/generations \ -H "apikey: $HPPROUTER_API_KEY" \ + -H "X-HPP-Payment-Rail: wallet" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-1", @@ -70,15 +75,19 @@ The image is returned as base64 (`b64_json`). The `usage` block reports the toke ## Pricing (token-based) -Image generation is billed per token, like chat: +Image generation is billed per token, like chat. For `openai/gpt-image-1`: -- **Input:** $10 per 1M tokens ($0.00001 / token) -- **Output:** $40 per 1M tokens ($0.00004 / token) +- **Input (text tokens):** $5 per 1M tokens (`0.000005` / token) +- **Output (image tokens):** $40 per 1M tokens (`0.00004` / token) + +Confirm live rates with `GET /llm/v1/models`. Higher `quality` settings consume more **output tokens** — for example, `auto` can use roughly 15× the output tokens of `low`. Choose the lowest quality that meets your needs to control cost. -## Quota management +## Wallet payments + +All image generation requests require authentication with an API key. For wallet payments, include the `X-HPP-Payment-Rail: wallet` header. -- Requests are checked against your [quota](./quota-and-usage) before being forwarded. -- If quota is insufficient, the endpoint returns **`429`** (quota exceeded). See [Errors](./errors). -- Usage is tracked automatically and deducted from your quota. +- Requests are processed on-chain via x402 protocol. +- If wallet settlement fails, the endpoint returns **`402 PAYMENT REQUIRED`** with payment instructions. See [Errors](./errors). +- Usage is tracked automatically and settled on-chain after completion. diff --git a/hpp-router/guides/openai-sdk.mdx b/hpp-router/guides/openai-sdk.mdx index 849ea43..ddf64ee 100644 --- a/hpp-router/guides/openai-sdk.mdx +++ b/hpp-router/guides/openai-sdk.mdx @@ -84,4 +84,4 @@ OpenAI SDKs send the key as `Authorization: Bearer `, which HPP Router acce ## When to prefer `@hpprouter/sdk` -The dedicated [TypeScript SDK](../client-sdk/typescript) returns smart-routing metadata (resolved model, basket, tier) alongside the response, and provides typed helpers for usage, quota, and images. Use it when you want first-class access to HPP Router-specific features; use the OpenAI SDK when you want a minimal-change drop-in. +The dedicated [TypeScript SDK](../client-sdk/typescript) returns smart-routing metadata (resolved model, basket, tier) alongside the response, and provides typed helpers for usage and images. Use it when you want first-class access to HPP Router-specific features; use the OpenAI SDK when you want a minimal-change drop-in. diff --git a/hpp-router/guides/quota-and-usage.mdx b/hpp-router/guides/quota-and-usage.mdx index 2ec85eb..53d208a 100644 --- a/hpp-router/guides/quota-and-usage.mdx +++ b/hpp-router/guides/quota-and-usage.mdx @@ -7,28 +7,21 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodePanel from '@site/src/components/CodePanel'; -# Quota & Usage - -HPP Router uses a **prepaid quota** model: each consumer has a dollar-denominated quota, and every request is checked against the remaining balance *before* it reaches a provider. Token usage is then metered and deducted. +--- -## Quota model +# Usage & Settlement -| Term | Meaning | -| --- | --- | -| `quota` | Total dollar allowance for the consumer. | -| `used` | Dollars already accrued from usage. | -| `remaining` | `quota − used` — headroom before the cap. | -| `has_quota` | `true` when `remaining > 0`. | +HPP Router uses **on-chain USDC payments** via x402 wallet. All requests require authentication with an API key for consumer identification. -When a request arrives, the gateway verifies the consumer has quota. If not, the request is rejected with **`429`** before any provider is called (fail-fast). See [Errors](./errors). +Token usage is metered and billed on-chain after usage settlement. -## Check quota +## Usage summary A lightweight pre-flight check for the authenticated consumer: - + ```bash showLineNumbers curl https://router.hpp.io/api/quota-check \ @@ -52,11 +45,13 @@ If the quota state cannot be verified (e.g. a backend datastore is unavailable), ## Usage summary -A fuller summary of consumption for the authenticated consumer: +A summary of consumption for the authenticated consumer. + +### x402 Wallet (default) - + ```bash showLineNumbers curl https://router.hpp.io/api/usage \ @@ -72,9 +67,9 @@ curl https://router.hpp.io/api/usage \ "consumer_id": "....", "username": "alice", "custom_id": "user-001", - "quota": 100, - "used": 12.5, - "remaining": 87.5, + "spent_usdc_micro": 2500000, + "settle_success_count": 3, + "settle_failed_count": 0, "requests": 42, "total_tokens": 18500, "total_cost": 12.5 @@ -85,10 +80,12 @@ curl https://router.hpp.io/api/usage \ | --- | --- | | `consumer_id` | The authenticated consumer's id. | | `username` / `custom_id` | Optional identifiers (may be `null`). | -| `quota` / `used` / `remaining` | The quota balance (see above). | +| `spent_usdc_micro` | Total USDC spent on-chain (in micro units). | +| `settle_success_count` | Number of successful on-chain settlements. | +| `settle_failed_count` | Number of failed settlements. | | `requests` | Number of requests recorded. | | `total_tokens` | Total tokens consumed. | -| `total_cost` | Total dollar cost accrued. | +| `total_cost` | Total dollar cost (from resolved model pricing). | ## How usage is metered @@ -101,7 +98,9 @@ For `hpprouter/auto`, cost uses the **resolved** model's pricing, not a price fo ## Performance note -The quota-check path is backed by a short-lived in-memory cache to reduce database load under bursts of traffic, with concurrent lookups for the same consumer collapsed into a single read. Cached values are kept fresh for a few seconds and invalidated immediately when an admin changes a consumer's quota, so the figures you read stay accurate. +## Performance note + +The usage endpoint is backed by a short-lived in-memory cache to reduce database load under bursts of traffic, with concurrent lookups for the same consumer collapsed into a single read. Cached values are kept fresh for a few seconds and invalidated immediately when an admin changes a consumer's quota, so the figures you read stay accurate. ## Local models diff --git a/hpp-router/guides/streaming.mdx b/hpp-router/guides/streaming.mdx index 4addf7c..81335b4 100644 --- a/hpp-router/guides/streaming.mdx +++ b/hpp-router/guides/streaming.mdx @@ -19,13 +19,18 @@ Accept: text/event-stream ## REST (curl) +### Wallet (with API key) + +Include both the payment rail header and your API key: + - + ```bash showLineNumbers curl -N -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", @@ -50,13 +55,41 @@ data: [DONE] ## TypeScript SDK +### Wallet (with API key) + +Include both the payment rail header and your API key: + - + + +```ts showLineNumbers +import { HppRouter } from '@hpprouter/sdk'; + +const client = new HppRouter({ + apiKey: process.env.HPPROUTER_API_KEY!, + baseURL: 'https://router.hpp.io', +}); + +const { stream, meta } = await client.chat.stream({ + model: 'openai/gpt-5', + messages: [{ role: 'user', content: 'Stream a short answer.' }], +}); + +for await (const event of stream) { + console.log(event); +} + +console.log(meta.resolvedModel); +``` + + + ```ts showLineNumbers import { HppRouter } from '@hpprouter/sdk'; +// For wallet payments, include apikey for Kong auth and x402Rail option const client = new HppRouter({ apiKey: process.env.HPPROUTER_API_KEY!, baseURL: 'https://router.hpp.io', @@ -65,6 +98,7 @@ const client = new HppRouter({ const { stream, meta } = await client.chat.stream({ model: 'openai/gpt-5', messages: [{ role: 'user', content: 'Stream a short answer.' }], + x402Rail: 'wallet', // Sets X-HPP-Payment-Rail header }); for await (const event of stream) { diff --git a/hpp-router/guides/vision-multimodal.mdx b/hpp-router/guides/vision-multimodal.mdx index 6cd5dd5..cf2f20b 100644 --- a/hpp-router/guides/vision-multimodal.mdx +++ b/hpp-router/guides/vision-multimodal.mdx @@ -15,13 +15,18 @@ Vision-capable models accept images alongside text in the same chat completion r Use an array of content parts in a message, mixing `text` and `image_url`: +### Wallet (with API key) + +Include both the payment rail header and your API key: + - + ```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-4o", diff --git a/hpp-router/intro.md b/hpp-router/intro.md index 03170c8..588b13a 100644 --- a/hpp-router/intro.md +++ b/hpp-router/intro.md @@ -6,7 +6,7 @@ description: What HPP Router is, how requests flow through the gateway, and wher # HPP Router -**HPP Router** is an OpenAI-compatible LLM API gateway for the HPP ecosystem. It sends each request to the right model across providers, enforces a prepaid quota per consumer, and tracks usage — all behind a single API key and a single base URL. +**HPP Router** is an OpenAI-compatible LLM API gateway for the HPP ecosystem. It sends each request to the right model across providers, enforces wallet-based on-chain payments per consumer, and tracks usage — all behind a single API key and a single base URL. ``` https://router.hpp.io @@ -16,25 +16,24 @@ https://router.hpp.io - **One API, many models.** Call OpenAI, Anthropic, Moonshot, or local Ollama models through one OpenAI-compatible endpoint. Switch models by changing a single `model` string. - **Smart routing.** Use the virtual model [`hpprouter/auto`](/hpp-router/smart-routing) and let the gateway pick a cost-appropriate model per request based on configurable rules. -- **Prepaid quota & usage tracking.** Every request is checked against the consumer's remaining quota before it reaches a provider, and token usage is metered and billed against the [resolved model's pricing](/hpp-router/models-and-pricing). +- **On-chain wallet payments** — Every request is tracked for usage and settled on-chain via x402 (USDC). Token usage is metered and billed at the resolved model's pricing. - **Drop-in compatibility.** Existing OpenAI SDK code works by pointing the base URL at `https://router.hpp.io` and using your HPP Router API key. ## How a request flows ``` -Client → Kong Gateway (key-auth, rate-limiting, quota check) +Client → Kong Gateway (key-auth, rate-limiting) → llm-router (resolves provider/model, incl. hpprouter/auto) → upstream provider (OpenAI / Anthropic / Ollama) → response captured for async usage logging - → PostgreSQL (consumer quotas, usage logs) + → PostgreSQL (usage logs, blockchain settlement) ``` 1. A request arrives with your API key. 2. The gateway authenticates the consumer and applies rate limits. -3. The quota layer verifies the consumer still has available quota (fail-fast otherwise). -4. The router resolves the target `provider/model` — or, for `hpprouter/auto`, classifies the request and picks a model from rules. -5. The upstream provider is called and the response is returned to you. -6. Token usage is extracted asynchronously (no added latency) and deducted from the consumer's quota. +3. The router resolves the target `provider/model` — or, for `hpprouter/auto`, classifies the request and picks a model from rules. +4. The upstream provider is called and the response is returned to you. If x402 wallet payment is used (`X-HPP-Payment-Rail: wallet`), the server will prompt for on-chain payment authorization. +5. Token usage is extracted asynchronously (no added latency) and settled on-chain via x402 protocol. ## Where HPP Router fits in the HPP ecosystem diff --git a/hpp-router/models-and-pricing.mdx b/hpp-router/models-and-pricing.mdx index d2db73c..ecb965b 100644 --- a/hpp-router/models-and-pricing.mdx +++ b/hpp-router/models-and-pricing.mdx @@ -9,41 +9,64 @@ import CodePanel from '@site/src/components/CodePanel'; # Models & Pricing -HPP Router exposes models from multiple providers behind one OpenAI-compatible API. Billing is **token-based** and deducted from your prepaid [quota](./guides/quota-and-usage). +HPP Router exposes models from multiple providers behind one OpenAI-compatible API. Billing is **token-based** and settled on-chain via x402 wallet (USDC). ## Listing models -Use the OpenAI-compatible models endpoint to discover what's available, including the virtual `hpprouter/auto` model: +Use the OpenAI-compatible models endpoint to discover what's available, including the virtual `hpprouter/auto` model. **No API key is required** for this endpoint. - + ```bash showLineNumbers -curl https://router.hpp.io/llm/v1/models \ - -H "apikey: $HPPROUTER_API_KEY" +curl https://router.hpp.io/llm/v1/models ``` -The response is an OpenAI-style list. Each model may include a `pricing` object: +The response is an OpenAI-style list with pricing and capability metadata. `pricing.*` values are **USD per token** (multiply by `1_000_000` for the familiar $/1M figure): ```json showLineNumbers { "object": "list", "data": [ + { + "id": "hpprouter/auto", + "object": "model", + "owned_by": "hpprouter", + "name": "Auto", + "description": "Smart routing picks a provider and model based on your request.", + "pricing": null, + "context": null, + "max_output": null, + "tool": null, + "structured": null, + "knowledge_cutoff": null, + "input_modalities": [], + "output_modalities": [] + }, { "id": "openai/gpt-5", "object": "model", "owned_by": "openai", + "name": "GPT-5", + "description": null, "pricing": { - "input": 1.25, - "output": 10, + "input": 0.00000125, + "output": 0.00001, "cache_write": null, - "cache_read": null - } + "cache_read": 1.25e-7 + }, + "context": 272000, + "max_output": 128000, + "tool": true, + "structured": true, + "knowledge_cutoff": null, + "input_modalities": ["text", "image"], + "output_modalities": ["text"] } ] } @@ -53,12 +76,18 @@ The response is an OpenAI-style list. Each model may include a `pricing` object: | --- | --- | | `id` | Model identifier — use this as the request `model`. | | `owned_by` | Provider that owns the model. | -| `pricing.input` | Price per 1M input tokens (USD). | -| `pricing.output` | Price per 1M output tokens (USD). | -| `pricing.cache_write` / `cache_read` | Cache pricing per 1M tokens, when applicable (may be `null`). | +| `name` / `description` | Display name and short description (may be `null`). | +| `pricing` | `null` for `hpprouter/auto` (billed at the resolved model). | +| `pricing.input` | USD **per input token**. | +| `pricing.output` | USD **per output token**. | +| `pricing.cache_write` / `cache_read` | USD **per cache token**, when applicable (may be `null`). | +| `context` / `max_output` | Context window and max output tokens, when known. | +| `tool` / `structured` | Tool calling / structured output support (may be `null`). | +| `knowledge_cutoff` | Knowledge cutoff date string, when known. | +| `input_modalities` / `output_modalities` | Accepted / produced modalities (e.g. `text`, `image`). | :::note -The models list is the source of truth for what is currently enabled. The examples below are illustrative pricing taken from the gateway documentation and may change. +The models list is the source of truth for what is currently enabled. The example rates below are illustrative and may change. ::: ## Model identifiers @@ -77,8 +106,10 @@ Specify a model as **`provider/model`**, or use the virtual smart-routing model: ## How billing works -- Pricing is **per million tokens**, split into **input** (prompt) and **output** (completion) rates. -- Cost for a request ≈ `(prompt_tokens × input_rate + completion_tokens × output_rate) / 1,000,000`. +- API `pricing.*` values are **USD per token**. Human-readable $/1M ≈ `pricing.input × 1_000_000`. +- When using **$/1M** rates from the table below, cost ≈ `(prompt_tokens × input_rate + completion_tokens × output_rate) / 1,000,000`. +- When plugging API `pricing.*` values directly, omit the `/ 1,000,000` and also include cache tokens when present: + `(prompt_tokens × input) + (completion_tokens × output) + (cache_write_tokens × cache_write) + (cache_read_tokens × cache_read)`. - The `usage` block in each response reports the token counts used for billing. - Local models (e.g. `ollama/*`) are tracked at **$0 cost**, but token usage is still logged. @@ -87,17 +118,17 @@ Specify a model as **`provider/model`**, or use the virtual smart-routing model: | Model | Input (per 1M) | Output (per 1M) | | --- | --- | --- | | `openai/gpt-5` | $1.25 | $10 | -| `gpt-image-1` (image generation) | $10 | $40 | +| `openai/gpt-image-1` (image generation) | $5 | $40 | See [Image Generation](./guides/image-generation) for how image quality affects output-token usage. ## Billing with smart routing -When you request `hpprouter/auto`, billing uses the **resolved** model's pricing — not a price for `auto` itself. The resolved model is returned in the `X-HPP-Router-Resolved-Model` response header and recorded in your usage logs. See [Smart Routing](./smart-routing) for details. +When you request `hpprouter/auto`, billing uses the **resolved** model's pricing — not a price for `auto` itself (`pricing` is `null` on the models list). The resolved model is returned in the `X-HPP-Router-Resolved-Model` response header and recorded in your usage logs. See [Smart Routing](./smart-routing) for details. -## Checking your quota and usage +## Checking your usage -- `GET /api/quota-check` — remaining quota for the authenticated consumer. -- `GET /api/usage` — usage summary (requests, total tokens, total cost, remaining quota). +- `GET /api/quota-check` — check remaining balance for the authenticated consumer. +- `GET /api/usage` — usage summary (requests, total tokens, total cost). See [Quota & Usage](./guides/quota-and-usage). diff --git a/hpp-router/quickstart.mdx b/hpp-router/quickstart.mdx index c61c185..9adab87 100644 --- a/hpp-router/quickstart.mdx +++ b/hpp-router/quickstart.mdx @@ -13,7 +13,8 @@ Send the same chat completion request using the stack you prefer. All examples t ## Prerequisites -- An **HPP Router API key** from [HPP Hub](https://hub.hpp.io) +- An **HPP Router API key** from [HPP Hub](https://hub.hpp.io) (required for Kong authentication) +- x402 wallet payments for on-chain USDC transactions (wallet payment rail: `X-HPP-Payment-Rail: wallet`) - Base URL: `https://router.hpp.io` Store your key in an environment variable: @@ -71,7 +72,7 @@ console.log(completion.choices[0].message); ``` - + ```bash showLineNumbers curl -X POST https://router.hpp.io/llm/v1/chat/completions \ @@ -138,4 +139,4 @@ When you use `hpprouter/auto`, the model used for billing is returned in the `X- - [Authentication](./authentication) — API key vs. Bearer token. - [Models & Pricing](./models-and-pricing) — discover available models. -- [Guides](./guides/chat-completions) — chat, streaming, vision, images, quota, and errors. +- [Guides](./guides/chat-completions) — chat, streaming, vision, images, and errors. diff --git a/hpp-router/smart-routing.mdx b/hpp-router/smart-routing.mdx index c486938..79afed6 100644 --- a/hpp-router/smart-routing.mdx +++ b/hpp-router/smart-routing.mdx @@ -19,7 +19,7 @@ When you send `model: "hpprouter/auto"`, the gateway classifies the request and - + ```bash showLineNumbers curl -sS -D /tmp/headers.txt -o /tmp/out.json \ @@ -77,7 +77,7 @@ To read `X-HPP-Router-*` headers from browser JavaScript, the gateway must expos ## Billing -Billing always uses the **resolved** model's pricing and the upstream `usage` — there is no separate price for `hpprouter/auto`. The resolved model is recorded in your [usage logs](./guides/quota-and-usage). +Billing always uses the **resolved** model's pricing and the upstream `usage`. The resolved model is recorded in your [usage logs](./guides/quota-and-usage). ## Notes for client apps From 7a2084d5409af8d163dbda6da4c991bef2899262 Mon Sep 17 00:00:00 2001 From: croa Date: Wed, 15 Jul 2026 10:32:21 +0900 Subject: [PATCH 2/2] Add new model to consumer-v1 API reference - Included 'ollama/solidity-master:2' in the list of available models. This update enhances the API reference documentation for users integrating with the HPP Router. --- hpp-router/api-reference/consumer-v1.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/hpp-router/api-reference/consumer-v1.yaml b/hpp-router/api-reference/consumer-v1.yaml index cb97a65..7ebde02 100644 --- a/hpp-router/api-reference/consumer-v1.yaml +++ b/hpp-router/api-reference/consumer-v1.yaml @@ -169,6 +169,7 @@ components: - anthropic/claude-sonnet-4 - moonshotai/kimi-k2.6 - ollama/gpt-oss:120b + - ollama/solidity-master:2 messages: type: array items: