preciousblock - Bitcoin

Example code for the preciousblock JSON-RPC method. Complete guide on how to use preciousblock JSON-RPC in GetBlock Web3 documentation.

This method treats a block as if it were received before others with the same work, changing tip selection. Its effect is not retained across restarts.

Parameters

Parameter	Type	Required	Description
blockhash	string	Yes	The hash of the block to prioritize

Request

cURL

curl --location --request POST 'https://shared.eu-central-1.getblock.io/<ACCESS-TOKEN>/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "preciousblock",
    "params": ["000000000000000000046b9302e08c16ea186950f42a5498320ddd1bd7ab3428"],
    "id": "getblock.io"
}'

bitcoinjs-lib

example.js

const axios = require('axios');

const response = await axios.post('https://shared.eu-central-1.getblock.io/<ACCESS-TOKEN>/', {
    jsonrpc: '2.0',
    method: 'preciousblock',
    params: ["000000000000000000046b9302e08c16ea186950f42a5498320ddd1bd7ab3428"],
    id: 'getblock.io'
}, {
    headers: { 'Content-Type': 'application/json' }
});

console.log(response.data.result);

Request

example.py

import requests

response = requests.post(
    'https://shared.eu-central-1.getblock.io/<ACCESS-TOKEN>/',
    headers={'Content-Type': 'application/json'},
    json={
        'jsonrpc': '2.0',
        'method': 'preciousblock',
        'params': ["000000000000000000046b9302e08c16ea186950f42a5498320ddd1bd7ab3428"],
        'id': 'getblock.io'
    }
)

print(response.json())

Rust

example.rs

use reqwest::Client;
use serde_json::{json, Value};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();

    let response = client
        .post("https://shared.eu-central-1.getblock.io/<ACCESS-TOKEN>/")
        .header("Content-Type", "application/json")
        .json(&json!({
            "jsonrpc": "2.0",
            "method": "preciousblock",
            "params": ["000000000000000000046b9302e08c16ea186950f42a5498320ddd1bd7ab3428"],
            "id": "getblock.io"
        }))
        .send()
        .await?
        .json::<Value>()
        .await?;

    println!("Result: {}", response["result"]);
    Ok(())
}

Response

{
    "jsonrpc": "2.0",
    "id": "getblock.io",
    "result": null
}

Response Parameters

Parameter	Type	Description
jsonrpc	string	JSON-RPC protocol version ("2.0")
id	string	Request identifier matching the request
result	null	null on success

Use Cases

• Fork Resolution: Prefer one branch among equal-work tips

• Testing: Force tip selection in controlled setups

• Recovery: Guide a node onto the intended chain

• Operations: Resolve a temporary split

Error Handling

Error Code	Message	Description
403	Forbidden	Missing or invalid ACCESS-TOKEN
-5	Not found	The requested block or transaction was not found
-8	Invalid parameter	A parameter is out of range or malformed
-32602	Invalid params	A parameter is missing or has the wrong type