让开源，少一点语言距离。
npm包中文文档

@faremeter/middleware

中文文档
0.22.0发布于 2026/05/27LGPL-3.0-onlyTypeScriptESM + CJS近 30 天下载 2533

使用 x402 协议在 API 端点上添加支付墙的服务器中间软件

中文使用文档
中文原文
文档目录48 节
  1. 安装
  2. 特征
  3. API 参考
  4. 职能
  5. 创建 HTTPF促进器汉德勒
  6. 寻找匹配支付要求
  7. 寻找匹配支付要求V2
  8. 放宽对V2的要求
  9. 支持变量
  10. 验证Middlewares 参数
  11. 生成能力
  12. 生成策略
  13. 来源资源信息
  14. 接受定价
  15. 创建 RemoteX402 手提箱
  16. 解析
  17. 解析能力
  18. 处理中软件请求
  19. 创建中间软件
  20. 创建中间软件
  21. 古老的LLRUCACHE
  22. 方法
  23. 类型
  24. 古老的LLRUCACHEOPTs 维基语录链接:名人名言 - 分类
  25. 放松要求
  26. 放宽要求V2
  27. 支持的版本配置
  28. 普通中间软件
  29. 创建 RemoteX402 手提箱Args
  30. 解析配置
  31. 抓取结果V1
  32. 抓取结果V2
  33. 抓取结果
  34. 授权ResultV1
  35. 授权ResultV2
  36. 授权结果
  37. 获取
  38. 支付政策
  39. 中间软件Body ContextV1
  40. 中间软件Body ContextV2
  41. 抓取结果MPP
  42. 授权ResultMPP
  43. 中间软件Body 文本MPP
  44. 中间软件Body 文本
  45. 处理中软件请求
  46. 实例
  47. 相关软件包
  48. 许可证

@ faremeter/ 中间软件

用于使用x402协议向API端点添加支付壁的服务器中间软件.

安装

pnpm install @faremeter/middleware

特征

  • 付费墙任意终点 - 添加 middleware 转到任何路径
  • 框架不可知性 - 快报、 Hono 或 定制
  • 多链支持-索拉纳、EVM、可扩展
  • 快速验证 - 付款要求缓存
  • 调解人一体化-处理和解核查

API 参考

职能

创建 HTTPF促进器汉德勒

创建一个 FacilitatorHandler 代表到远程调解人 通过HTTP.

胶层构造有效 x402PaymentRequirements 从 ResourcePricing 使用操作器的申报 schemes,然后通过 他们去 getRequirements。这个处理器将操作器输入到 主持人 /accepts 浓缩的终点.

缓存键稳定性:缓存假设相同 accepts 数组 制作相同的主持人答复。 如果调解人返回 时间依赖值(例如:. recentBlockhash),使用简称 maxAge 或禁用缓存.

函数类型
createHTTPFacilitatorHandler(facilitatorURL: string, opts: CreateHTTPFacilitatorHandlerOpts) => FacilitatorHandler

寻找匹配支付要求

找到匹配客户端v1支付有效载荷的支付要求.

函数类型
findMatchingPaymentRequirements(accepts: x402PaymentRequirementsV1[], payload: x402PaymentPayloadV1) => any

参数:

  • accepts: - 调解人接受的付款要求分组
  • payload- 客户的付款有效载荷

回返情况:

匹配要求, 如果找不到匹配则未定义

寻找匹配支付要求V2

找到匹配客户端v2支付有效载荷的支付要求.

函数类型
findMatchingPaymentRequirementsV2(accepts: x402PaymentRequirements[], payload: x402PaymentPayload) => any

参数:

  • accepts: - 调解人接受的付款要求分组
  • payload: - 客户端的 v2 支付有效载荷

回返情况:

匹配要求, 如果找不到匹配则未定义

放宽对V2的要求

将 v1 放宽的要求转换为 v2 格式, 保留所有字段 包括 extra。 。 。 .

函数类型
relaxedRequirementsToV2(req: x402PaymentRequirementsV1) => x402PaymentRequirements

支持变量

解析并验证支持的版本配置 . 返回已解析配置并应用默认值 . 如果配置无效则丢出 .

函数类型
resolveSupportedVersions(config?: SupportedVersionsConfig or undefined) => Required<SupportedVersionsConfig>

验证Middlewares 参数

验证 CommunityMiddlewareArgs 的配置模式完全相同 .

函数类型
validateMiddlewareArgs(args: CommonMiddlewareArgs) => void

生成能力

衍生物 HandlerCapabilities 从放松的v1要求. 框架适配器用于构建 HTTP 包装器的能力 从遗产 accepts 配置 .

函数类型
deriveCapabilities(accepts: x402PaymentRequirementsV1[]) => HandlerCapabilities

生成策略

从放松的v1要求中衍生出一套独特的x402计划. QQlink 的同父异母关系获得能力 ; 保持分离, 因为计划是 x402- 特异性, 住在处理器上而不是上 {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}你应该知道 {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}我是谁.

函数类型
deriveSchemes(accepts: x402PaymentRequirementsV1[]) => string[]

来源资源信息

从 v1 提取资源信息接受条目 . 被框架适配器用于为402响应构建资源信息.

函数类型
deriveResourceInfo(accepts: x402PaymentRequirementsV1[], resourceURL: string) => x402ResourceInfo

接受定价

函数类型
acceptsToPricing(accepts: x402PaymentRequirementsV1[]) => ResourcePricing[]

创建 RemoteX402 手提箱

创建由远程 HTTP 协调器支持的x402 辅助处理器 .

这是可堆叠的等同物 facilitatorURL + 键 accepts (原始内容存档于2018-09-29). shortwand on QQlink CommunityMiddlewareArgs}. 需要的时候使用 将远程 x402 调试器和进程内 MPP 处理器结合到 同一个中间软件.

函数类型
createRemoteX402Handlers(args: CreateRemoteX402HandlersArgs) => FacilitatorHandler[]

回返情况:

数组 FacilitatorHandler 适用于 createMiddleware({ x402Handlers: ... })。 。 。 .

解析

解析 QQLink CommunityMiddlewareArgs} 进入处理器 + 定价 Tuple 需要的就是这个链条 给 facilitatorURL 路径, 创建 HTTP 处理器包装并转换接受定价.

函数类型
resolveConfig(args: CommonMiddlewareArgs) => ResolvedConfig

解析能力

决定身体回调是否应当在 /request (一阶段)或推迟到 /response (分两相.

canAuthorizehasAuthorizepincapturesAt
虚假任意无request
真实虚假无request
真实真实无response
任意任意"request"request
真实任意"response"response

canAuthorize 即"任何实际接受此方案的管理者 / 方法宣布验证”。 对于x402,候选组合是: narrowHandlers(handlers, requirements) 进一步过滤 h.schemes?.includes(requirements.scheme) - 方案过滤器是 负载因为 narrowHandlers 只检查网络和 资产,所以没有它 一个多方案处理器集 一个核实 - 能处理器会漏出 canAuthorize = true 计划 只能由专人负责 对于MPP, 候选组合是 精确过滤的处理器 method 相匹配的。 匹配的。 中间的软件 在援引前计算每项请求的上游 body,所以请 身体回调只需读取 context.capturesAt。 。 。 .

pin 是操作员提供的覆盖 PaymentPolicy.pin 键 <protocol>:<scheme-or-method>针入 "response" 对不能授权的操作员,在施工时拒绝 以 validateOperationPolicies 在中间软件-openapi。 如果有的话 在运行时到达此解析器( 例如程序规格 绕过验证) authorize() 电话会扔"不" 操作员接受了核查 以500.. 而不是默默地降级到一个阶段.

函数类型
resolveCapturesAt(canAuthorize: boolean, hasAuthorize: boolean, pin?: CapturesAt or undefined) => CapturesAt

处理中软件请求

核心中件请求处理器,处理x402和MPP支付流量.

代表特定协议胶层 挑战生成, 和解与核查。 中间软件格式 HTTP 响应 但绝不直接构建协议类型.

函数类型
handleMiddlewareRequest<MiddlewareResponse>(args: HandleMiddlewareRequestArgs<MiddlewareResponse>) => Promise<MiddlewareResponse or undefined>

创建中间软件

创建Express中端软件,用于在 x402 和 MPP 付款后运行.

函数类型
createMiddleware(args: CommonMiddlewareArgs) => Promise<(req: Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>, res: Response<...>, next: NextFunction) => Promise<...>>

参数:

  • args: - 配置包括处理器+定价或促进器 URL

回返情况:

一个快取中件功能

创建中间软件

创建 Hono 中间软件, 用于在 x402 和 MPP Pay 后面的出站口 .

中间软件拦截请求,检查付款信头,验证 ,然后通过 x402 或 MPP 协议结算付款,并且只允许 如果付款成功,则请求继续进行.

函数类型
createMiddleware(args: CreateMiddlewareArgs) => Promise<MiddlewareHandler>

参数:

  • args: - 配置包括处理器+定价或促进器 URL

回返情况:

一个Hono中件处理器

古老的LLRUCACHE

一个 LRU 缓存, 带有基于时间的过期 .

条目超过最大年龄或缓存到达时被删除 容量(至少最近使用的条目首先被删除).

方法

起来

方法类型
get(key: K) => V or undefined

设置

方法类型
put(key: K, value: V) => void

类型

古老的LLRUCACHEOPTs 维基语录链接:名人名言 - 分类

AgdLRUCAche 的配置选项 .

类型类型
AgedLRUCacheOpts{ /** Maximum number of entries. Defaults to 256. */ capacity?: number; /** Maximum age in milliseconds before entries expire. Defaults to 30000. */ maxAge?: number; /** Custom time function for testing. Defaults to Date.now. */ now?: () => number; }

放松要求

类型类型
RelaxedRequirementsPartial<x402PaymentRequirementsV1>

放宽要求V2

类型类型
RelaxedRequirementsV2Partial<x402PaymentRequirements>

支持的版本配置

中间软件所支持的 x402 协议版本的配置 . 至少必须启用一个版本 .

类型类型
SupportedVersionsConfig{ /** Support x402 v1 protocol (JSON body responses, X-PAYMENT header). Default: true */ x402v1?: boolean; /** Support x402 v2 protocol (PAYMENT-REQUIRED header, PAYMENT-SIGNATURE header). Default: false */ x402v2?: boolean; }

普通中间软件

所有中间软件执行共用的配置参数 . 支持两种相互排斥的模式:进程内处理器或远程促进器.

类型类型
CommonMiddlewareArgs{ /** x402 handlers for in-process settlement. */ x402Handlers?: FacilitatorHandler[]; /** MPP method handlers for in-process settlement. */ mppMethodHandlers?: MPPMethodHandler[]; /** Protocol-agnostic pricing for in-process handlers. */ pricing?: ResourcePricing[]; /** URL of a remote facilitator service (backward compat). */ facilitatorURL?: string; /** Payment requirements for the remote facilitator path. */ accepts?: (RelaxedRequirements or RelaxedRequirements[])[]; /** Cache configuration for remote facilitator responses. */ cacheConfig?: AgedLRUCacheOpts and { disable?: boolean }; /** Which x402 protocol versions to support. */ supportedVersions?: SupportedVersionsConfig; }

创建 RemoteX402 手提箱Args

类型类型
CreateRemoteX402HandlersArgs{ facilitatorURL: string; accepts: (RelaxedRequirements or RelaxedRequirements[])[]; cacheConfig?: AgedLRUCacheOpts and { disable?: boolean }; }

解析配置

类型类型
ResolvedConfig{ handlers: FacilitatorHandler[]; pricing: ResourcePricing[]; mppHandlers: MPPMethodHandler[]; resourceInfo?: x402ResourceInfo; }

抓取结果V1

QQ 类型 QQ 类型 |----------------------------------------------------------------------------------------- -------------------------------------------------------------------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- - - - - - - - - - - - - - - - - -- - - - - - - - - - - - - - - - - -- - - - - - - - - - - - - - - - - - - - - - | CaptureResultV1 | | { success: true; response: x402SettleResponseV1 } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

抓取结果V2

QQ 类型 QQ 类型 |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ------- - -- - - - -- - - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- - - - - - - - - - - - - - - - - - - - - -- - | CaptureResultV2 | | { success: true; response: x402SettleResponse } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

抓取结果

QQ 类型 QQ 类型 |------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------ ------------------ ------- - - - -- -- -- --- | CaptureResult | | CaptureResultV1<MiddlewareResponse> or CaptureResultV2<MiddlewareResponse> |

授权ResultV1

QQ 类型 QQ 类型 |------------------------------------------------------------------------------------------------------------------------------------------------------------------ - - - - - - - - - - -- - - - - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- - - - - - - - - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | AuthorizeResultV1 | | { success: true; response: x402VerifyResponseV1 } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

授权ResultV2

QQ 类型 QQ 类型 |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - - - - - - - - - - - - - - - - - - -- --- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- - - - - - - - - | AuthorizeResultV2 | | { success: true; response: x402VerifyResponse } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

授权结果

QQ 类型 QQ 类型 |------------------------------------------------------------------------------------------------------------------------------------------------------------- -- -- - - - - - - - - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- - - - - - - - - - - - - - - - - - - - - -- - - - - - - - - - - - - - - - - - - - | AuthorizeResult | | AuthorizeResultV1<MiddlewareResponse> or AuthorizeResultV2<MiddlewareResponse> |

获取

当身体召回应驱动捕获.

"request" - 一个阶段:身体呼叫 capture() 立即和 在生产资源之前,支付就已结清.

"response" - 两阶段:身体呼叫 authorize() 现在和推迟 抓取到后期( OpenAPI 网关抓取于 /response 一旦知道最后数额.

中间软件通过 QQlink 解析 CapturesAt} 解决每件请求 从匹配的处理器的授权能力和规则 hasAuthorize 因此,身体召回 从来没有检查 上下文形状以决定要走的路径.

类型类型
CapturesAtrequest" or "response

支付政策

业务支付政策。 限制哪些协议计划/ 给定的路由接受方法,可选择的标点特定 一到一相或两相捕捉,无论操作者 已宣布的能力.

键入 allow 财务报告和审定财务报表 pin 形式为 "<protocol>:<id>"数字 :

  • "x402:exact", (中文(简体) ), "x402:permit2" - x402计划
  • "mpp:solana" - MPP方法

协议前缀是区分大小写并使用小写线条 窗体( e)"mpp:"没有 "MPP:"),匹配各种计划和方法 在协议本身上被识别.

allow: undefined 允许每一个注册的计划和方法. allow: [] . 否认他们全体.

pin["x402:exact"].capturesAt: "request" 一个阶段的俘虏 无论操作者是否支持该计划 handleVerify 无论规则是否 authorize。 。 。 . 针到 "response" 对不能授权的操作员的 构造时捕获到配置错误 .

类型类型
PaymentPolicy{ allow?: string[]; pin?: Record<string, { capturesAt?: CapturesAt }>; }

中间软件Body ContextV1

向中间软件正文处理器提供用于 v1 协议请求的背景 . 载有付款信息和行业标准 authorize 编号 : capture 操作。 在引擎盖下 这些发送到匹配的 x402 辅助处理器 handleVerify 编号 : handleSettle。 。 。 .

类型类型
MiddlewareBodyContextV1{ protocolVersion: 1; capturesAt: CapturesAt; paymentRequirements: x402PaymentRequirementsV1; paymentPayload: x402PaymentPayloadV1; capture: () => Promise<CaptureResultV1<MiddlewareResponse>>; authorize: () => Promise<AuthorizeResultV1<MiddlewareResponse>>; }

中间软件Body ContextV2

向中间软件处理器提供 v2 协议请求的背景 . 载有付款信息和行业标准 authorize 编号 : capture 操作。 在引擎盖下 这些发送到匹配的 x402 辅助处理器 handleVerify 编号 : handleSettle。 。 。 .

类型类型
MiddlewareBodyContextV2{ protocolVersion: 2; capturesAt: CapturesAt; paymentRequirements: x402PaymentRequirements; paymentPayload: x402PaymentPayload; capture: () => Promise<CaptureResultV2<MiddlewareResponse>>; authorize: () => Promise<AuthorizeResultV2<MiddlewareResponse>>; }

抓取结果MPP

QQ 类型 QQ 类型 |-------------------------------------------------------------------------------------------------------------------------------------------- -------------------------------------------------------------- ----- -- --------- ------------- - - - - - - ------ ---- -- --- - - | CaptureResultMPP | | { success: true; receipt: mppReceipt } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

授权ResultMPP

QQ 类型 QQ 类型 |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ - - - - ---- - - - - - - - - - - - - - - - - -- - - - - - - - - - - - -- - - - - - - - - - - - - -- - - - - -- - - - - - - - - - - -- - - - - - - - - - | AuthorizeResultMPP | | { success: true; receipt: mppReceipt } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

中间软件Body 文本MPP

为 MPP 协议请求提供上下文给中间软件正体处理器 .

authorize 因为不是每个 MPP 方法处理器执行 handleVerify时 capturesAt === "response" 中间软件 担保 authorize 定义( 解析器只选择 "response" 当至少有一个匹配的处理器可以验证时).

类型类型
MiddlewareBodyContextMPP{ protocolVersion: "mpp"; capturesAt: CapturesAt; credential: mppCredential; capture: () => Promise<CaptureResultMPP<MiddlewareResponse>>; authorize?: or (() => Promise<AuthorizeResultMPP<MiddlewareResponse>>) or undefined; }

中间软件Body 文本

为中间软件处理器提供上下文 . 使用协议Version来区分v1,v2和mpp请求类型.

QQ 类型 QQ 类型 |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ - - -- - - - - - --- --- - - - -- -- - -- -- -- -- - -- - - - --- - - -- - - - - - - - - - - - - - - -- - - | MiddlewareBodyContext | | MiddlewareBodyContextV1<MiddlewareResponse> or MiddlewareBodyContextV2<MiddlewareResponse> or MiddlewareBodyContextMPP<MiddlewareResponse> |

处理中软件请求

核心中件请求处理器的参数 . 针对具体框架的中间软件实施 对象到此接口.

类型类型
HandleMiddlewareRequestArgs{ /** x402 handlers for in-process settlement. */ x402Handlers?: FacilitatorHandler[]; /** MPP method handlers for in-process settlement. */ mppMethodHandlers?: MPPMethodHandler[]; /** Protocol-agnostic pricing entries for the current request. */ pricing: ResourcePricing[]; /** The resource URL being accessed. */ resource: string; /** Resolved supported versions configuration. */ supportedVersions: Required<SupportedVersionsConfig>; /** Function to retrieve a request header value. */ getHeader: (key: string) => string or undefined; /** Function to send a JSON response with optional headers. */ sendJSONResponse: ( status: PossibleStatusCodes, body?: PossibleJSONResponse, headers?: Record<string, string>, ) => MiddlewareResponse; /** Handler function called when a valid payment is received. */ body: ( context: MiddlewareBodyContext<MiddlewareResponse>, ) => Promise<MiddlewareResponse or undefined>; /** Optional function to set a response header. */ setResponseHeader?: (key: string, value: string) => void; /** Optional pre-built resource info for the 402 response. */ resourceInfo?: x402ResourceInfo; /** Optional accessor for the request body (for RFC 9530 digest). */ getBody?: () => Promise<ArrayBuffer or null>; /** * Whether the matched pricing rule has an explicit 授权* expression (i.e. is two-phase). Drives the per-handler获取* decision resolved before each机构invocation. Defaults to false; * non-OpenAPI callers that have no rule shape leave this unset and * the middleware treats every request as one-phase. */ hasAuthorize?: boolean; /** * Per-operation payment policy. Restricts which schemes / methods * are advertised in the 402 challenge, rejects payments for * disallowed schemes, and threads针overrides into the *获取 resolution per matched handler. */ policy?: PaymentPolicy; }

实例

参见 票价计算仓库数字 :

许可证

LGPL-3.0 仅限

版本与发布记录

@faremeter/middleware 共发布 33 个版本，首次发布于 2025/07/31；过去 12 个月发布了 12 个版本。

版本发布日期距今
0.22.0latest2026/05/275 个月前
0.21.02026/04/216 个月前
0.20.12026/04/147 个月前
0.20.02026/04/147 个月前
0.19.02026/03/217 个月前
0.18.02026/03/207 个月前

关于 @faremeter/middleware 的常见问题

@faremeter/middleware 是什么？

使用 x402 协议在 API 端点上添加支付墙的服务器中间软件

如何安装 @faremeter/middleware？

在项目目录运行 npm install @faremeter/middleware，或使用 pnpm add / yarn add / bun add。

@faremeter/middleware 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@faremeter/middleware 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@faremeter/middleware 可以商用吗？

@faremeter/middleware 使用 LGPL-3.0-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

@faremeter/middleware 的下载量有多少？

根据 npm 官方下载统计，@faremeter/middleware 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,533 次，日均约 84 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@faremeter/middleware 还在维护吗？

最新版本 0.22.0 发布于 2026/05/27（5 个月前）；至今共发布 33 个版本，其中过去 12 个月发布了 12 个；首次发布于 2025/07/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。