Api

Blockchain API

Blockchain data and fee estimation

The Blockchain API provides access to blockchain data and fee estimation services.

Endpoints


Get Block Number

Get the current block number for a network.

Service: BlockchainServiceMethod: GetBlockNumber

Parameters:

NameTypeRequiredDescription
networkNetworkYESNetwork to query

Response:

FieldTypeDescription
block_numberuint64Current block number/height

Example Request:

TypeScript
const blockNumber = await hydraGrpcClient.getBlockNumber({
  protocol: Protocol.BITCOIN,
  id: '0a03cf40' // Bitcoin Signet
})
Rust
let request = tonic::Request::new(GetBlockNumberRequest {
    network: Some(Network {
        protocol: Protocol::Bitcoin as i32,
        id: "0a03cf40".to_string(),
    }),
});

let response = client.get_block_number(request).await?;
let block_number = response.into_inner().block_number;

Get Block Header

Get block header information for a specific block.

Service: BlockchainServiceMethod: GetBlockHeader

Parameters:

NameTypeRequiredDescription
networkNetworkYESNetwork to query
block_numberuint64NOBlock number (omit for latest)

Response:

FieldTypeDescription
headerBlockHeaderBlock header data

BlockHeader Object:

FieldTypeDescription
hashstringBlock hash
numberuint64Block number
timestampTimestampBlock timestamp
parent_hashstringPrevious block hash

Example Request:

TypeScript
// Get latest block header
const header = await hydraGrpcClient.getBlockHeader({
  protocol: Protocol.EVM,
  id: '11155111'
})

// Get specific block
const header = await hydraGrpcClient.getBlockHeader({
  protocol: Protocol.EVM,
  id: '11155111'
}, 1000000)
Rust
// Latest block
let request = tonic::Request::new(GetBlockHeaderRequest {
    network: Some(Network {
        protocol: Protocol::Evm as i32,
        id: "11155111".to_string(),
    }),
    block_number: None,
});

let response = client.get_block_header(request).await?;
let header = response.into_inner().header;

Get Fee Estimates

Get current fee estimates for transactions on a network.

Service: BlockchainServiceMethod: GetFeeEstimates

Parameters:

NameTypeRequiredDescription
networkNetworkYESNetwork to get fees for

Response:

FieldTypeDescription
lowDecimalStringLow priority fee (sats/vB or gwei)
mediumDecimalStringMedium priority fee
highDecimalStringHigh priority fee

Example Request:

TypeScript
const fees = await hydraGrpcClient.getFeeEstimates({
  protocol: Protocol.BITCOIN,
  id: '0a03cf40'
})

console.log(`Low: ${fees.low} sat/vB`)
console.log(`Medium: ${fees.medium} sat/vB`)
console.log(`High: ${fees.high} sat/vB`)
Rust
let request = tonic::Request::new(GetFeeEstimatesRequest {
    network: Some(Network {
        protocol: Protocol::Bitcoin as i32,
        id: "0a03cf40".to_string(),
    }),
});

let response = client.get_fee_estimates(request).await?;
let fees = response.into_inner();
println!("Low: {} sat/vB", fees.low);
println!("Medium: {} sat/vB", fees.medium);
println!("High: {} sat/vB", fees.high);

Get Token Allowance

Get the current allowance for a spender to use tokens on behalf of an owner (EVM only).

Service: BlockchainServiceMethod: GetTokenAllowance

Parameters:

NameTypeRequiredDescription
networkNetworkYESEVM network
token_addressstringYESToken contract address
ownerstringYESToken owner address
spenderstringYESSpender address

Response:

FieldTypeDescription
allowanceDecimalStringCurrent allowance amount

Example Request:

TypeScript
const allowance = await hydraGrpcClient.getTokenAllowance({
  network: {
    protocol: Protocol.EVM,
    id: '11155111'
  },
  tokenAddress: '0x...', // USDC
  owner: '0x...', // Your address
  spender: '0x...' // Contract address
})

console.log(`Allowance: ${allowance}`)
Rust
let request = tonic::Request::new(GetTokenAllowanceRequest {
    network: Some(Network {
        protocol: Protocol::Evm as i32,
        id: "11155111".to_string(),
    }),
    token_address: "0x...".to_string(),
    owner: "0x...".to_string(),
    spender: "0x...".to_string(),
});

let response = client.get_token_allowance(request).await?;
let allowance = response.into_inner().allowance;

Common Patterns

Monitor block confirmations

Rust
async fn wait_for_confirmations(
    client: &mut BlockchainServiceClient<Channel>,
    network: Network,
    tx_block: u64,
    required_confirmations: u64,
) -> Result<(), Box<dyn std::error::Error>> {
    loop {
        let current_block = client
            .get_block_number(GetBlockNumberRequest {
                network: Some(network.clone()),
            })
            .await?
            .into_inner()
            .block_number;

        let confirmations = current_block.saturating_sub(tx_block);

        if confirmations >= required_confirmations {
            return Ok(());
        }

        tokio::time::sleep(tokio::time::Duration::from_secs(15)).await;
    }
}

Get appropriate fee for urgency

Rust
async fn get_fee_for_urgency(
    client: &mut BlockchainServiceClient<Channel>,
    network: Network,
    urgent: bool,
) -> Result<String, Box<dyn std::error::Error>> {
    let fees = client
        .get_fee_estimates(GetFeeEstimatesRequest {
            network: Some(network),
        })
        .await?
        .into_inner();

    Ok(if urgent { fees.high } else { fees.medium })
}

Error Handling

Error CodeDescriptionSolution
INVALID_ARGUMENTInvalid network or parametersVerify all parameters
NOT_FOUNDBlock not foundCheck block number exists
UNAVAILABLENode temporarily unavailableRetry with backoff

Best Practices

  1. Cache fee estimates - Update every 30-60 seconds, not per transaction
  2. Monitor confirmations - Poll block number for transaction confirmations
  3. Use appropriate fees - Balance cost vs confirmation time
  4. Handle reorgs - Be aware of blockchain reorganizations on short confirmation counts

← Back to API Reference | Next: Orderbook API →


Copyright © 2025