The Bloq Connect service enables users to read and write (or “query” and “submit”) information on a number of blockchains, including Bitcoin, Bitcoin Cash, Ethereum, and Ethereum Classic — with more on the way.
With these services, merchants can monitor incoming payments, exchanges can automate customer withdrawals, and analysts can parse data. These are the fundamental building blocks required to create third-party applications that interact with and operate in a blockchain environment.
In this tutorial, we’re going to walk through how to query a blockchain record and submit a transaction on each of these four blockchains. In another unit, we’ll show how to do the same on two or more blockchains simultaneously.
Getting Started
First-time users can follow the Getting Started guide to create their Bloq account to use Bloq Connect API toolkits.
Depending on the data you are interested in, you may need to have a block, transaction, or address on hand to supply Bloq Connect. This information is readily available through a block explorer.
There are three interfaces that users can utilize to access the BTC and BCH chains via Bloq Connect:
- REST API
- Websocket API
- Javascript SDK
The Bloq Command Line Interface also offers some functionality to query the Bitcoin and Bitcoin Cash blockchains directly from your terminal. See the Connect section of the CLI Technical Reference to explore the relevant CLI commands.
JSON-RPC support is additionally built out for ETH and ETC. The following sections will provide step-by-step instructions to execute queries and submissions through each of these interfaces.
Bitcoin and Bitcoin Cash
REST API
REST was designed to interact with distributed systems, which makes it effective in communicating with Bitcoin and other blockchains. Like the Bloq CLI, users pass REST calls and data directly in their command prompt.
The REST API for Bloq Connect embodies a URL directory that points to a set of methods. In other words, users supply the URL that corresponds to the method they are looking to execute every time they produce a REST API call in their terminal. For example, the proper API url to receive block information is: https://btc.connect.bloq.cloud/api/v1/block/{hash}
REST API calls require an authentication token, either in the form of an Account or Client Access Token. A Client Access Token can be created through the CLI with bcl client-token.
Query
Once you’ve created your access token, plug it into the “Authorization: Bearer” header line of the following command and execute it in your terminal to retrieve data pertaining to the Bitcoin Genesis block:
There are several components that make up each REST API call. In the above command, the first line asserts that the client will GET the data from the server at the associated url. The specific block hash supplied at the url endpoint is where the server looks to collect block information. The other lines represent headers (denoted by -H). The first header instructs that the client will receive (“Accept”) the information in JSON format. The second header encompasses the access token that authorizes the client to GET information from the server.
Keep in mind that REST API calls are executed directly in the user’s command prompt. Because the command prompt isn’t designed as a text editor, you may find it easier to organize your commands in a separate text file and copy/paste them into the terminal to execute them.
Submit
REST API calls categorized as POST produce an output as the result of some specified input. The input data is communicated in the data (-d) field.
Plug a signed raw transaction hash into the data field alongside a valid authorization token to broadcast a transaction to the network:
To make REST API calls to the Bitcoin Cash blockchain, simply change the URL from btc.connect.bloq.cloud to bch.connect.bloq.cloud.
To learn more about the REST API and view a list of all commands please see the Bloq Connect BTC / BCH REST API Technical Reference.
Javascript SDK
The Javascript SDK provides a comprehensive suite of commands for reading and writing to the blockchain. Also note that advanced developers or Javascript-allergic users can call the API directly through whichever language they prefer — the SDK is used to simplify and streamline development.
First, install the Bloq Javascript SDK in your command prompt with npm install --save @bloq/cloud-sdk.
From here, you can create Javascript files in the text editor of your preference and pass them through your command prompt. Navigate to the proper directory and run your Javascript with node filename.js.
The header of your JS file should resemble the following:
For the clientId and clientSecret fields, generate a set of client keys through the CLI with bcl client-keys create.
To interact with Bitcoin Cash, change the btc to bch in the coin: field.
Underneath your header, you may run any number of the methods encompassed by the SDK. The methods produce a variable that represents the queried data. Use Javascript’s console.log() method to view the output.
Query
The following code represents a sample query to grab information from the BTC genesis block via the block(hash) method:
The above command passes a function with the output from client.block. More specifically, it prints “Block:” followed by the information received by the method.
The code block encompassed by the .then function (two console.log() commands, in the above code), can be changed to reflect whatever output the user desires. For example, the user could call another method with the produced variable as an input, or run some additional process when certain criteria are meant.
For instance, the user can add an additional console.log that prints “HALVING BLOCK” if the block height is divisible by 210,000 (because Bitcoin’s mining rewards halve every 210,000 blocks).
Submit
“Send Transaction” in the SDK is the primary method that enables users to submit information to the BTC / BCH blockchain.
sendTransaction(rawTransaction) takes the raw hexadecimal hash of a signed transaction and broadcasts it to the network.
The following code returns a “Transaction Success!” message alongside the broadcast transaction or an error message in the case of failure (such as an invalid raw transaction hash input):
Signing and sending transactions in separate environments enables a far superior level of security. Users can send coins from their “cold wallets,” which remain offline, by signing and exporting the transaction to be broadcast elsewhere (such as here). This eliminates any online interaction that could expose the entire account balance to hackers or otherwise malicious individuals.
To learn more about the Javascript SDK and view a list of all commands please see the Javascript SDK Technical Reference.
Ethereum / Ethereum Classic
Ethereum and Ethereum Classic are derived from a separate codebase than Bitcoin and Bitcoin Cash. As such, different methods are required to support interaction with ETH/ETC through the Bloq Connect service.
JSON-RPC
Ethereum JSON-RPC calls are generally executed in the same manner as the BTC REST API calls, with a few key distinctions.
Authorization tokens are not required for JSON-RPC calls. Instead, users must supply a valid project id in the url endpoint. Use the Bloq console to create your project id.
Because the project id is supplied in the URL, the method to call is communicated in the data (-d) field. The data field also encompasses any additional parameters, the corresponding method id, and the appropriate JSON-RPC version.
Query
Input a valid project id to the following code and execute in the terminal to retrieve the most recent Ethereum block number:
By default, Ethereum JSON-RPC calls will return numerical values in hexadecimal format. The ETH Connect Technical Reference contains directions to append Python to your calls in order to convert the output to standard decimal format.
Submit
Plug a signed raw transaction hash as parameter into the following code alongside a valid project id to broadcast a transaction to the network:
The eth_sendRawTransaction method can be used to send ether, transfer tokens, interact with contracts, and so on. In your wallet provider of choice, generate an offline transaction to sign and export. MyEtherWallet supports this functionality. When sending tokens, make sure to raise your gas limit to reflect the added gas requirements!
To make JSON-RPC calls to the Ethereum Classic blockchain, simply change the URL from eth.connect.bloq.cloud to etc.connect.bloq.cloud. The method name will remain unchanged.
To learn more about the JSON-RPC and view a list of all commands please see the Bloq Connect ETH / ETC Technical Reference.
Next Steps
Congratulations! You’ve worked through the Bloq Connect toolkit. Perhaps you’ve begun to brainstorm how these various methods and interfaces can work together to provide more nuanced utilities.
As one possible project: Set up a program that retrieves incoming blocks and check the estimated gas fees with each new block, broadcasting a signed transaction when gas fees fall below a certain threshold.