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

/treasury-curve

/bonds

/bonds/:id

/bonds/:id/analytics

/bonds/:id/cashflows

/bonds/:id/history

/calculate

/riesgo-pais

/riesgo-pais/history

/calculate/batch

Identifier formats: ISIN (

US040114HS26

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 }

See

references/signer-setup.md

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

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)