bondterminal-x402_skill

Overview

This skill lets you query BondTerminal endpoints using x402 keyless pay-per-call authentication via the btx CLI. It handles automatic 402 -> payment -> retry flows so you can fetch bond lists, details, analytics, cashflows, history, single-bond calculations, and riesgo país data without a Bearer API key. Paid calls cost $0.01 USDC on Base mainnet and settlement metadata is printed on success.

How this skill works

The CLI issues the API request normally and, if the server returns HTTP 402 with PAYMENT-REQUIRED, it signs an x402 payment using the EVM private key and USDC on Base, then retries the request. It requires an environment private key (X402_PRIVATE_KEY or EVM_PRIVATE_KEY) and on-chain funds (USDC for the payment plus some Base ETH for gas). Certain endpoints remain Bearer-only (for example calculate/batch) and will return 403 or 401 accordingly.

When to use it

• Fetch BondTerminal bond lists or single-bond details without a Bearer API key
• Run bond analytics, yields, or market fields when you want on-demand pay-per-call data
• Retrieve bond cashflows and history for ISINs or tickers like AL30, GD30, US040114HS26
• Query riesgo país and riesgo-history endpoints to get country risk metrics
• Use CLI machine-readable output with --json for scripting and automation

Best practices

• Ensure X402_PRIVATE_KEY or EVM_PRIVATE_KEY is set and valid (32-byte hex with 0x prefix)
• Fund the signing wallet with USDC on Base and a small ETH balance for gas before making paid calls
• Use --json for reproducible, machine-parsable output in scripts
• Expect automatic retry on 402; monitor stderr for settlement metadata (payer, transaction, network)
• Avoid using this skill for endpoints documented as Bearer-only (e.g., POST /calculate/batch)

Example use cases

• Search bonds by ticker: btx bonds --search AL30 to list available bonds and ISINs
• Get bond analytics: btx analytics AL30 --fields market,yields to fetch live yields and market metrics
• Fetch cashflows: btx cashflows GD30D to retrieve coupon and principal schedules
• Lookup riesgo país: btx riesgo and btx riesgo-history --range 1m for country risk time series
• Calculate single-bond price or yield: btx calculate AL30 --price 80 to compute derived metrics