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:
| Name | Type | Required | Description |
|---|---|---|---|
network | Network | YES | Network to query |
Response:
| Field | Type | Description |
|---|---|---|
block_number | uint64 | Current 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:
| Name | Type | Required | Description |
|---|---|---|---|
network | Network | YES | Network to query |
block_number | uint64 | NO | Block number (omit for latest) |
Response:
| Field | Type | Description |
|---|---|---|
header | BlockHeader | Block header data |
BlockHeader Object:
| Field | Type | Description |
|---|---|---|
hash | string | Block hash |
number | uint64 | Block number |
timestamp | Timestamp | Block timestamp |
parent_hash | string | Previous 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:
| Name | Type | Required | Description |
|---|---|---|---|
network | Network | YES | Network to get fees for |
Response:
| Field | Type | Description |
|---|---|---|
low | DecimalString | Low priority fee (sats/vB or gwei) |
medium | DecimalString | Medium priority fee |
high | DecimalString | High 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:
| Name | Type | Required | Description |
|---|---|---|---|
network | Network | YES | EVM network |
token_address | string | YES | Token contract address |
owner | string | YES | Token owner address |
spender | string | YES | Spender address |
Response:
| Field | Type | Description |
|---|---|---|
allowance | DecimalString | Current 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 Code | Description | Solution |
|---|---|---|
INVALID_ARGUMENT | Invalid network or parameters | Verify all parameters |
NOT_FOUND | Block not found | Check block number exists |
UNAVAILABLE | Node temporarily unavailable | Retry with backoff |
Best Practices
- Cache fee estimates - Update every 30-60 seconds, not per transaction
- Monitor confirmations - Poll block number for transaction confirmations
- Use appropriate fees - Balance cost vs confirmation time
- Handle reorgs - Be aware of blockchain reorganizations on short confirmation counts