PHP 搭建 JSON-RPC 接口与比特币(BTC)钱包交互开发指南

admin 发布于 2026-02-11 1:21 频道：默认分类阅读：3

比特币（BTC）作为最知名的加密货币，其钱包开发一直是开发者关注的焦点，在 PHP 环境下，如何与比特币核心客户端（或兼容的比特币节点）进行交互，从而实现一个基础的 BTC 钱包功能呢？JSON-RPC（Remote Procedure Call）提供了一种轻量级、高效的解决方案，本文将详细介绍如何利用 PHP 通过 JSON-RPC 协议开发 BTC 钱包的核心功能。

准备工作

在开始之前,你需要确保以下环境已经准备就绪：

比特币核心客户端：在你的服务器或本地机器上安装并运行比特币核心客户端，首次运行会同步整个比特币区块链，这可能需要较长时间和大量磁盘空间，同步完成后，比特币核心会通过 JSON-RPC 接口提供服务。

启用 JSON-RPC 接口：

关闭比特币核心客户端。
找到配置文件 bitcoin.conf（通常位于比特币数据目录下，如 ~/.bitcoin/bitcoin.conf 在 Linux/Mac，或 %APPDATA%\Bitcoin\ 在 Windows）。

在配置文件中添加或修改以下内容：

server=1  # 启用 JSON-RPC 服务器
rpcuser=your_rpc_username  # 设置 RPC 用户名
rpcpassword=your_rpc_password  # 设置 RPC 密码，务必复杂
rpcallowip=127.0.0.1      # 允许连接的 IP 地址，开发时可设为 127.0.0.1，生产环境需谨慎设置
# 可选：指定 RPC 端口，默认为 8332
# rpcport=8332

保存配置文件并重新启动比特币核心客户端。

PHP 环境：确保你的系统已安装 PHP，并且支持 cURL 扩展（用于发送 HTTP 请求），可以通过 php -m | grep curl 检查。

随机配图

g> PHP 与 JSON-RPC 交互基础

比特币核心的 JSON-RPC 接口允许我们发送特定的命令（如获取余额、转账等）并接收 JSON 格式的响应，PHP 中，我们可以使用 cURL 库来发送这些请求。

我们可以封装一个发送 JSON-RPC 请求的函数，提高代码复用性：

<?php
/**
 * 发送 JSON-RPC 请求到比特币核心
 * @param string $method RPC 方法名
 * @param array $params 方法参数
 * @return array|false 响应数据或失败时返回 false
 */
function btcRpcCall($method, $params = []) {
    $rpcUrl = 'http://127.0.0.1:8332/'; // Bitcoin RPC URL
    $rpcUser = 'your_rpc_username';    // bitcoin.conf 中设置的 rpcuser
    $rpcPass = 'your_rpc_password';    // bitcoin.conf 中设置的 rpcpassword
    $data = [
        'jsonrpc' => '2.0',
        'method' => $method,
        'params' => $params,
        'id' => uniqid(), // 请求 ID，用于匹配响应
    ];
    $options = [
        CURLOPT_URL => $rpcUrl,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($data),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'Authorization: Basic ' . base64_encode($rpcUser . ':' . $rpcPass),
        ],
        CURLOPT_TIMEOUT => 10, // 超时时间，秒
    ];
    $ch = curl_init();
    curl_setopt_array($ch, $options);
    $response = curl_exec($ch);
    if (curl_errno($ch)) {
        error_log('cURL Error: ' . curl_error($ch));
        curl_close($ch);
        return false;
    }
    curl_close($ch);
    $result = json_decode($response, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        error_log('JSON Decode Error: ' . json_last_error_msg());
        return false;
    }
    // 检查 RPC 响应中是否有错误
    if (isset($result['error'])) {
        error_log('Bitcoin RPC Error: ' . $result['error']['message'] . ' (' . $result['error']['code'] . ')');
        return false;
    }
    return $result['result'] ?? false;
}
?>

开发 BTC 钱包核心功能

有了 btcRpcCall 函数，我们就可以开始实现 BTC 钱包的一些基本功能了。

获取钱包信息

功能：获取钱包的基本信息，如版本、余额、区块高度等。
RPC 方法：getwalletinfo

PHP 实现：

$walletInfo = btcRpcCall('getwalletinfo');
if ($walletInfo) {
    echo "钱包余额 (BTC): " . $walletInfo['balance'] . "\n";
    echo "钱包余额 (未确认): " . $walletInfo['unconfirmed_balance'] . "\n";
    echo "当前区块高度: " . $walletInfo['block_height'] . "\n";
    print_r($walletInfo);
}

生成新地址
- 功能：在钱包中生成一个新的 BTC 地址，用于接收比特币。
- RPC 方法：getnewaddress [可选参数：标签]
- PHP 实现：
```
$newAddress = btcRpcCall('getnewaddress', ['my_new_address']);
if ($newAddress) {
    echo "新生成的 BTC 地址: " . $newAddress . "\n";
}
```

查询地址余额

功能：查询指定 BTC 地址的余额。
RPC 方法：getaddressinfo [参数：地址]

PHP 实现：

$addressToCheck = '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'; // 示例地址
$addressInfo = btcRpcCall('getaddressinfo', [$addressToCheck]);
if ($addressInfo && isset($addressInfo['balance'])) {
    echo "地址 {$addressToCheck} 的余额: " . $addressInfo['balance'] . " BTC\n";
}

发送比特币

功能：从钱包向指定地址发送比特币。
RPC 方法：sendtoaddress [参数：地址，数量，可选：注释，可选：注释到，可选：替代费率]

PHP 实现：

$toAddress = '1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2'; // 示例接收地址
$amount = 0.01; // 发送数量 (BTC)
$comment = 'PHP 测试转账';
$txid = btcRpcCall('sendtoaddress', [$toAddress, $amount, $comment]);
if ($txid) {
    echo "转账成功！交易ID: " . $txid . "\n";
    // 可以通过交易ID查询交易详情
    // $txDetails = btcRpcCall('gettransaction', [$txid]);
    // print_r($txDetails);
}

查询交易详情

功能：根据交易ID（TXID）查询交易的详细信息。
RPC 方法：gettransaction [参数：交易ID]

PHP 实现：

$txid = '你的交易ID'; // 替换为实际的交易ID
$transactionDetails = btcRpcCall('gettransaction', [$txid]);
if ($transactionDetails) {
    echo "交易详情:\n";
    print_r($transactionDetails);
}

列出交易

功能：列出钱包中的最近交易。
RPC 方法：listtransactions [可选：参数，可选：计数，可选：从]

PHP 实现：

$transactions = btcRpcCall('listtransactions', ['', 10, 0]); // 最近10笔交易
if ($transactions) {
    echo "最近交易列表:\n";
    foreach ($transactions as $tx) {
        echo "ID: " . $tx['txid'] . ", 金额: " . $tx['amount'] . ", 分类: " . $tx['category'] . ", 时间: " . date('Y-m-d H:i:s', $tx['time']) . "\n";
    }
}

安全注意事项

RPC 凭据安全：rpcuser 和 rpcpassword 是极其敏感