x402 API

StockKit 的每一个端点都同时以按次付费的形式提供在 /v1/x402/* 下，由 x402 进行付费门控：无需 API 密钥，无需订阅，无需注册。每次调用支付几美分的稳定币，就能在同一个请求中拿到响应。这一层让 Robinhood Chain 和 Base 上的智能体、钱包和市场可以直接购买 StockKit 数据，不需要签合同，也不需要开账户。

整个 API 的机器可读契约，包括每个付费路由的价格、输入和输出结构，发布在 api.stockkit.dev/openapi.json。 x402scan 这类智能体注册表抓取的正是这份文档。

端点

端点	价格
`GET /v1/x402/research/:symbol`	$0.01
`GET /v1/x402/quote`	$0.01
`GET /v1/x402/portfolio/:address`	$0.01
`GET /v1/x402/history/:symbol`	$0.01
`POST /v1/x402/trade/build`	$0.02

参数和响应结构与 Research、Execution、 Portfolio 和 Market 页面中记录的免费端点完全相同。 /v1/x402/* 路径只是在同样的处理逻辑外面包了一层付费；免费的 /v1/* 路由在测试期间保持开放。

结算网络

一个请求可以在两个网络中任选其一付费。402 挑战始终同时列出两者：

网络	资产	Facilitator
Robinhood Chain（`eip155:4663`）	USDG	facilitator.meshgateway.co
Base（`eip155:8453`）	USDC	facilitator.payai.network

StockKit 从不持有中继私钥，也不直接接触任何一条链。每个 facilitator 负责验证签名后的付款并广播转账；StockKit 只在返回响应之前检查结算结果。

付款流程

StockKit 通过标准 HTTP 传输层使用 x402 v2。不带付款调用付费端点，会得到一个 402 响应，其 PAYMENT-REQUIRED 头携带 base64 编码的挑战，其中包含两种可接受的付款选项。同一个对象也会作为 JSON 响应体重复一遍，方便人工阅读：

curl -i https://api.stockkit.dev/v1/x402/research/NVDA

{
  "x402Version": 2,
  "error": "Payment is required (StockKit research).",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:4663",
      "amount": "10000",
      "asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
      "payTo": "0x0E74F4793a144b0eB9c15CDB959B1D8bcAA5c9Cf",
      "maxTimeoutSeconds": 300,
      "extra": { "assetTransferMethod": "permit2", "spender": "0x402085c248EeA27D92E8b30b2C58ed07f9E20001" }
    },
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x0E74F4793a144b0eB9c15CDB959B1D8bcAA5c9Cf",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "resource": {
    "url": "https://api.stockkit.dev/v1/x402/research/NVDA",
    "description": "Company fundamentals from SEC EDGAR ...",
    "mimeType": "application/json"
  }
}

接受查询参数或 JSON 请求体的路由还会包含一个 extensions.bazaar 块，描述期望的输入，与 OpenAPI 文档发布的结构一致。

用兼容 x402 的钱包或客户端为 accepts 中的某一项签署付款，然后把签名后的载荷放在 PAYMENT-SIGNATURE 头中重试同一个请求。成功的响应会在 PAYMENT-RESPONSE 头中携带结算回执（交易哈希、网络、付款人），正常的 JSON 响应体照常返回。付款无效或失败时，会再次返回 402，并附上来自 facilitator 的拒绝原因，而不是一个笼统的错误。

仍然使用 v1 头名称的旧客户端也可以正常工作：放在 X-PAYMENT 中的付款会被接受，回执也会同时写入 X-PAYMENT-RESPONSE。

付费中间件在任何参数或请求体校验之前运行，因此未经认证的探测请求总能到达 402 挑战。发现服务的爬虫在对照线上端点核验列表时，依赖的正是这一点。

任何 x402 v2 客户端都可以使用，例如面向 Base 的 PayAI 智能体工具，或集成了 meshgateway 的 Robinhood Chain 钱包。

为什么按次付费

无需账户，无需密钥。 任何能签署付款的钱包都可以立即调用 API。
可被智能体发现。 /openapi.json 文档用 x-payment-info 和记录在案的 402 响应标记每一个付费路由，这正是 x402scan 这类注册表用来收录 API 的契约。你可以自己审计线上源站：
终端窗口
```
npx -y @agentcash/discovery@latest discover https://api.stockkit.dev
```
与免费层相同的数据。 按次付费是给那些希望在协议内付费、而不是使用开放测试端点的调用方准备的，不是一个单独的、缩水的数据集。