Update HPP Router documentation to reflect x402 wallet integration an…#21
Update HPP Router documentation to reflect x402 wallet integration an…#21croa-blocko wants to merge 2 commits into
Conversation
…d 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.
hayarobi
left a comment
hayarobi
left a comment
There was a problem hiding this comment.
It appears that the term "quota" is no longer used, but the "quota & usage" title still appears on the left sidebar. Is this section being maintained as is?
| - anthropic/claude-sonnet-4 | ||
| - moonshotai/kimi-k2.6 | ||
| - ollama/gpt-oss:120b | ||
| - ollama/solidity-master:2 |
There was a problem hiding this comment.
I think that this model needs to be remained.
- 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.
dohoon84
left a comment
dohoon84
left a comment
There was a problem hiding this comment.
hpp-router 리포지토리(소스 코드, Kong 설정, SDK, docs 내 x402 섹션)와 대조하여 리뷰했습니다. 전반적으로 x402 지갑 결제(온체인 USDC.e) 반영 취지는 좋으나, 실제 구현과 어긋나는 부분이 여러 군데 있어 우선 문서/코드를 서로 맞추는 작업이 필요해 보입니다. 상세 코멘트는 각 라인에 남겼고, 아래는 파일 간에 공통으로 반복되는 이슈를 모아 정리한 것입니다.
1) 결제 레일 헤더명이 문서 전체에서 틀려 있습니다 (가장 중요)
authentication.mdx, quickstart.mdx, guides/chat-completions.mdx, guides/image-generation.mdx, guides/streaming.mdx, guides/vision-multimodal.mdx, api-reference/consumer-api.md, intro.md 전체에서 X-HPP-Payment-Rail: wallet 헤더를 쓰도록 안내하고 있는데, 실제 hpp-router 소스에서는 X-Payment-Rail: wallet 헤더를 사용합니다.
- 근거:
src/x402-config.js(isWalletPaymentRail이req.headers['x-payment-rail']를 읨),kong-plugins/kong/plugins/noosphere-router/handler.lua:235,kong/kong.yaml:593(CORS allow-list),client/src/lib/wallet/x402PaymentRequest.ts:109,client/src/lib/chat/streamChatCompletion.ts:178. X-HPP-Payment-Rail이라는 문자열은 hpp-router 코드베이스 어디에도 없습니다. 문서 그대로 호출하면 지갑 결제 레일이 인식되지 않을 것으로 보입니다. 전체 파일 일괄 수정이 필요합니다.
2) USDC → USDC.e
온체인 정산 토큰은 USDC.e(Bridged USDC, 0x401eCb1D350407f13ba348573E5630B83638E30D, src/x402-config.js의 USDC_E_ADDRESS)입니다. 이 저장소의 x402/intro.md, x402/networks-and-token.mdx도 이미 "USDC.e"로 일관되게 표기하고 있습니다. 이번 PR에서 "USDC"로만 표기된 부분(authentication.mdx, quickstart.mdx, models-and-pricing.mdx, guides/quota-and-usage.mdx, intro.md 등)을 "USDC.e"로 통일해 주세요. (검토자 지적사항)
3) API 키 발급 경로 — HPP 포털도 함께 명시 필요
authentication.mdx의 "Getting an API key"(diff 범위 밖이라 인라인 코멘트를 남기지 못했습니다, 16행: "API keys are issued through HPP Hub, the HPP developer portal.")와 intro.md 40행, quickstart.mdx 16행 모두 API 키 발급처를 HPP Hub로만 안내합니다. hpp-router 소스 확인 결과 API 키는 자체 포털(POST /api/user/keys, src/user-api.js)에서도 발급 가능하고, HPP Hub·admin·partner 경로로도 발급됩니다. "HPP Hub에서만 발급"으로 오독될 수 있는 현재 문구를 "HPP 포털에서 발급 가능하며, 추가로 HPP Hub를 통해서도 발급 가능"으로 보완해 주세요. (검토자 지적사항과 일치)
4) x402 프로토콜 링크
authentication.mdx 78행의 https://docs.x402.com 링크는 (a) 도메인이 실제 x402 재단 공식 문서 도메인(docs.x402.org)과 다르고, (b) 이 docs 저장소에 이미 HPP 전용 x402 문서 섹션(/x402, x402/intro.md 등)이 있으므로 외부 링크 대신 그쪽으로 연결하는 것이 맞아 보입니다. (검토자 지적사항)
5) GET /llm/v1/models 인증 필요 여부
models-and-pricing.mdx, authentication.mdx, consumer-api.md, consumer-v1.yaml, client-sdk/typescript.mdx에서 일괄적으로 "API 키 불필요"로 바뀌었는데, hpp-router의 kong/kong.yaml을 보면 /llm/v1/models 라우트에는 key-auth 플러그인이 적용되어 있어 Kong을 통한 실제 호출에는 API 키가 필요한 것으로 보입니다. 인증이 필요 없는 것은 별도 엔드포인트인 GET /public/v1/models(src/public-router.js)입니다. 실제로 라우팅이 무인증으로 바뀐 것이 맞는지 백엔드 쪽 확인 후 반영 부탁드립니다. (검토자 지적사항과 일치)
6) /api/quota-check 엔드포인트를 문서에서 삭제했는데 실제로는 존재
authentication.mdx, consumer-api.md의 엔드포인트 표에서 GET /api/quota-check가 삭제되고 GET /api/user/audit/:logId로 대체되었는데, hpp-router 소스(src/dashboard.js, kong/kong.yaml의 public allowlist ~/api/(usage|quota-check|pricing|info|audit)$)를 보면 /api/quota-check는 제거되지 않았습니다. 두 엔드포인트는 대체 관계가 아니라 둘 다 살아있으므로, 표에서 삭제하지 말고 /api/user/audit/:logId를 추가하는 형태로 수정해야 합니다. consumer-v1.yaml에는 애초에 /api/quota-check path가 그대로 남아있어 markdown과 yaml 간 불일치도 발생합니다.
7) /api/usage 응답 스키마 — 문서 간 불일치
guides/quota-and-usage.mdx는 응답 예시를 spent_usdc_micro/settle_success_count/settle_failed_count로 교체했지만, consumer-api.md의 UsageResponse 설명은 이 필드들을 언급하지 않고 quota/used/remaining만 제거했습니다. consumer-v1.yaml의 UsageResponse 스키마(397행~)는 여전히 quota/used/remaining을 required로 선언하고 있어 세 문서가 서로 다른 내용을 말하고 있습니다. 실제로는 ?rail=wallet 쿼리 파라미터가 있을 때만 정산 필드가 추가되고 기본 응답에는 quota 필드가 남는 것으로 보이니, 이 동작을 명확히 설명하고 세 문서를 통일해 주세요.
각 파일 상세 코멘트는 라인별로 남겼습니다. 확인 후 반영 부탁드립니다.
| # 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. |
There was a problem hiding this comment.
결제 토큰은 USDC가 아니라 USDC.e입니다. 요약 2) 참고.
| All consumer endpoints are authenticated: | ||
| | Endpoint | Auth | Purpose | | ||
| | --- | --- | --- | | ||
| | `GET /llm/v1/models` | Optional | [List models](./models-and-pricing) | |
There was a problem hiding this comment.
GET /llm/v1/models를 Optional로 표기했는데, kong/kong.yaml상 이 라우트에는 key-auth가 걸려 있어 실제로는 인증이 필요한 것으로 보입니다. 무인증 엔드포인트는 별도의 GET /public/v1/models입니다. 요약 5) 참고.
| | `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) | |
There was a problem hiding this comment.
표에서 GET /api/quota-check, GET /api/user/audit/:logId 행이 빠졌습니다. /api/quota-check는 삭제된 게 아니라 여전히 존재하는 엔드포인트입니다(src/dashboard.js). 요약 6) 참고.
| | `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. |
There was a problem hiding this comment.
헤더명이 틀렸습니다. 실제로는 X-Payment-Rail: wallet입니다. 요약 1) 참고.
|
|
||
| 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.). |
There was a problem hiding this comment.
같은 헤더명 오류(X-Payment-Rail)입니다. 또한 PAYMENT-REQUIRED 헤더에 지갑주소/micro-USDC 금액이 담긴다는 설명이 실제 x402 accepts 페이로드 스펙과 정확히 일치하는지 한 번 더 확인 부탁드립니다.
|
|
||
| - **`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. |
There was a problem hiding this comment.
"top up your wallet via the x402 protocol" 설명이 실제 충전 플로우와 맞는지 확인이 필요합니다. x402는 결제 프로토콜이고, USDC.e 충전(브릿지)은 이 저장소의 x402/networks-and-token.mdx 기준으로 HPP Hub의 브릿지 기능을 통해 이루어지는 것으로 보입니다. "HPP Hub에서 USDC.e를 브릿지/충전" 쪽이 더 정확할 수 있습니다.
| - **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. |
| 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. |
|
|
||
| ## Models | ||
|
|
||
| `models.list()` does **not** require an API key. |
There was a problem hiding this comment.
models.list()가 API 키 없이 호출 가능하다고 되어 있는데, 실제 HppRouter 생성자(packages/sdk/src/client.ts)는 apiKey가 없으면 즉시 throw합니다. 바로 아래 120행의 catalogClient 예시(apiKey 없이 생성)는 실행 시 에러가 날 것으로 보입니다.
| <TabItem value="typescript" label="TypeScript" default> | ||
|
|
||
| ```ts showLineNumbers | ||
| const usage = await client.usage.get(); |
There was a problem hiding this comment.
client.quota.check()를 문서에서 제거했는데, 실제 SDK(packages/sdk/src/client.ts)에는 quota.check()가 그대로 남아 있습니다. wallet 결제를 쓰지 않는 경우에는 여전히 사용 가능하다는 점을 남겨두는 것이 좋을 것 같습니다.
3 participants
…d on-chain USDC payments. Key changes include:
These updates ensure comprehensive guidance for users on utilizing the new payment system effectively.