bondterminal-x402

name	bondterminal-x402
description	Query BondTerminal API using x402 keyless payments. No API key needed — pay $0.01 USDC per request on Base mainnet. Use when users ask for Argentine bond data, analytics, cashflows, history, riesgo país, or ISIN/ticker lookups (e.g. AL30, GD30, US040114HS26). Supports automatic 402 → payment → retry.
license	MIT
metadata	{"author":"0juano","version":"2.1.0"}

BondTerminal x402

Query the BondTerminal API with x402 pay-per-call auth. No API key, no subscription — just sign and pay per request.

Cost: $0.01 USDC per request on Base mainnet.

API Endpoints

Base URL: https://bondterminal.com/api/v1

Method	Endpoint	Description	Auth
GET	/treasury-curve	US Treasury yield curve	Free
GET	/bonds	List all bonds (60+)	x402
GET	/bonds/:id	Bond details by ISIN or local ticker	x402
GET	/bonds/:id/analytics	Price, YTM, duration, spreads	x402
GET	/bonds/:id/cashflows	Cashflow schedule	x402
GET	/bonds/:id/history	Historical price/yield/spread	x402
POST	/calculate	Bond analytics from custom price	x402
GET	/riesgo-pais	Current Argentina country risk	x402
GET	/riesgo-pais/history	Historical riesgo país series	x402
POST	/calculate/batch	Batch calculations	Bearer only

Identifier formats: ISIN (US040114HS26), local ticker with D/C suffix (AL30D, GD30D).

Full docs: https://bondterminal.com/developers Endpoint reference in this skill: references/endpoints.md

How x402 Works

1. Call any x402 endpoint without auth → server returns 402 with PAYMENT-REQUIRED header
2. Decode the header (base64 JSON) to get payment requirements (amount, asset, network, payTo)
3. Sign an EIP-3009 transferWithAuthorization via the x402 client library
4. Retry the request with the signed payment in the PAYMENT-SIGNATURE header (v2), with X-PAYMENT as legacy fallback
5. Server verifies payment via Coinbase facilitator, returns data + PAYMENT-RESPONSE header

Setup

1. Install dependencies

npm install @x402/core @x402/evm viem

Note: The code examples use ES modules. Use .mjs file extension or add "type": "module" to your package.json.

2. Configure a signer

The x402 payment flow requires an EVM signer on Base mainnet with USDC balance. Configure your signer following the x402 EVM documentation.

The signer must implement { address, signTypedData } — any viem-compatible wallet client works (hardware wallet, KMS, injected provider, etc).

See references/signer-setup.md for a complete signer configuration example.

3. Register the x402 client

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);

Fetching Bond Data

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 ();
  }

   res.();
}


 bonds =  ();
 analytics =  ();
 riesgo =  ();

Quick Test

Validate both free and paid flows:

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

Wallet Requirements

The signing wallet needs:

• USDC on Base — for the $0.01 payment per request

No ETH for gas is required — x402 uses EIP-3009 (off-chain signature), not on-chain transactions.

Notes

• POST /calculate/batch requires a Bearer API key subscription — not available via x402
• Local tickers require D/C suffix: AL30D (USD), AL30C (ARS) — not AL30
• Settlement is on-chain: each paid call produces a verifiable transaction hash
• The PAYMENT-RESPONSE header contains settlement metadata (payer, tx hash, network)