REST API

Findexer comes with REST API for easy integration into other platforms. REST API is accessible on port 2021 of the machine you run Findexer on. It's publicly accessibe by default on http://<YOUR_PUBLIC_IP>:2021.

Summary

Endpoint	Arguments	Methods	Description
/status	-	GET	Findexer status such as index progress
/sql	query, network (optional)	POST	Executes query and gives results as json
/aio_search	query, size (optional), start (optional), network (optional)	GET, POST	All-in-one blockchain search that finds anything anywhere
/get_by_height	height, index (optional), network (optional)	GET, POST	Retrieves the whole index entries at height
/evm_tx_by_hash	hash, network	GET, POST	Finds an EVM transaction by hash
/utxo_by_proposer	proposer, size (optional), start (optional), network (optional)	GET, POST	Finds all blocks proposed by proposer
/top_proposers	num (optional), network (optional)	GET, POST	Finds top proposers

Documentation

/status

• Arguements: -
• HTTP Methods: GET

Returns a JSON which contains the indexing progress of each network.

Example response

{
   "forge_last_indexed_block": 132728,
   "mainnet_last_indexed_block": 177546,
   "testnet_last_indexed_block": 60696,
   "version": "0.1"
}

---

/sql

• Arguements:

  • query: SQL query

  • network (optional): Can be mainnet, forge, or testnet. Default network is mainnet.

• HTTP Methods: POST

Executes the SQL query and returns the results in JSON format. Only SELECT and DESC queries are allowed, because this endpoint is most probably accessible to public and we don't want them to be able to UPDATE and INSERT stuff. See SQL examples for some query ideas.

Example cURL request

curl --data "query=select utxo_block_height from mainnet_flat where utxo_last_commit_hash='F453B473537AF8CB9A3BD811B93A19790CD052E11953B6E0B1E522E9FC0ECA89'" "http://127.0.0.1:2021/sql"

Example response

{ 
 "response":
   { "columns": [
      { "name": "utxo_block_height", "type": "long" }
   ],
   "rows": [ [10] ]
   },
   "version":"0.1"
}

---

/aio_search

• Arguements:

  • query: Any term or phrase as string.

  • size (optional): Number of results that will be returned. Default is 10.

  • start (optional): Indicates which result is the starting point of results. Default is 0.

  • network (optional): Can be mainnet, forge, or testnet. Default network is mainnet.

• HTTP Methods: GET, POST

All-in-one search is useful when you have a hash or any other data, but you don't know where to search for it. It searches all the fields in the whole blockchain and returns all occurrences of your query. The optional parameters size and start work together similar to LIMIT and OFFSET in most SQLs.

---

/get_by_height

• Arguements:

  • height: The height of the block.

  • index (optional): Generally, it can be flat, utxo, or web3. If network is mainnet, it can't be web3. Default index is flat.

  • network (optional): Can be mainnet, forge, or testnet. Default network is mainnet.

• HTTP Methods: GET, POST

Retrieves all information inside an index at the block height equal to parameter height.

---

/evm_tx_by_hash

• Arguements:

  • hash: Hash of a specific EVM transaction

  • network: Can be forge or testnet. Note that mainnet doesn't have EVM at the moment.

• HTTP Methods: GET, POST

Simply finds an EVM transaction by the hash.

Example cURL request

curl "http://127.0.0.1:2021/evm_tx_by_hash?network=forge&hash=0x9c71cefb4ffc6ffb8121dc9951de5d84e9527b1fb6cf9ab4bcb884401bb40018"

Example response

{
   "response": {
      "_id": "0x9c71cefb4ffc6ffb8121dc9951de5d84e9527b1fb6cf9ab4bcb884401bb40018",
      "_ignored": [
         "raw.keyword"
      ],
      "_index": "forge_tx",
      "_primary_term": 1,
      "_seq_no": 872,
      "_source": {
         "blockHash": "0xfab3ee14509dad7fe1a68f65cbffdfc040a3b17c9775d153cbed2dae7724140a",
         "blockNumber": 132244,
         "chainId": "0x20d",
         "creates": null,
         "from": "0x71819C78cc5c33A37460eE681ef39f98bfb4e5BA",
         "gas": 43457,
         "gasPrice": 10000000000,
         "hash": "0x9c71cefb4ffc6ffb8121dc9951de5d84e9527b1fb6cf9ab4bcb884401bb40018",
         "input": "0xb3ab15fb0000000000000000000000007dd3fd126e5d8ea01ba2188c46c53c5540a36803",
         "nonce": 267,
         "publicKey": "0xc130be965b95b2eb7b3437e9a6d72b6f55d758abd7b14ca384a7249a2917d2d5a6c10ce667df0f5695e23342388f9b2b516d7a986c05b81226bd0fcbffc3411e",
         "r": "0x2d6fb00912150488a9cc202017ae2711627d3253400cd5fd1b70f44fa9afd71c",
         "raw": "0xf88c82010b8502540be40082a9c19468a69a95858b6e2ca34ecc8c35714669ec93741880a4b3ab15fb0000000000000000000000007dd3fd126e5d8ea01ba2188c46c53c5540a3680382043da02d6fb00912150488a9cc202017ae2711627d3253400cd5fd1b70f44fa9afd71ca0087c548ac2ed491727e488ac81a59ef8b85bf7f03b5b7ea5e72cd0a218279597",
         "s": "0x087c548ac2ed491727e488ac81a59ef8b85bf7f03b5b7ea5e72cd0a218279597",
         "standardV": 0,
         "timestamp": "2021-11-05T02:47:08",
         "to": "0x68A69A95858b6E2cA34eCC8C35714669ec937418",
         "transactionIndex": 0,
         "v": 1085,
         "value": 0,
         "valueStr": "0"
      },
      "_type": "_doc",
      "_version": 1,
      "found": true
   },
   "version": "0.1"
}

---

/utxo_by_proposer

• Arguements:

  • proposer: Proposer address as string

  • size (optional): Number of results that will be returned. Default is 10.

  • start (optional): Indicates which result is the starting point of results. Default is 0.

  • network (optional): Can be mainnet, forge, or testnet. Default network is mainnet.

• HTTP Methods: GET, POST

Finds all blocks proposed by a proposer. The optional parameters size and start work together similar to LIMIT and OFFSET in most SQLs.

---

/top_proposers

• Arguements:

  • num (optional): Number of top proposers to be returned. Default is top 10.

  • network (optional): Can be mainnet, forge, or testnet. Default network is mainnet.

• HTTP Methods: GET, POST

Returns the top num UTXO block proposers.

---

Adding more Endpoints

It's pretty easy to add more endpoints to this REST API. Please check app.py and searcher.py for some clues. If Flask/Python/Elasticsearch stack isn't your thing, feel free to submit an issue requesting an endpoint you really need.