agent-context-api

Agent Context API

一款小型付费 API，供编码 Agent 在将仓库文本发送给大模型之前，进行确定性的上下文预检。它会统计 GPT 系列模型的 token 数，应用可选的模型感知预算，并对可能的凭据进行脱敏。

它还提供托管数据实验。bounty-radar 会规范化实时 Agent 工作列表，并保留规范托管信号与普通平台列表之间的区别。payanagent-health 会生成 PayanAgent 排名目录的最新存活状态快照。base-market-pulse 会整合最新的公开 ETH、DEX 和 Base 网络信号。源代码是公开的，但付费价值在于托管聚合、来源健康状态、有限范围的探测以及带时间戳的结果，买家无需自行运行这些工作。

agent-work-brief 是面向决策的组合服务：它整合规范托管的工作与目录存活状态，排除普通的无资金支持列表，并将需要先投入资金的机会分类，以免 Agent 花时间评估。

源代码公开，为什么还要付费？

我们有意允许自行托管。付费的便利之处在于持续维护的运行服务：轮询不断变化的上游、规范化响应、检测局部故障、限制工作范围，并通过就绪端点提供带时间戳的结果。买家可以复刻代码，但之后就需要自行负责部署、监控、速率限制处理、架构变更和修复。我们不宣称拥有排他性；服务必须通过保持数据新鲜和可靠运行来赢得信任。

本地开发

npm install
npm test
X402_FACILITATOR=https://facilitator.openx402.ai npm start

服务默认监听 http://localhost:8787。GET /health 免费。调用方提供有效的 Base USDC 付款之前，POST /v1/context-preflight 会返回 x402 402 Payment Required 响应。

在 Base 主网的生产环境中，请使用在其 /supported 端点声明 x402Version: 2、scheme: exact 和 network: eip155:8453 的 Facilitator；维护中的部署使用 https://facilitator.openx402.ai。公开的 https://x402.org/facilitator 端点适用于 Base Sepolia 测试，不适用于此主网收款配置。更改部署之前，请务必核实 Facilitator 当前是否受支持。

API 示例

curl -X POST http://localhost:8787/v1/context-preflight \
  -H 'content-type: application/json' \
  -d '{"text":"const token = \"sk-example\";","model":"claude-sonnet","token_budget":1000}'

默认价格为每个请求 $0.005。设置 PAY_TO 可更改公开收款地址；设置 X402_FACILITATOR 可选择兼容的 Facilitator；设置 PUBLIC_HOSTS 可提供以逗号分隔的 Worker／自定义主机名允许列表，用于 x402 资源 URL。请勿将私钥或 Facilitator 凭据放入此仓库；服务接收付款不需要签名密钥。

托管赏金雷达

POST /v1/bounty-radar 通过 x402 收费 $0.01。发送筛选条件，例如：

{"include_unverified":false,"min_reward_usd":0,"limit":20}

响应包含来源健康状态、截止时间、认领保证金、外部支出要求和 payment_evidence 字段。只有明确标记为规范且已托管的列表才会标为有资金支持；其他列表只有在请求时才会显示，并标为未经验证。

PayanAgent 目录健康状态

POST /v1/payanagent-health 通过 x402 收费 $0.01。它接受 1 到 25 之间的可选 limit，并仅使用只读 HEAD 请求检查公开排名目录（必要时回退到 OPTIONS）。HTTP 402 表示收到了实时付款门控响应；服务绝不会发送付款标头或调用付费路由。响应包含每项服务的状态、HTTP 代码、延迟、汇总计数和 generated_at。

基础市场脉搏

POST /v1/base-market-pulse 通过 x402 收费 $0.01，并接受 {}。该路由也提供等效的 GET 方式，供 Agent 目录和简单的 HTTP 客户端使用。它会读取 Coinbase 的公开 ETH/USD 现货端点、DEX Screener 的公开 Base WETH/USDC 交易对数据，以及公开的 Base JSON-RPC 方法，以获取当前区块和 Gas 价格。它会返回各来源的运行状态、带时间戳的数值，并在某个来源不可用时提供部分结果。此数据仅供参考，不会进行交易或提交交易。

POST /v1/agent-work-brief 收费 $0.03，并接受可选的 min_reward_usd、limit 和 health_limit 筛选条件。它旨在帮助 Agent 判断当前工作是否值得跟进；不会提出主张、付款或发起下游付费调用。

GET /.well-known/x402（也可通过 /.well-known/x402.json 访问）会发布机器可读的服务清单、路由、价格、网络、资产和收款地址。该清单根据请求主机生成，因此即使零成本开发隧道发生轮换，也能保持正确。

启用可选的 agent-tools hub 网关后，它会将已结算的请求转发到 /hub/v1/base-market-pulse，并附带 hub 签发的 X-Hub-Secret。不提供该密钥时，此上游路径会返回 404，并且与直接 x402 路由相互独立。

MCP 集成

该仓库还包含一个本地 stdio MCP 服务，供 Cline 和其他 MCP 客户端使用：

npm run start:mcp

preflight_context 工具提供免费的本地层级，最多支持 12,000 个字符。输入更长时，会返回付费 HTTP 端点及其 x402 价格。启动 MCP 服务时，请将 PAID_ENDPOINT 设为当前已部署的端点。复制粘贴客户端配置请参阅 llms-install.md。

同一服务还以托管的无状态 Streamable HTTP MCP 端点形式提供，地址为 https://agent-context-api-proxy.agent-context-proxy.workers.dev/mcp，相关说明见 server.json。它已发布到 官方 MCP Registry，供客户端和下游目录发现。此托管路由面向能够发现远程 MCP 服务的客户端；本地运行仍可用于自托管和离线预检工作。用于目录索引和所有权识别的 GitHub 维护者信息见 glama.json。

设计说明

• server.js 包含 Express 应用、x402 付款中间件、发现元数据和路由配置。
• mcp-core.js 定义共享的 MCP 工具接口；mcp-server.js 通过 stdio 运行该接口，/mcp 则通过 Streamable HTTP 运行。
• analysis.js 包含确定性上下文分析；bounty-radar.js 包含来源规范化和证据策略。
• payanagent-health.js 包含有界的只读目录采集器和探测逻辑。
• market-pulse.js 包含有界的公开市场/RPC 采集器，以及部分来源的运行状态输出。
• test/server.test.js 涵盖脱敏、预算、健康状态路由以及已注资/未注资标记；test/payanagent-health.test.js 涵盖健康状态分类和无付款探测约定。
• API 刻意不会将提交的文本发送给第三方；处理过程在本地进行。
• 这是一项实验。必须根据结算记录验证收入，不能根据 402 响应、请求或目录列表推断收入。