Hyphae Gateway 开发者指南

这页是面向接入方的完整说明：如何通过/api/store/search和/api/store/invoke完成 agent 调用，并处理 x402 的 402 支付重试流程。

1. 快速开始

启动本地服务并加载依赖。
运行示例脚本，脚本会先 search，再 invoke，并演示 402 重试。

pnpm install
pnpm dev
node examples/gateway-invoke.mjs

对应示例文件：examples/gateway-invoke.mjs，文档基线：docs/gateway-mvp.md。

2. Gateway API 概览

Endpoint	Purpose	Details
GET /api/store/search	Search providers and get a stable unified agent id.	Supports provider/category/price filters. Use results[i].id as invoke input.
POST /api/store/invoke	Gateway proxy invocation for provider endpoint.	Validates id, resolves provider agent, blocks private-network targets, forwards request and selected payment headers.

3. x402 流程与本项目映射

Concept	x402 / Protocol	Hyphae Gateway
HTTP 402 Payment Required	Seller/API returns 402 when payment proof is missing/invalid.	Gateway passes through upstream 402 status and body so client can continue payment flow.
accepts requirements	Payment requirements include network, amount, asset, payTo and scheme details.	Client side reads body.accepts (if present) and decides how to sign and retry.
Payment headers	Common headers in x402 ecosystem include PAYMENT-REQUIRED and PAYMENT-SIGNATURE.	Current invoke API accepts payment.headerName = X-PAYMENT or PAYMENT-SIGNATURE, and forwards upstream payment response headers X-PAYMENT-RESPONSE / PAYMENT-RESPONSE.
Key custody	Buyer signs locally; avoid exposing private keys to third-party services.	Project docs follow non-custodial model. signPayment is placeholder; implement local wallet/KMS/HSM signing.

典型调用序列

1) GET /api/store/search -> 选出 result.id
2) POST /api/store/invoke { id, input } -> 可能返回 402
3) 读取 body.accepts + X-PAYMENT-RESPONSE / PAYMENT-RESPONSE
4) 本地签名后重试:
   POST /api/store/invoke {
     id,
     input,
     payment: { headerName: "X-PAYMENT" | "PAYMENT-SIGNATURE", value: "..." }
   }

4. 请求示例

第一次调用（不带 payment）

curl -X POST http://localhost:3000/api/store/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "id": "coinbase:https://api.example.com/weather",
    "input": {
      "city": "Shanghai",
      "unit": "c"
    }
  }'

402 后带 payment 重试

curl -X POST http://localhost:3000/api/store/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "id": "coinbase:https://api.example.com/weather",
    "input": {
      "city": "Shanghai",
      "unit": "c"
    },
    "payment": {
      "headerName": "X-PAYMENT",
      "value": "<your-local-signature>"
    }
  }'

5. 错误码速查

Code	Meaning
200 / 201	Upstream invocation succeeded and response is proxied back.
402	Payment required from upstream. Read body.accepts and response payment headers, then retry with payment field.
404	Agent id not found in corresponding provider adapter.
413	Request body exceeds 64KB limit.
422	Invalid payload/id, blocked endpoint (localhost/private network), unsupported provider invoke policy, or invalid GET input shape.
502	Gateway failed to call upstream endpoint or upstream returned invalid JSON.
504	Gateway upstream timeout (default 10s).

6. 安全与落地建议

Security: 不要把私钥托管到网关服务。推荐在调用方运行时（browser/serverless/agent runtime）本地签名，或使用 KMS/HSM。

Security: 不要记录完整 payment token/signature 到日志；只记录前缀、哈希或 request id。

Security: 先做只读/沙盒验证：使用测试网络和小额度，验证 402 -> retry -> success 全链路后再放大流量。