AgentFeed on Algorand

agentfeed-algo

一个基于 Algorand 的付费 x402 数据 API。它按次以 USDC 出售跨交易所清算数据流，并会告知你何时无法确定。

为 Algorand Foundation Global x402 Challenge 打造。

已在 Algorand 主网上线

https://algo.ochinimus.app

network   algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=
asset     USDC, ASA 31566704
facilitator  https://facilitator.goplausible.xyz
catalog   https://algo.ochinimus.app/catalog
manifest  https://algo.ochinimus.app/.well-known/x402

可免费查看，读取需付费。不付款调用任一路由，都会收到一个 402 响应，其正文包含路由、价格、资产以及付款后可获取的内容；付款挑战本身则以 base64 格式放在 PAYMENT-REQUIRED 标头中。其背后的数据流自 2026 年 7 月 8 日起，已记录 Binance、Bybit 和 OKX 上超过 900 个交易品种；在截至 2026 年 9 月 16 日之前的 7 个完整日里，平均每天约有 73,000 条清算记录。

销售内容

提供 5 个端点，以 USDC 计价，通过 x402 按请求付费，无需账户、API 密钥或注册。它们发布在 /v2 下。

这些路由最初发布时使用的 5 个路径，也就是 /v1 路径，仍然可以正常响应。它们使用相同的处理程序、付费墙和价格，并各自拥有独立的资源 URL。持有旧 URL 的 Agent 不会因迁移而无法使用。不过，现已不再对外公布 /v1：目录、清单、落地页和 MCP 服务列表中只包含 /v2，也不应再基于旧路径构建任何新内容。

按交易所划分某个交易品种在指定时间范围内的清算量，并区分多头或空头被清算的情况，价格为 0.02 USDC。 级联评分，用于衡量清算量是集中在单次突发中，还是均匀分布，价格为 0.05 USDC。 数据流在指定时间范围内覆盖的全部交易品种，让调用方能够区分覆盖范围与无数据情况，价格为 0.10 USDC。 各交易所的报告完整性，价格为 0.03 USDC。

第 5 个路由销售历史数据。它会返回某个交易品种在全部 3 个交易所上的完整已记录清算历史，从该交易品种首次出现在本数据流中一直到现在，可按小时或按日分桶，价格为 5.00 USDC。此处其他路由的回溯范围都不超过 7 天，区别仅在于此：清算记录无法事后补录，因此历史深度才是真正稀缺的部分。覆盖范围按交易品种说明，而非按整个数据流说明，因为某个交易品种可能要等到首次发生清算时才会出现，这可能比数据流启动晚数周；负载中也包含该交易品种自身的覆盖起始时间，因此不会让人误把我们的起始日期当成市场的起始时间。

每个路由调用一次，总费用为 5.2 USDC。实时价格发布在 /catalog 的 sweep_price_usdc 字段中，并根据目录计算而非手动填写；如果本行与该字段不一致，以端点为准，本文件已过时。

Global x402 挑战资格

作为一个 Composite 项目接入：五个端点共用一个 payTo 地址。

每条路由都带有所需的 x402-global-challenge 标签，并声明了 Bazaar 发现扩展，因此从未听说过此服务的 Agent 也能找到它、了解每条路由的价格，并仅凭列表构造有效请求。两者都在 compileCatalog 和 buildRoutes 中统一应用，而非逐条路由编写，因此不会有任何一个端点被遗漏。检查它们的测试会遍历此服务实际响应的每条路由，而不是只抽查一条，因此任何一条路由只要缺少其中之一，测试套件就会失败。

该标签位于 accepts[].extra 中，排行榜从这里读取，而不是从 resource.tags 中读取。它与资产小数位数以及协调器公布的 feePayer 一同放在那里，因为 ExactAvmScheme 会合并这些额外信息，而不是将其替换。

结算通过 GoPlausible 协调器在 Algorand 主网上进行，付款已完成端到端流程。当前的数量、对应的不同付款方以及结算总额，以账本记录为准，而不是以此文件中的内容为准，因此请使用 agentfeed-algo ledger 查询，不要相信此处手动填写的数字。

在 Agent 中使用

端点是一个 URL，而需要为其付款的对象看不到 URL。因此，本项目也提供了 MCP 服务。

npx -y -p @seekdaseek/agentfeed-algo agentfeed-algo-mcp

也可以在 MCP 客户端配置中将其配置为名为 agentfeed-algo 的服务，运行 npx -y @seekdaseek/agentfeed-algo，使用二进制文件 agentfeed-algo-mcp，并设置一个环境变量 ALGO_PAYER_MNEMONIC，其中存放一个拥有 USDC 且已选择加入资产 31566704 的 Algorand 账户助记词。

共有六个工具。四个是付费工具，分别对应四条短窗口路由。两个是免费工具：catalog 列出所有在售项目及其价格，payer_status 报告你的余额以及任何会阻碍付款的情况。两者都无需任何密钥即可使用，因此你可以安装它、查看有哪些内容，再决定是否要为账户充值。历史路由会通过 catalog 工具列出，其中包含价格和路径，但它没有专属工具。

付款来自你自己的账户。整个流程不会使用我们的密钥，也不需要创建账户。

未经测量的响应会作为工具错误返回，而不是作为数据返回。HTTP 层已经会拒绝对此类响应收费，但读取工具结果的 Agent 也需要相同的信号；一个看起来像答案的数据缺口，比没有答案更糟。

让它物有所值的关键

每个响应都会附带自身状态，共有三种状态。

已测量：我们发起了查询并获得了答案。

不存在：我们发起了查询，但市场中没有相关内容。在该时间窗口内没有发生清算，是对平静市场的一项真实发现，买方可以据此采取行动。

未测量：我们自己的查询失败了。可能是触发了速率限制、数据库被锁定，或查询抛出了异常。这并不是一项发现，而是缺少发现。

未测量的响应会返回 503，绝不会收费，即使我们直到验证付款后才发现这一点也是如此。我们会有意放弃这笔销售。Agent 开始按次付费后，最糟糕的产品就是卖出一个由你捏造的零值，因为调用方无法区分它和真实结果。与每次都给出答案的数据源相比，能够说明自己何时不知道的数据源，每次调用都更有价值。

运行

npm install
npm test
node bin/agentfeed-algo.mjs catalog

配置由环境变量驱动。复制示例并填写配置。

cp .env.example .env
node bin/agentfeed-algo.mjs doctor
node bin/agentfeed-algo.mjs serve

Doctor 会检查配置、目录和协调器，并为每项检查打印一行结果。只要其中任何一项检查失败，Serve 就会拒绝启动。

Mainnet 从不只是偶然

上面的部署运行在 mainnet。要部署到 mainnet，需要有意设置两个变量：将 ALGO_NETWORK 设为 mainnet，并将 ALGO_ALLOW_MAINNET 设为 yes；如果未设置配置，则会回退到 testnet，而不会转向 mainnet。

这是有意为之。一个变量拼写错误不应该就足以开始收取真实资金，而悄悄默认处理资金的服务迟早会把款项收进一个无人核实过的地址。

在 mainnet 上，预检还会拒绝 localhost 资源 URL、明文 facilitator、testnet 资产 ID，以及任何警告。在 testnet 上则允许通过警告。这种不对称正是关键：在 mainnet 上，配置错误会把钱送到一个无法撤回的地方。

payTo 地址经过校验和验证，而非仅做模式匹配

Algorand 地址是由 32 字节公钥加上 4 字节 SHA-512/256 校验和进行 base32 编码得到的。只检查长度和字符集的正则表达式，会轻易接受两个对调的字符。校验和不会；有一项测试会对调一对字符来证明这一点。

这是唯一一个拼写错误会悄无声息地造成真实资金损失的字段，因此这里使用真正的解码器，而不是模式匹配。

价格始终使用 BigInt

USDC 有 6 位小数。此服务中的每个价格都是以微 USDC 为单位的 BigInt 计数，绝不会使用浮点数。精度超出资产可表示范围的价格会报错，而不会被悄悄截短，因此 toMicroUsdc("0.0000001") 会抛出异常，而不是变成零。

x402 价格字段会作为资产金额传递，并明确携带资产 ID，因此小数永远不会被误认为属于错误的代币。

谁在付款

挑战会要求参与者证明付款者身份，而排行榜总额无法回答这个问题。10 个 Agent 各付款 20 次，与 1 个 Agent 付款 200 次，产生的总额相同，但代表的业务完全不同。

因此，每次验证和结算，无论成功与否，都会追加到本地账本中；摘要会优先呈现集中度，而不是总额。

node bin/agentfeed-algo.mjs ledger

关于为其提供数据的钩子，需要说明一点。撰写本文时，我还没有观察到 x402 传递给 onAfterSettle 的上下文对象结构，因此没有断言一个尚未见过的结构，而是让提取器尝试可能的字段路径；如果找不到付款者，就记录上下文的顶层键，而不是写入 null。2026-08-05 的第一笔真实结算让我们在有人会查看的账本中了解了其结构：上下文包含 paymentPayload、requirements、declaredExtensions、transportContext 和 result，付款者和交易 ID 位于 result 中。提取器仍会尝试其他路径，因为这样毫无成本，而且结构由上游决定，可能会发生变化。

架构

目录是一个数组，其他一切都由它派生而来。x402 路由配置、位于 /.well-known/x402 的公开清单、免费的 /catalog 列表、CLI 输出和测试都读取同一数据源，因此价格不会在一个地方更改，却在另一个地方保留旧值。

磁带存储是通过注入提供的。测试使用内存中的数组运行，绝不会打开文件；缺少磁带时会降级为未测量状态，而不会导致崩溃，这也是原因之一。

facilitator 客户端是通过注入提供的。测试绝不会访问网络。

测试

npm test

不联网、不读取墙上时钟、不休眠。端到端测试套件会在临时端口上启动真实的 Express 应用，并通过真实 HTTP 请求进行测试，包括启用付费墙的情况，因此 402 路径经过了验证，而非仅凭假设。

路由测试也通过 HTTP 进行，这并非多此一举。处理程序级别的测试无法发现服务器未传递的查询参数，而正是因为参数未被传递，历史路由才会忽略其 bucket 参数：处理程序会验证 bucket，并默认使用 hourly；它自己的测试也通过了，但服务器调用它时根本没有传入该参数。于是，bucket=day 被悄悄按 hourly 返回；无效的 bucket 也被按 hourly 返回并计费，而处理程序本应将其判定为未测量且不收费。问题出在路由器与处理程序之间的衔接处，因此现在相关测试也放在这里。

交易对才是符号，覆盖缺口不等于市场平静

行情数据存储的是 SOLUSDT，而不是 SOL。调用方请求 SOL 却得到 0 行时，不能告知他们“SOL 没有清算”，因为这是一个判断，而且是错误的；事实是，我们从未收录过这个名称的符号。

因此，首先要进行解析。系统会依次尝试为裸符号添加 USDT、USD 和 USDC 后缀，并返回解析后的交易对及解析方式。如果行情数据中没有该符号，则会以未测量状态返回，原因是 symbol_not_covered。未测量的内容不计费，因此覆盖缺口不会让调用方付费，也绝不会在他们的推理中被当作市场事实。

如果行情数据中收录了某个符号，但指定时间窗口内没有数据，则该符号为缺失。这才是关于市场平静的真实判断，并会照常计费。

协调器公布的网络标识符与客户端库不同

在自行调试之前，值得先了解这一点。CAIP-2 将链引用限制为 32 个字符，@x402/avm 包中的常量也遵循这一限制。GoPlausible 协调器公布 Algorand 时使用完整的 44 个字符的 base64 创世哈希（包括填充字符），而在同一响应中公布 Solana 时却正确地进行了截断。

这会导致两个问题，第二个更严重。

预检会比较这两种形式，并错误地报告“协调器不支持你的网络”。在主网上，这会导致服务因一个并不存在的问题而无法启动。

更糟的是，@x402/core 在自己的能力检查中也会进行同样的纯字符串比较。之后，每条付费路由都会因无法构建支付质询而失败，服务返回 503 而不是 402。在生产环境中，这意味着没人能向你付款，端点也无法使用。错误内容为：Facilitator does not support scheme exact on network algorand，后面跟着被截断的标识符。

这里最初的修复是在边界处进行规范化，包装协调器客户端，使其在 core 看到 getSupported 的结果之前先返回截断后的标识符。这样通过了能力检查，却在之后的验证阶段失败了，因为协调器会根据自己公布的标识符（未截断的形式）验证支付。基于截断形式构建的质询会返回 Network not supported，而此时调用方已经签名。相比启动时失败，这是更糟糕的失败时机。

因此，配置中保留未截断的标识符，也就是协调器自身用于验证的标识符，并且支付流程中的任何环节都不会重写它。

反对这种做法的理由在于资产解析，因为 @x402/avm 中的 USDC_CONFIG 没有未截断标识符对应的键。但这里不会遇到这个问题，因为价格不会以十进制数的形式传入，供基于网络键值表进行解析。它会以显式携带 ASA id 的资产金额形式传入，而 @x402/avm 中的 parsePrice 会原样返回该金额和资产，不会查询 USDC_CONFIG。可能导致问题的查找根本不会发生。

这之所以是上游 bug，而不是配置错误，是因为 @x402/avm 已经知道如何协调这两种形式。normalizeAlgorandNetwork 接受任一形式并返回规范形式，isAlgorandNetwork 接受两者，而 getNetworkFromCaip2 也能正确地将两者解析为 testnet 或 mainnet。机制包处理了这一问题，只是 core 的能力检查根本没有调用它。

规范化器仍保留在代码树中，并且仍有测试覆盖，因为预检会进行防御性比较；等到 core 在上游协调这两种形式时，测试也应明确体现这一点，而不应就此失效。还有一项测试会重放协调器的真实负载结构，并断言返回的是 402 而不是 503。

如果你正在使用 Algorand x402 构建应用，而你的付费路由返回 503，原因就在这里。

账本的已知限制

账本通过资源服务器的 verify 和 settle 钩子写入。未能通过验证的请求（例如支付标头格式错误）不会产生任何账本记录。协调器和链仍是权威记录来源；这个文件是它们的副本，而且只有已进入检查阶段的支付才会完整记录在其中。

还有第二个缺口，这个问题出在我们这里，而不是上游。迄今写入的每条记录都带有 null routeId 和 null path，因此账本可以记录谁支付了、支付金额以及对应的交易，但无法记录他们购买了哪条路由。提取器会在 requirements.resource 和其他可能的键中查找资源 URL，但在当前的上下文中，它还没有找到。账本旨在回答的付款方集中度问题不受影响，但目前无法通过这个文件查看各路由的收入。

限制

tape reader 需要一个清算表，其中包含 symbol、exchange、side、以毫秒为单位的 ts 和 usd 列。列名是 exchange，而不是 venue；symbol 是 SOLUSDT 这样的交易所交易对，而不是单独的代码。如果你的架构不同，只需更改存储即可。

账本是一个本地文件。它是我们对事实的副本，而非事实本身；事实存在于协调方和链上。

级联集中度按一分钟为间隔计算。对于永续合约清算来说，这个分辨率合理；对于其他任何情况，这个分辨率都是任意的。

只注册了 exact 方案。其他方案需要有各自的服务实现。

许可证

MIT。