bondterminal-x402

用途

BondTerminal x402 用于通过 x402 按次付费方式查询 BondTerminal API，主要服务于阿根廷债券数据相关查询。无需 API key，也无需订阅，每次请求在 Base 主网上支付 0.01 USDC 即可调用付费端点。

主要能力

API 基础地址为 https://bondterminal.com/api/v1，端点如下：

方法	端点	说明	认证
GET	/treasury-curve	美国国债收益率曲线	免费
GET	/bonds	列出所有债券（60+）	x402
GET	/bonds/:id	按 ISIN 或本地代码查询债券详情	x402
GET	/bonds/:id/analytics	价格、YTM、久期、利差	x402
GET	/bonds/:id/cashflows	现金流计划	x402
GET	/bonds/:id/history	历史价格/收益率/利差	x402
POST	/calculate	根据自定义价格进行债券分析	x402
GET	/riesgo-pais	当前阿根廷国家风险	x402
GET	/riesgo-pais/history	历史 riesgo país 序列	x402
POST	/calculate/batch	批量计算	仅 Bearer

标识符格式：ISIN（如 US040114HS26），或带 D/C 后缀的本地代码（如 AL30D、GD30D）。本地代码需要 D/C 后缀：AL30D（USD）、AL30C（ARS），而非 AL30。

完整文档见 https://bondterminal.com/developers，本技能内的端点参考位于 references/endpoints.md。

x402 工作方式

无认证调用任意 x402 端点 → 服务器返回 402，并带有 PAYMENT-REQUIRED 头。
解码该头（base64 JSON）以获取支付要求（金额、资产、网络、payTo）。
通过 x402 客户端库签名 EIP-3009 transferWithAuthorization。
携带已签名的支付重试请求，使用 PAYMENT-SIGNATURE 头（v2），并以 X-PAYMENT 作为旧版回退。
服务器通过 Coinbase facilitator 验证支付，返回数据及 PAYMENT-RESPONSE 头。

使用方式

1. 安装依赖

npm install @x402/core @x402/evm viem

注意：代码示例使用 ES 模块。请使用 .mjs 文件扩展名，或在 package.json 中添加 "type": "module"。

2. 配置签名器

x402 支付流程需要一个位于 Base 主网且持有 USDC 余额的 EVM 签名器。请按 x402 EVM 文档配置签名器。签名器必须实现 { address, signTypedData } ——任何与 viem 兼容的钱包客户端均可（硬件钱包、KMS、注入式 provider 等）。完整的签名器配置示例见 references/signer-setup.md。

3. 注册 x402 客户端

import { x402Client } from '@x402/core/client';
import { x402HTTPClient } from '@x402/core/http';
import { ExactEvmScheme } from '@x402/evm'; // exact export name

// signer = { address, signTypedData } — see references/signer-setup.md
const scheme = new ExactEvmScheme(signer);
const client = new x402Client();
client.register('eip155:8453', scheme); // Base mainnet
const httpClient = new x402HTTPClient(client);

获取 Bond 数据

async function fetchBT(path) {
  const url = `https://bondterminal.com/api/v1${path}`;
  let res = await fetch(url);

  if (res.status === 402) {
    const paymentRequired = httpClient.getPaymentRequiredResponse(
      (name) => res.headers.get(name),
      await res.json()
    );
    const payload = await httpClient.createPaymentPayload(paymentRequired);

    // Preferred v2 header
    res = await fetch(url, {
      headers: httpClient.encodePaymentSignatureHeader(payload),
    });

    // Legacy fallback for servers still expecting X-PAYMENT
    if (res.status === 402) {
      const encoded = Buffer.from(JSON.stringify(payload)).toString('base64');
      res = await fetch(url, { headers: { 'X-PAYMENT': encoded } });
    }
  }

  if (!res.ok) {
    throw new Error(`BondTerminal request failed (${res.status})`);
  }

  return res.json();
}

// Examples
const bonds = await fetchBT('/bonds');
const analytics = await fetchBT('/bonds/AL30D/analytics');
const riesgo = await fetchBT('/riesgo-pais');

快速测试

验证免费与付费流程：

await fetchBT('/treasury-curve'); // free route (no payment)
await fetchBT('/riesgo-pais');    // paid route (triggers x402 flow)

钱包要求

签名钱包需要：

Base 上的 USDC —— 用于每次请求 0.01 USDC 的支付。
无需 ETH 作为 gas —— x402 使用 EIP-3009（链下签名），不进行链上交易。

适用场景

适用于需要在阿根廷债券数据场景中查询债券列表、单只债券详情与分析指标、现金流与历史走势，以及阿根廷国家风险数据的用户。也可用于验证免费端点与 x402 付费端点两种调用流程。

限制

POST /calculate/batch 需要 Bearer API key 订阅，无法通过 x402 使用。
本地代码必须带 D/C 后缀：AL30D（USD）、AL30C（ARS），不能写作 AL30。
结算在链上进行：每次付费调用会产生可验证的交易哈希。
PAYMENT-RESPONSE 头包含结算元数据（付款方、交易哈希、网络）。