Hermes 服务 x402 端点

Hermes 服务不止可以作为内部运行时。只要服务暴露稳定的 HTTP API 并返回可预测的 JSON 响应，Alephant 就能将其封装为受治理、具备支付能力的 x402 端点，供其他开发者和智能体付费调用。

核心思路很简单：

Buyer or agent
-> Alephant x402 Paid Endpoint
-> Alephant Workflow Agent
-> Hermes service HTTP endpoint
-> Hermes tool execution
-> Stable JSON result
-> Alephant trace, cost, revenue, and margin record

本页以 Finance News Report Service 为例。相同模式适用于任何能够接收 JSON 请求、在背后运行工具并返回稳定响应的 Hermes 服务。

视频演示

观看在 Alephant 中将 Hermes 服务配置为 x402 端点的过程。

Open the Loom walkthrough

准备内容

创建付费端点前，请确保已具备：

• 已部署到生产环境的 Hermes 服务。
• 一个稳定的 HTTPS 端点，例如 POST /tools/finance_news_report。
• 买方可以依赖的 JSON 请求与响应契约。
• 不暴露运行日志、回溯信息、密钥、本地文件路径或内部主机名的响应体。
• 可在其中创建工作流智能体和付费端点的 Alephant 工作区。
• 用于接收 x402 付款的钱包或结算配置。

1. 将 Hermes 服务准备为 API

在 Alephant 将其转为付费端点之前，Hermes 服务应表现得像一个可正常调用的 API。在财经新闻示例中，上游运行时接收 POST 请求，并在 JSON 对象中返回 Markdown 报告。

对于付费端点，应将 Hermes 服务边界配置为公开契约：

不要将上游 Hermes URL 作为产品契约。公开契约是 Alephant x402 端点；Hermes URL 是该端点背后的私有转发目标。

2. 定义请求与响应契约

只有调用方知道该发送什么以及会收到什么，Alephant 才能将服务变现。请让 Hermes 请求 Schema、响应 Schema 和示例与实际运行时保持一致。

请求体示例：

1
{
2
  "limit": 3,
3
  "deep_fetch": false
4
}

字段说明：

成功响应示例：

1
{
2
  "status": "ok",
3
  "tool": "finance_news_report",
4
  "format": "markdown",
5
  "content": "# Finance News Report\n\n## 1. Market headline..."
6
}

错误响应示例：

1
{
2
  "status": "error",
3
  "code": "UPSTREAM_TIMEOUT",
4
  "message": "The finance news report timed out before completion."
5
}

良好的付费端点响应应当：

• 返回一个 JSON 对象，而非原始日志流或任意工具输出列表。
• 包含清晰的成功或错误字段，例如 status。
• 避免泄露 API 密钥、原始 stderr、回溯信息、钱包元数据、本地路径或 Hermes 内部执行细节。
• 在各服务版本间保持字段名稳定。
• 返回客户端能够处理的、带 HTTP 状态码的有用错误。

3. 在 Alephant 中创建工作流智能体

在 Alephant 中创建一个代表 Hermes 服务运行时的智能体。

选择 Workflow Agent，然后选择 Custom Webhook 作为运行时。这会告知 Alephant：智能体执行应转发至外部 HTTPS 端点，而非由仅模型的 AI Agent 直接处理。

使用描述付费能力而非内部实现的名称和说明。例如：

连接运行时时，请使用生产 Hermes URL，例如 https://<you-domain-host>/tools/finance_news_report。如果 Hermes 服务需要网关签名密钥或私有请求头，请在运行时连接中配置，以免买方看到它们。

4. 创建 x402 付费端点

工作流智能体创建完成后，在 Alephant 中新建一个智能体付费端点。

先配置端点基本字段：

然后完成商业配置：

• 设置每次调用的价格。
• 选择 x402 配置支持的结算网络和资产。
• 配置速率限制、买方访问、预算护栏和滥用控制。
• 决定以私有、内部还是市场形式发布。
• 在广泛分发前确保收款钱包和收入提现设置已就绪。

x402 使用 HTTP 402 Payment Required 流程。调用方请求端点、收到付款要求、提交已签名付款载荷，并在付款验证和策略检查通过后收到 Hermes 服务结果。

添加 Schema 与示例

端点发现需要 Schema。外部智能体通过它了解参数、预期响应和定价要求。

输入 Schema 示例：

1
{
2
  "type": "object",
3
  "required": ["limit", "deep_fetch"],
4
  "properties": {
5
    "limit": {
6
      "type": "integer",
7
      "description": "Maximum number of news items to include in the report.",
8
      "minimum": 1,
9
      "maximum": 10,
10
      "default": 3,
11
      "examples": [3]
12
    },
13
    "deep_fetch": {
14
      "type": "boolean",
15
      "description": "When true, enables deeper retrieval before generating the report.",
16
      "default": false
17
    }
18
  }
19
}

请求示例：

1
{
2
  "limit": 3,
3
  "deep_fetch": false
4
}

响应示例：

1
{
2
  "status": "ok",
3
  "tool": "finance_news_report",
4
  "format": "markdown",
5
  "content": "# Finance News Report\n\n..."
6
}

Alephant 中的 Schema 应与运行时契约完全匹配。如果服务添加了新的输出字段，请在广泛发布端点前更新 Schema 和示例。

使用签名密钥验证网关来源

如果可从公网访问 Hermes 服务 URL，请验证 Alephant 网关签名，防止客户端绕过 x402 直接调用上游服务。

这不是买方 API 密钥认证。买方认证、付款和结算由 x402 处理。签名密钥仅用于确认请求来自 Alephant 付费网关。

X-Alephant-Timestamp
X-Alephant-Signature

服务器应使用 Alephant 签名密钥验证这些请求头，验证失败时拒绝请求。请将签名密钥存储在密钥管理器或受保护的环境变量中，不要提交到仓库或在市场示例中暴露它。

5. 发布到市场

端点发布后，可与其他 x402 条目一同出现在 Alephant 市场中。

一个好的条目应说明服务完成的具体工作：

• 买方提供什么输入。
• 买方获得什么输出。
• 使用了哪些数据源。
• 结果是确定性的、AI 生成的，还是尽力而为的。
• 报告通常需要多长时间。
• 如何返回错误和超时。

对于财经新闻示例，条目应明确说明：此端点抓取实时财经新闻，并返回其他智能体或应用可使用的英文 Markdown 报告。

6. 测试付费调用

先从受信任服务器或私有网络直接测试 Hermes 服务：

$
curl -X POST "https://<you-domain-host>/tools/finance_news_report" \
>
  -H "Content-Type: application/json" \
>
  -d '{"limit":3,"deep_fetch":false}'

然后在不带付款载荷的情况下测试 Alephant x402 端点。预期响应为 HTTP 402 Payment Required。

$
curl -X POST "https://pay.alephant.io/x402/finance-news-report-service" \
>
  -H "Content-Type: application/json" \
>
  -d '{"limit":3,"deep_fetch":false}'

按 x402 协议对付款要求进行签名，然后携带已签名付款载荷再次发送请求：

$
curl -X POST "https://pay.alephant.io/x402/finance-news-report-service" \
>
  -H "Content-Type: application/json" \
>
  -H "PAYMENT-SIGNATURE: <signed-payment-payload>" \
>
  -d '{"limit":3,"deep_fetch":false}'

调用成功后，在 Alephant 中检查：

• 付款验证和结算状态。
• 工作流智能体执行状态。
• Hermes 服务响应延迟。
• 端点错误率。
• 如有追踪，AI token 成本和外部工具成本。
• 收入、费用和已知利润率。
• 与端点和智能体运行关联的请求日志。

生产清单

广泛推广端点前：

• Hermes 服务已部署到生产环境并返回稳定 JSON。
• Alephant 端点 Schema 与线上 Hermes 请求和响应契约匹配。
• 上游 Hermes URL 受到私有网络、网关来源验证或等效控制的保护。
• 公开示例不暴露真实主机名、IP 地址、密钥、回溯信息、stderr 或本地文件路径。
• 当可从公网访问上游服务时，已验证 X-Alephant-Timestamp 和 X-Alephant-Signature。
• 已配置端点策略、速率限制、超时预期和买方访问控制。
• 按调用追踪收入、模型成本、外部 API/工具支出和利润率。
• 请求或响应契约变化时，端点已进行版本控制。

相关文档

• x402 Overview
• How x402 Works
• Bazaar Quality Ranking
• Alephant Marketplace
• Paid Endpoints