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
- Call any x402 endpoint without auth → server returns
402 with PAYMENT-REQUIRED header
- Decode the header (base64 JSON) to get payment requirements (amount, asset, network, payTo)
- Sign an EIP-3009
transferWithAuthorization via the x402 client library
- Retry the request with the signed payment in the
PAYMENT-SIGNATURE header (v2), with X-PAYMENT as legacy fallback
- 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.
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 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)