DEV Community: codaMW

Designing a Highly Resilient, Non-Panicking Bitcoin Core RPC Client in Rust

codaMW — Wed, 15 Jul 2026 10:28:46 +0000

Bitcoin operates on a decentralized peer-to-peer (P2P) network where nodes propagate transactions and blocks using a gossip protocol over TCP. While this P2P layer handles the core consensus mechanics, serializing inv, tx, and block messages, it is intentionally low-level and computationally intensive. Directly managing these messages requires deep protocol expertise and exhaustive state management.

To bridge the gap between low-level network operations and high-level application logic, Bitcoin Core exposes a JSON-RPC 2.0 interface over HTTP. This REST-like interface allows developers to query the node's internal state, manage wallets, issue administrative commands, and introspect the blockchain, all without re-implementing the networking stack.

When developing developer tooling or infrastructure components for Bitcoin, interacting with a local Bitcoin Core node is a standard requirement. While high-level library wrappers abstract away HTTP details, building a custom JSON-RPC transport layer using low-level HTTP client libraries is often the optimal choice for fine-grained control, custom deserialization behavior, and minimizing dependency bloat.

This article details how to design and build a highly modular, asynchronous, non-panicking Bitcoin Core CLI tool in Rust using reqwest, serde_json, and clap. By the end of this guide, you will have a robust foundation for interacting with Bitcoin Core programmatically.

Architecture Overview
Prerequisites
Defining a Centralized Error Domain
Assembling the Configuration Layer
Implementing the Custom JSON-RPC Client
Structuring Command Routing with Clap
Handling Unpredictable API Payloads
Parsing Arbitrary Dynamic Commands
Putting It All Together
Key Takeaways

Architecture Overview

To ensure the codebase scales cleanly and remains maintainable, we avoid placing all execution logic in a single file. The application is divided into five modular, decoupled domains:

src/
├── main.rs        # Application bootstrap, configuration assembly, and execution router
├── config.rs      # Environment validation and loading
├── error.rs       # Domain-specific error taxonomy
├── rpc.rs         # Core HTTP transport engine and authorization encoder
├── cli.rs         # CLI command mapping and parser
└── commands/      # Target RPC handlers (blockchain, wallet, dynamic RPC)

Why this matters: By decoupling transportation (rpc.rs) from command presentation (commands/), we ensure that updating an endpoint's return type does not break the networking engine. This separation of concerns aligns with the Single Responsibility Principle and makes unit testing significantly easier.

Prerequisites

Before diving into the implementation, ensure you have:

Rust (latest stable) installed via rustup.
Cargo for dependency management.
A local Bitcoin Core node running on Regtest (i recommend using Polar for easy setup).
The following Rust crates added to your Cargo.toml:

[dependencies]
clap = { version = "4.0", features = ["derive"] }
reqwest = { version = "0.11", features = ["json"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tokio = { version = "1.0", features = ["full"] }
thiserror = "1.0"
base64 = "0.21"

Defining a Centralized, Non-Panicking Error Domain

A production command-line application must never crash or panic on unexpected runtime errors (e.g., network drops, bad block hashes, or incorrect passwords). We use the thiserror crate to declare a strongly-typed error hierarchy in src/error.rs:

// src/error.rs
use thiserror::Error;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("Environment configuration error: {0}")]
    Config(String),

    #[error("Network connection failed: {0}")]
    Network(#[from] reqwest::Error),

    #[error("RPC error returned from node: (Code {code}) {message}")]
    BitcoinRpc { code: i32, message: String },

    #[error("Serialization / Deserialization error: {0}")]
    Serialization(#[from] serde_json::Error),
}

Key design decisions:

#[from] macros: Automatically map internal reqwest::Error and serde_json::Error events directly into our domain-specific enum, eliminating nested match blocks.
Friendly string outputs: The #[error("...")] macro formats debugging messages directly, allowing our CLI binary to print clean error logs to stderr and terminate gracefully.
Explicit RPC errors: We distinguish between network faults and business-logic RPC errors (e.g., "Method not found") by capturing the Bitcoin Core error code.

Assembling the Configuration Layer

To prevent secret leakage, access credentials must never be committed to source control. In src/config.rs, we parse environment variables and validate their existence:

// src/config.rs
use std::env;
use crate::error::AppError;

pub struct Config {
    pub rpc_url: String,
    pub rpc_user: String,
    pub rpc_pass: String,
}

impl Config {
    pub fn from_env() -> Result<Self, AppError> {
        let rpc_url = env::var("BTC_RPC_URL")
            .unwrap_or_else(|_| "http://127.0.0.1:18443".to_string());

        let rpc_user = env::var("BTC_RPC_USER")
            .map_err(|_| AppError::Config("BTC_RPC_USER env var is missing".into()))?;

        let rpc_pass = env::var("BTC_RPC_PASS")
            .map_err(|_| AppError::Config("BTC_RPC_PASS env var is missing".into()))?;

        Ok(Self { rpc_url, rpc_user, rpc_pass })
    }
}

Why this approach: Using Result instead of panicking via .unwrap() allows the caller (main.rs) to format missing variable errors cleanly before exit, providing actionable feedback to the user.

Implementing the Custom JSON-RPC Client

The Bitcoin Core RPC protocol communicates using HTTP POST requests containing a JSON-RPC 2.0 payload, authenticated via HTTP Basic Authentication.

We write our low-level network engine in src/rpc.rs. The code manually builds the authentication header by formatting user credentials as "username:password" and encoding that string into Base64:

// src/rpc.rs

use crate::error::AppError;
use crate::config::Config;
use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION};
use serde::{Deserialize, Serialize};
use serde_json::Value;

#[derive(Serialize)]
struct RpcRequest {
    jsonrpc: &'static str,
    id: &'static str,
    method: String,
    params: Vec<Value>,
}

#[derive(Deserialize)]
struct RpcResponse {
    result: Option<Value>,
    error: Option<RpcErrorPayload>,
}

#[derive(Deserialize, Debug)]
struct RpcErrorPayload {
    code: i32,
    message: String,
}

pub struct BitcoinRpcClient {
    client: reqwest::Client,
    url: String,
}

impl BitcoinRpcClient {
    pub fn new(config: &Config) -> Result<Self, AppError> {
        // Build the basic authorization header manually
        let auth_str = format!("{}:{}", config.rpc_user, config.rpc_pass);
        let b64_auth = base64::Engine::encode(&base64::engine::general_purpose::STANDARD, auth_str);

        let mut headers = HeaderMap::new();
        let mut auth_header = HeaderValue::from_str(&format!("Basic {}", b64_auth))
            .map_err(|_| AppError::Config("Invalid character in RPC credentials".into()))?;
        auth_header.set_sensitive(true);
        headers.insert(AUTHORIZATION, auth_header);

        let client = reqwest::Client::builder()
            .default_headers(headers)
            .build()?;

        Ok(Self { client, url: config.rpc_url.clone() })
    }

    /// Sends a type-safe or dynamic request to the Bitcoin node
    pub async fn call(&self, method: &str, params: Vec<Value>) -> Result<Value, AppError> {
        let payload = RpcRequest {
            jsonrpc: "2.0",
            id: "btc-cli",
            method: method.to_string(),
            params,
        };

        let res = self.client.post(&self.url)
            .json(&payload)
            .send()
            .await?;

        // Catch non-200 authentication/network errors before parsing JSON
        if res.status() == reqwest::StatusCode::UNAUTHORIZED {
            return Err(AppError::BitcoinRpc {
                code: -401,
                message: "Unauthorized: Invalid RPC Username or Password".to_string(),
            });
        }

        let rpc_response: RpcResponse = res.json().await?;

        if let Some(err) = rpc_response.error {
            return Err(AppError::BitcoinRpc {
                code: err.code,
                message: err.message,
            });
        }

        Ok(rpc_response.result.unwrap_or(Value::Null))
    }
}

Key implementation details:

set_sensitive(true): Prevents the Basic Authentication header from leaking into logs during verbose network debugging.
serde_json::Value wrapper: Using dynamic values for input parameters and raw results enables this single client class to process typed calls (e.g., structured blockchain metrics) as well as arbitrary dynamic method calls.

Structuring Command Routing with Clap

We implement our command mappings inside src/cli.rs. By deriving Clone and Subcommand, clap builds a robust parsing engine directly from our enum:

// src/cli.rs

  // src/cli.rs
use clap::{Parser, Subcommand};

#[derive(Parser, Debug)]
#[command(name = "btc-cli")]
#[command(about = "Command-Line Bitcoin node dashboard", long_about = None)]
pub struct Cli {
    #[arg(short, long, global = true, help = "Override RPC Node URL")]
    pub url: Option<String>,

    #[arg(short, long, global = true, help = "Optional Wallet Name")]
    pub wallet: Option<String>,

    #[command(subcommand)] // This specifies that `command` contains the subcommand enums
    pub command: Commands,
}

#[derive(Subcommand, Debug, Clone)] // Derived Subcommand and Clone here!
pub enum Commands {
    #[command(about = "Get basic blockchain metrics")]
    BlockchainInfo,

    #[command(about = "Get loaded wallet stats")]
    WalletInfo,

    #[command(about = "Display wallet balance in BTC")]
    Balance,

    #[command(about = "Generate a new wallet receiving address")]
    NewAddress,

    #[command(about = "Run arbitrary RPC methods dynamically")]
    Rpc {
        method: String,
        params: Vec<String>,
    },
}

Handling Unpredictable API Payloads

One common pain point in Bitcoin Core integration is the subtle structural variance in RPC outputs. For example, calling getwalletinfo on an unnamed or empty wallet on Regtest can return a response where the walletname field is empty and fields like balance or txcount are completely absent.

To prevent deserialization failures, we wrap optional primitive fields in Option<T> within src/commands/wallet.rs:

// src/commands/wallet.rs

use crate::rpc::BitcoinRpcClient;
use crate::error::AppError;
use serde::Deserialize;

#[derive(Deserialize, Debug)]
struct WalletInfoResult {
    walletname: String,
    // Using Option keeps the parser from failing if the node hides these fields
    balance: Option<f64>,
    unconfirmed_balance: Option<f64>,
    txcount: Option<u64>,
}

pub async fn handle_wallet_info(client: &BitcoinRpcClient) -> Result<(), AppError> {
    let raw_val = client.call("getwalletinfo", vec![]).await?;
    let info: WalletInfoResult = serde_json::from_value(raw_val)?;

    println!("=========================================");
    println!("             WALLET INFORMATION          ");
    println!("=========================================");
    println!("Wallet Name:          {}", info.walletname);
    println!("Confirmed Balance:    {} BTC", info.balance.unwrap_or(0.0));
    println!("Unconfirmed Balance:  {} BTC", info.unconfirmed_balance.unwrap_or(0.0));
    println!("Transaction Count:    {}", info.txcount.unwrap_or(0));
    println!("=========================================");

    Ok(())
}

pub async fn handle_balance(client: &BitcoinRpcClient) -> Result<(), AppError> {
    let raw_val = client.call("getbalance", vec![]).await?;
    let balance: f64 = serde_json::from_value(raw_val)?;
    println!("Wallet Balance: {} BTC", balance);
    Ok(())
}

pub async fn handle_new_address(client: &BitcoinRpcClient) -> Result<(), AppError> {
    let raw_val = client.call("getnewaddress", vec![]).await?;
    let address: String = serde_json::from_value(raw_val)?;
    println!("Generated Address: {}", address);
    Ok(())
}

pub async fn handle_generic_rpc(
    client: &BitcoinRpcClient,
    method: String,
    raw_params: Vec<String>,
) -> Result<(), AppError> {
    let parsed_params: Vec<serde_json::Value> = raw_params
        .into_iter()
        .map(|p| {
            serde_json::from_str(&p)
                .unwrap_or_else(|_| serde_json::Value::String(p))
        })
        .collect();

    let result = client.call(&method, parsed_params).await?;
    println!("{}", serde_json::to_string_pretty(&result)?);
    Ok(())
}

Best practice: Always prefer Option<T> over T when dealing with third-party JSON APIs that are not strictly versioned. This defensive approach ensures the application remains resilient to upstream changes.

Parsing Arbitrary Dynamic Commands (The Generic Runner)

To support raw, dynamic requests (e.g., executing getblockhash 100), we must parse raw string inputs into their appropriate JSON-RPC types at runtime. We achieve this by mapping terminal parameters through a JSON string parser:

// src/commands/mod.rs
pub mod blockchain;
pub mod wallet;

How this works:

If a user executes rpc getblockhash 100, serde_json::from_str("100") evaluates successfully and passes the parameter as the integer 100 rather than the raw string "100". This satisfies Bitcoin Core's strict typing constraints on raw parameters.
If a user executes rpc getblock "abc", the parser fails on the integer conversion and defaults to a JSON String, which is the correct type for the block hash argument.

Putting It All Together

The application orchestrator (src/main.rs) initializes configurations, handles custom arguments, routes subcommand execution, and prints user-friendly error logs:

// src/main.rs
mod config;
mod error;
mod rpc;
mod cli;
mod commands;

use clap::Parser;
use config::Config;
use rpc::BitcoinRpcClient;
use cli::{Cli, Commands};

#[tokio::main]
async fn main() {
    // 1. Process local system configuration
    let mut config = match Config::from_env() {
        Ok(cfg) => cfg,
        Err(e) => {
            eprintln!("Configuration Error: {}", e);
            std::process::exit(1);
        }
    };

    // 2. Parse arguments passed from Terminal
    let args = Cli::parse();

    // Support override URL from command line flags
    if let Some(custom_url) = args.url {
        config.rpc_url = custom_url;
    }

    // Support connecting to specific sub-wallets 
    // Bitcoin Core isolates multi-wallet RPC interfaces at "http://node-ip:port/wallet/<wallet-name>"
    if let Some(wallet_name) = args.wallet {
        config.rpc_url = format!("{}/wallet/{}", config.rpc_url.trim_end_matches('/'), wallet_name);
    }

    // 3. Initialize RPC Engine
    let rpc_client = match BitcoinRpcClient::new(&config) {
        Ok(c) => c,
        Err(e) => {
            eprintln!("Client Initialization Error: {}", e);
            std::process::exit(1);
        }
    };

    // 4. Command Router Execution
    let exec_result = match args.command {
        Commands::BlockchainInfo => commands::blockchain::handle_info(&rpc_client).await,
        Commands::WalletInfo => commands::wallet::handle_wallet_info(&rpc_client).await,
        Commands::Balance => commands::wallet::handle_balance(&rpc_client).await,
        Commands::NewAddress => commands::wallet::handle_new_address(&rpc_client).await,
        Commands::Rpc { method, params } => {
            commands::wallet::handle_generic_rpc(&rpc_client, method, params).await
        }
    };

    // 5. Graceful Error printer
    if let Err(e) = exec_result {
        eprintln!("Operational Error: {}", e);
        std::process::exit(1);
    }
}

Critical design consideration: By constructing the rpc_client after overriding the URL with the wallet name, we support Bitcoin Core's multi-wallet feature natively. This architecture eliminates the need to re-implement wallet switching logic at the command level.

Key Takeaways

Building custom integration layers for Bitcoin Core can introduce vulnerabilities and performance issues if not executed carefully. By structuring your client according to these patterns, you establish a firm foundation:

Zero-Unwrap Execution: All critical systems use Rust's Result patterns to handle configurations and networking errors cleanly. The application never panics on user input or network failures.
Defensive Serialization: Standardizing on dynamic JSON mappings (serde_json::Value) alongside structured configurations allows you to support both strict types and dynamic endpoints without sacrificing type safety.
Security Separation: Keeping credentials isolated to shell environment configurations protects private access keys from slipping into version control.
Modular Extensibility: The clear separation between the HTTP transport layer and command logic means that adding a new RPC command requires only a new variant in the Commands enum and a corresponding handler, leaving the networking engine untouched.

This architectural pattern is not limited to Bitcoin. It can be replicated for any HTTP-based JSON-RPC service, providing a robust, testable, and maintainable foundation for your infrastructure tooling.

Building an AI Weather Agent with PydanticAI and Tool Injection

codaMW — Sat, 11 Jul 2026 00:04:55 +0000

Large Language Models (LLMs) excel at processing natural language but cannot access real-time data natively. To resolve this limitation, developers build autonomous AI agents. An AI agent extends an LLM's capabilities by executing external tools, accessing live APIs, and validating unstructured data into predictable data models.

This article details how to build a production-ready AI weather agent using PydanticAI, validate external API data with Pydantic, and handle structured dependencies. This project serves as a foundational step toward constructing specialized, autonomous agents capable of managing automated Bitcoin mining nodes, validating Lightning Network lightning transactions, and orchestrating algorithmic payments.

Architectural Overview

The application architecture separates prompt evaluation from the execution of the external business logic.

User Query 
  │
  ▼
PydanticAI Agent 
  │
  ▼
Weather Tool (@agent.tool) 
  │
  ▼
Weather Service (WeatherAgent Dependency)
  │
  ▼
Open-Meteo Geocoding & Forecast APIs
  │
  ▼
Pydantic Data Validation (Coordinates & CurrentWeather Models)
  │
  ▼
Final Structured AI Response

Instead of allowing the LLM to access the network directly, the agent acts as an orchestrator. It extracts natural language parameters (such as a city name), passes them to a registered validation tool, executes network requests via httpx, and maps the response payload back to a strict schema.

Core Concepts Implemented

To transition from a simple text chatbot to an analytical agent, this project implements several core engineering patterns:

Dependency Injection via RunContext: Instead of hardcoding API clients inside global functions, the system injects data services dynamically into the execution context using PydanticAI's deps_type.
Strict Type Safety: Data objects entering and leaving the agent use Pydantic BaseModel classes to prevent data corruption and unexpected structural types.
Deterministic Tool Execution: The system uses the @agent.tool decorator to automatically expose Python functions to the underlying LLM via generated JSON schemas.

Implementation Code

The implementation is contained within a single executable Python module (main.py). The script uses the Open-Meteo Geocoding API to resolve alphanumeric location queries into geographic coordinates before querying weather metrics.


import httpx
from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

class Coordinates(BaseModel):
    """Data model to validate geographic coordinates."""
    latitude: float
    longitude: float


class CurrentWeather(BaseModel):
    """Data model to validate structured weather conditions."""
    city: str
    temperature: float  # Corrected typo from original 'tempereture'
    description: str


class WeatherAgent:
    """Service class handling external API interaction and data retrieval."""

    def get_coordinates(self, city: str) -> Coordinates:
        try:
            response = httpx.get(
                "https://geocoding-api.open-meteo.com/v1/search",
                params={"name": city, "count": 1},
                timeout=5.0
            )
            response.raise_for_status()
            data = response.json()
            results = data.get("results")

            if not results:
                raise ValueError(f"City '{city}' was not found.")

            result = results[0]
            return Coordinates(
                latitude=result["latitude"], 
                longitude=result["longitude"]
            )

        except httpx.ConnectError:
            print("[ERROR] Connection failure to Geocoding server.")
            raise
        except httpx.TimeoutException:
            print("[ERROR] Geocoding request timed out.")
            raise
        except httpx.HTTPStatusError as e:
            print(f"[ERROR] Server returned HTTP {e.response.status_code}")
            raise

    def describe_weather(self, code: int) -> str:
        """Maps World Meteorological Organization (WMO) codes to human-readable strings."""
        weather_codes = {
            0: "Clear sky",
            1: "Mainly clear",
            2: "Partly cloudy",
            3: "Overcast",
        }
        return weather_codes.get(code, "Unknown")

    def get_weather(self, city: str) -> CurrentWeather:
        # Step 1: Resolve city name to GPS coordinates
        coordinates = self.get_coordinates(city)

        # Step 2: Query the forecast API with resolved positions
        response = httpx.get(
            "https://api.open-meteo.com/v1/forecast",
            params={
                "latitude": coordinates.latitude,
                "longitude": coordinates.longitude,
                "current": "temperature_2m,weather_code",
            },
            timeout=5.0
        )
        response.raise_for_status()
        data = response.json()
        current = data["current"]

        return CurrentWeather(
            city=city,
            temperature=current["temperature_2m"],
            description=self.describe_weather(current["weather_code"]),
        )


# Instantiate the agent with strict instructions and explicit type dependencies
agent = Agent(
    "groq:llama-3.3-70b-versatile",
    instructions=(
        "You are a precise, helpful, and professional Weather Assistant. "
        "Your primary goal is to provide accurate weather forecasts and current conditions "
        "by utilizing available weather tools and structuring the data flawlessly.\n\n"
        "### Core Responsibilities:\n"
        "1. **Location Resolution:** Extract the location (city, country, region) from the user's query.\n"
        "2. **Tool Execution:** Use the provided weather tools to fetch real-time data. Never make up weather data.\n"
        "3. **Data Mapping:** Carefully parse the tool outputs to fulfill the schema requirements.\n\n"
        "### Formatting & Tone Guidelines:\n"
        "- **Units:** Default to the metric system (Celsius, km/h, mm) unless the user requests imperial units.\n"
        "- **Clarity:** Summarize complex meteorological data into simple, digestible insights.\n\n"
        "### Behavioral Constraints:\n"
        "- If a location cannot be found, explain the limitation gracefully.\n"
        "- Do not hallucinate current dates or times; rely entirely on the tool's timestamps."
    ),
    deps_type=WeatherAgent,
)


@agent.tool
def current_weather(ctx: RunContext[WeatherAgent], city: str) -> CurrentWeather:
    """Fetches the current weather for a given city.

    Args:
        ctx: The runtime context containing the injected WeatherAgent dependency.
        city: The name of the city to lookup.
    """
    print(f"[TOOL] Fetching weather for {city}")
    return ctx.deps.get_weather(city)


if __name__ == "__main__":
    history = None
    print("AI Weather Agent Initialized. Type 'exit' to quit.")

    while True:
        prompt = input("you> ")

        if prompt.lower() in {"exit", "quit"}:
            break
        if not prompt.strip():
            continue

        try:
            # Instantiate service dependency per conversation frame
            weather_service = WeatherAgent()
            result = agent.run_sync(
                prompt, 
                message_history=history, 
                deps=weather_service
            )
            print(f"bot> {result.output}")
            history = result.all_messages()

        except Exception as e:
            print(f"[RUNTIME ERROR] {type(e).__name__}: {e}")

Technical Insights and Key Takeaways

Building this system highlights the fundamental difference between standard generative text generation and actual agentic engineering:

State Isolation via Dependency Injection: Passing the WeatherAgent service instance through the deps argument ensures that tools remain stateless and isolated. This allows for concurrent execution threads without shared-state mutation errors.
Deterministic Network Error Defenses: External systems fail frequently. Wrapping httpx logic with deliberate catch blocks for ConnectError, TimeoutException, and HTTPStatusError ensures that the Python app handles infrastructure hiccups cleanly before they crash the runtime stack.
Structured Schemas Keep LLMs in Check: LLMs naturally output variable text formats. Forcing inputs and outputs through Pydantic classes forces the model to adhere to fixed data keys, allowing the data to seamlessly pipeline into downstream databases or APIs.

Future Goals: Bitcoin-Based AI Agents

Mastering structured tools and type-safe dependency execution prepares developers for the next level of intelligent systems: Bitcoin-native AI agents.

The long-term roadmap for this architecture shifts from tracking weather metrics to executing autonomous machine-to-machine financial operations on the Bitcoin network:

Automated Bitcoin Mining Management: Agents will poll hash rate metrics, ASIC temperature arrays, and real-time energy prices via REST tools. They can then dynamically toggle mining pools or adjust clock speeds to maximize profitability.
Autonomous Lightning Payments: By injecting Bitcoin node dependencies (e.g., LND, Core Lightning) through the RunContext, agents can autonomously pay for APIs, settle micro-invoices, and rebalance liquidity channels based on demand.
Programmable On-Chain Transactions: Integrating Bitcoin script builders and wallet interfaces will allow multi-agent systems to orchestrate multisig escrow releases, programmatic smart contract settlements, and trustless automated transactions.