Skip to main content

​
Overview

Makes REST API calls to Hive blockchain REST endpoints with automatic retry and failover support. Provides type-safe access to various Hive REST APIs with automatic path and query parameter handling.

​
Function Signature

export async function callREST<Api extends APIMethods, P extends keyof APIPaths[Api]>(
  api: Api,
  endpoint: P,
  params?: ParamsForEndpoint<APIPaths[Api][P]>,
  timeout = config.timeout,
  retry = config.retry
): Promise<GetResponse<SafeGet<APIPaths[Api][P]>>>

​
Parameters

​
api
APIMethods
required
The REST API method name. Available options:
  • 'balance' - Balance API for account balances
  • 'hafah' - HAF Account History API
  • 'hafbe' - HAF Block Explorer API
  • 'hivemind' - Hivemind social API
  • 'hivesense' - Hivesense API
  • 'reputation' - Reputation API
  • 'nft-tracker' - NFT Tracker API
  • 'hafsql' - HAF SQL API
  • 'status' - Status API
​
endpoint
string
required
The specific endpoint path within the API (e.g., '/accounts/{account-name}/balances')
​
params
object
Optional parameters for path and query string replacement. Path parameters are replaced in the endpoint URL, remaining parameters become query parameters.
​
timeout
number
default:"config.timeout"
Request timeout in milliseconds. If not specified, uses the default timeout from configuration.
​
retry
number
default:"config.retry"
Number of retry attempts before throwing an error. The function will try different REST nodes on failure.

​
Return Type

​
result
Promise<T>
Returns a Promise that resolves to the API response data with proper TypeScript typing based on the endpoint specification.

​
API Method Types

The function supports the following REST API endpoints:
API MethodBase PathDescription
balance/balance-apiAccount balance and transaction history
hafah/hafah-apiHAF Account History operations
hafbe/hafbe-apiHAF Block Explorer data
hivemind/hivemind-apiSocial features (posts, followers, etc.)
hivesense/hivesense-apiHivesense analytics
reputation/reputation-apiAccount reputation data
nft-tracker/nft-tracker-apiNFT tracking and data
hafsql/hafsqlSQL-based queries
status/status-apiNode status information

​
Path and Query Parameters

The function intelligently handles parameters:
  1. Path Parameters: Parameters matching {param-name} in the endpoint are replaced in the URL
  2. Query Parameters: Remaining parameters are added as query string parameters
// Path parameter: {account-name} is replaced
// Query parameter: coin-type becomes ?coin-type=HBD
await callREST('balance', '/accounts/{account-name}/aggregated-history', {
  'account-name': 'alice',  // Path parameter
  'coin-type': 'HBD'         // Query parameter
})
// Results in: /balance-api/accounts/alice/aggregated-history?coin-type=HBD

​
Examples

​
Balance API - Get Account Balances

import { callREST } from 'hive-tx'

const balance = await callREST(
  'balance',
  '/accounts/{account-name}/balances',
  { 'account-name': 'alice' }
)
console.log(balance)

​
Balance API - Get Aggregated History

import { callREST } from 'hive-tx'

const data = await callREST(
  'balance',
  '/accounts/{account-name}/aggregated-history',
  {
    'account-name': 'mahdiyari',
    'coin-type': 'HBD'
  }
)
console.log(data)

​
Status API - Get Node Status

import { callREST } from 'hive-tx'

const status = await callREST('status', '/status')
console.log(status.version, status.block_num)

​
HAF Account History - Get Account Operations

import { callREST } from 'hive-tx'

const operations = await callREST(
  'hafah',
  '/accounts/{account}/operations',
  {
    account: 'alice',
    limit: 100,
    offset: 0
  }
)

​
Hivemind API - Get Account Followers

import { callREST } from 'hive-tx'

const followers = await callREST(
  'hivemind',
  '/accounts/{account}/followers',
  {
    account: 'alice',
    limit: 50
  }
)

​
Custom Timeout and Retry

import { callREST } from 'hive-tx'

// 10 second timeout, 3 retry attempts
const data = await callREST(
  'status',
  '/status',
  undefined,
  10_000,
  3
)

​
Array Query Parameters

import { callREST } from 'hive-tx'

// Arrays are properly encoded as multiple query parameters
const data = await callREST(
  'balance',
  '/accounts/balances',
  {
    accounts: ['alice', 'bob', 'charlie']
  }
)
// Results in: /balance-api/accounts/balances?accounts=alice&accounts=bob&accounts=charlie

​
Error Handling

import { callREST } from 'hive-tx'

try {
  const balance = await callREST(
    'balance',
    '/accounts/{account-name}/balances',
    { 'account-name': 'alice' }
  )
  console.log(balance)
} catch (error) {
  if (error.message.includes('HTTP 404')) {
    console.error('Endpoint not found or invalid parameters')
  } else {
    console.error('Network or timeout error:', error)
  }
}

​
TypeScript Type Safety

The function uses TypeScript generics to provide full type safety: 
// TypeScript knows the exact response type based on the endpoint
const balance = await callREST(
  'balance',
  '/accounts/{account-name}/balances',
  { 'account-name': 'alice' }
)
// balance is properly typed based on the API specification

​
Behavior

  • Automatically rotates through configured REST nodes on failure
  • Properly encodes path parameters in URLs
  • Converts remaining parameters to query strings
  • Handles array parameters by appending multiple values
  • Throws error immediately on HTTP 404 responses
  • Retries on network or timeout errors with different nodes

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us