Explorer API Reference

The Theta Explorer APIs are provided by the Theta Explorer Microservice Node. It is the REST interface via which a user can interact with the Theta Explorer Microservice Node directly.

Theta Explorer APIs

Block APIs

GetBlock

This API returns the details of the block being queried with height.

REST Uri: /block/{height}

Returns

  • epoch: epoch of the block
  • height: height of the block
  • parent: hash of the parent block
  • transactions_hash: root hash of the transaction Merkle-Patricia trie
  • state_hash: root hash of the state Merkle-Patricia trie
  • timestamp: timestamp when the block was proposed
  • proposer: address of the proposer validator
  • hash: the block hash
  • transactions: json representation of the transactions contained in the block
  • raw: transaction details
  • type: type of the transaction (see the Transaction Types note below)
  • hash: hash of the transaction
  • status: status of the block (see the Block Status note below)

Transaction Types

0: coinbase transaction, for validator/guardian reward
1: slash transaction, for slashing malicious actors
2: send transaction, for sending tokens among accounts
3: reserve fund transaction, for off-chain micropayment
4: release fund transaction, for off-chain micropayment
5: service payment transaction, for off-chain micropayment
6: split rule transaction, for the "split rule" special smart contract
7: smart contract transaction, for general purpose smart contract
8: deposit stake transaction, for depositing stake to validators/guardians
9: withdraw stake transaction, for withdrawing stake from validators/guardians

Block Status

0: pending 
1: valid
2: invalid
3: committed
4: directly finalized
5: indirectly finalized
6: trusted (the first block in a verified snapshot is marked as trusted)

A block and all the transactions included in the block are considered Finalized by the validators if the block status is either 4, 5, or 6

Block status transitions:

+-------+          +-------+                          +-------------------+
|Pending+---+------>Invalid|                    +----->IndirectlyFinalized|
+-------+   |      +-------+                    |     +-------------------+
            |                                   |
            |      +-----+        +---------+   |     +-----------------+
            +------>Valid+-------->Committed+---+----->DirectlyFinalized|
                   +-----+        +---------+         +-----------------+

Example

// Request
curl https://explorer.thetatoken.org:8443/api/block/1

// Result
{  
   "type":"block",
   "body":{  
      "epoch":"1",
      "status":5,
      "height":1,
      "timestamp":"1550089775",
      "hash":"0x705b74cde1ad4afefb8cae883327b216dd11c3a4b592b4487a40337e5e27a7bd",
      "parent_hash":"0x8ce72f57b6ef53c7d5d144a40d6faacc444e9cd60d79043ea5ab978f44c120c6",
      "proposer":"0x9f1233798e905e173560071255140b4a8abd3ec6",
      "state_hash":"0xcb9b1641ecb9f1fb372a9ac9184c811c07bda3d061ce63b2c2e2f1fafc42c789",
      "transactions_hash":"0x36449d6d0523379a6799843cea98c0a4d708a7c314d0536496a78dee57fcb672",
      "num_txs":1,
      "txs":[  
         {  
            "raw":{  
               "proposer":{  
                  "address":"0x9f1233798e905e173560071255140b4a8abd3ec6",
                  "coins":{  
                     "thetawei":"0",
                     "tfuelwei":"0"
                  },
                  "sequence":"0",
                  "signature":"0xe54784005c1c321092d24ba50a32228b7b7b6d4e5ad41aa968e96123f1996f623aa609ab7414995aaa25eb8897ca2bb3809695e31829d5de2ee94eead3907eda00"
               },
               "outputs":[  
                  {  
                     "address":"0x2e833968e5bb786ae419c4d13189fb081cc43bab",
                     "coins":{  
                        "thetawei":"0",
                        "tfuelwei":"0"
                     }
                  },
                  {  
                     "address":"0x350ddef232565b32e66a9fb69780e85b686a9e1d",
                     "coins":{  
                        "thetawei":"0",
                        "tfuelwei":"0"
                     }
                  },
                  {  
                     "address":"0x5f74e3d5cc77b66f0030c5501cfbd39dcb8ff5b6",
                     "coins":{  
                        "thetawei":"0",
                        "tfuelwei":"0"
                     }
                  },
                  {  
                     "address":"0x7631958d57cf6a5605635a5f06aa2ae2e000820e",
                     "coins":{  
                        "thetawei":"0",
                        "tfuelwei":"0"
                     }
                  },
                  {  
                     "address":"0x9f1233798e905e173560071255140b4a8abd3ec6",
                     "coins":{  
                        "thetawei":"0",
                        "tfuelwei":"0"
                     }
                  },
                  {  
                     "address":"0xc15e24083152dd76ae6fc2aeb5269ff23d70330b",
                     "coins":{  
                        "thetawei":"0",
                        "tfuelwei":"0"
                     }
                  },
                  {  
                     "address":"0xdfb095b990c98a96dd434fe45cd040ec2167c228",
                     "coins":{  
                        "thetawei":"0",
                        "tfuelwei":"0"
                     }
                  }
               ],
               "block_height":"0"
            },
            "type":0,
            "hash":"0x72738626b99c6942daea0a04eaaca4d83d1d72e1620a0c55d35a886dcb0f56b1"
         }
      ]
   },
   "totalBlocksNumber":17164
}

GetBlocksByRange

This API returns a list of blocks given the page number and limit number.

REST Uri: /blocks/top_blocks

Query Parameters

  • pageNumber: the page number, 1 stands for the latest
  • limit: the limit size of each page

Returns

  • currentPageNumber: the number of current page
  • For each block it is similar to the returns of the GetBlock API. Please see above.

Example

In this example, we query the blocks with page number 0 and page size 10.

// Request
curl https://explorer.thetatoken.org:8443/api/blocks/top_blocks?pageNumber=1&limit=10

// Result
{  
   "type":"block_list",
   "body":[  
      {  
         "epoch":"17475",
         "status":4,
         "height":17449,
         "timestamp":"1550199501",
         "hash":"0x4756f30fa538769e4dcaae9fcbd19f6612b05abc843aa9c07a28983121fb3b1d",
         "parent_hash":"0xdd3fde69f68d8b9522adab25f04459f84072a160c2ab3ceeb086777550378e7f",
         "proposer":"0xc15e24083152dd76ae6fc2aeb5269ff23d70330b",
         "state_hash":"0x9711aadb58db9b33ac2f8e29584d772184b01b8406bc2c7cda52a024eeabba8a",
         "transactions_hash":"0xa90c99ab4a3861cfd2a71280a2f74f4aadda5727b72f046687681adfe31c3b5e",
         "num_txs":7,
         "txs":[...]
      },
      {  
         "epoch":"17476",
         "status":4,
         "height":17450,
         "timestamp":"1550199507",
         "hash":"0xb5997adcd3daf6c249b2e4ae79945d36fc1aa262fc344a5c665193460c4c2fec",
         "parent_hash":"0x4756f30fa538769e4dcaae9fcbd19f6612b05abc843aa9c07a28983121fb3b1d",
         "proposer":"0x9f1233798e905e173560071255140b4a8abd3ec6",
         "state_hash":"0x69407583b370cbc8c27c63f975e0a3145f05068f8a488d7411ed634f1544fefc",
         "transactions_hash":"0x1ff24e55b5c2e1a9e01ced5d7f92fe2dde90511e7b5cb28e93ed8751df721bda",
         "num_txs":5,
         "txs":[...]
      },
      {  
         "epoch":"17477",
         "status":4,
         "height":17451,
         "timestamp":"1550199513",
         "hash":"0x082b3653ccc74b26612da4a7666b2c3e9c2ce2222dd90c6083884892a0e3f1c6",
         "parent_hash":"0xb5997adcd3daf6c249b2e4ae79945d36fc1aa262fc344a5c665193460c4c2fec",
         "proposer":"0x7631958d57cf6a5605635a5f06aa2ae2e000820e",
         "state_hash":"0x10931619d1986b4b62f816c11643dbe66aeccbb48e2995b81fbf0786ceb312d1",
         "transactions_hash":"0x0cabb62272efeac14a06eb323c5b7e8b87271a948a619e5ead4a4fd284c094cf",
         "num_txs":7,
         "txs":[...]
      },
      {  
         "epoch":"17478",
         "status":4,
         "height":17452,
         "timestamp":"1550199520",
         "hash":"0x2ff868bf9c8aab3c2482a91b090530f430c8afb94fd66c60b9c8fd845899a00a",
         "parent_hash":"0x082b3653ccc74b26612da4a7666b2c3e9c2ce2222dd90c6083884892a0e3f1c6",
         "proposer":"0x9f1233798e905e173560071255140b4a8abd3ec6",
         "state_hash":"0x4d78020673af830a92ff5fc78a9d1859ecee3b07bf7cbda8d3ae74d61e0fee50",
         "transactions_hash":"0x1d77c10d77a8380f07ade4474816332d347f8739913aee03ae81f1f02391d3ae",
         "num_txs":3,
         "txs":[...]
      },
      {  
         "epoch":"17479",
         "status":4,
         "height":17453,
         "timestamp":"1550199526",
         "hash":"0x7953f10d559405dad20db498947148a73781546209485a803e414574e3439255",
         "parent_hash":"0x2ff868bf9c8aab3c2482a91b090530f430c8afb94fd66c60b9c8fd845899a00a",
         "proposer":"0x2e833968e5bb786ae419c4d13189fb081cc43bab",
         "state_hash":"0x62e34301225525c3dd44ee951e45a97a1590303aa9ba3586cf0c1791b1f8ebc4",
         "transactions_hash":"0x404e4a202f4e621ccf0abe824c318edf012b5a52b5c52d3509e050b996185f53",
         "num_txs":6,
         "txs":[...]
      },
      {  
         "epoch":"17480",
         "status":4,
         "height":17454,
         "timestamp":"1550199532",
         "hash":"0xe752c9e9dd0b5bca6aefe31c5d84845ba7e3d469eb56f1a91300b316ffc5ce4c",
         "parent_hash":"0x7953f10d559405dad20db498947148a73781546209485a803e414574e3439255",
         "proposer":"0xdfb095b990c98a96dd434fe45cd040ec2167c228",
         "state_hash":"0x2a2b68e13f0bb27b3adbef5ab54d1a8ef07a6e16afa8172684c5f5e8771f43ba",
         "transactions_hash":"0x679095a23b223847c197005d0b6e1995012bb381f49fc3c36bda40af6143149d",
         "num_txs":5,
         "txs":[...]
      },
      {  
         "epoch":"17481",
         "status":4,
         "height":17455,
         "timestamp":"1550199539",
         "hash":"0x05b6b8bd715f600242208710081395a050e37d6af0fa9789f74b50d37c696ca6",
         "parent_hash":"0xe752c9e9dd0b5bca6aefe31c5d84845ba7e3d469eb56f1a91300b316ffc5ce4c",
         "proposer":"0x2e833968e5bb786ae419c4d13189fb081cc43bab",
         "state_hash":"0xa6ad424d8d3d02c52f8f4aefa8c7d92a746e9b1368bb723e56805827d4b757f4",
         "transactions_hash":"0x016e5c9a7e43cb5d869d3a65a03da6e87e91fe5da3bb2bc9319b262532cfab42",
         "num_txs":5,
         "txs":[...]
      },
      {  
         "epoch":"17482",
         "status":4,
         "height":17456,
         "timestamp":"1550199545",
         "hash":"0x16b6d178380af8fb580f6d055919744f8dbee0c850d685f7f9dc34507db8f716",
         "parent_hash":"0x05b6b8bd715f600242208710081395a050e37d6af0fa9789f74b50d37c696ca6",
         "proposer":"0xc15e24083152dd76ae6fc2aeb5269ff23d70330b",
         "state_hash":"0xd97a3238cd3f97c2e3db9f4c825a6bb59ba2bb02112029c83f53b9495ef282ac",
         "transactions_hash":"0xbbd09b8bd634d59b44f810a72c2adb836eef3c4f83ef01033281c556bbe35342",
         "num_txs":3,
         "txs":[...]
      },
      {  
         "epoch":"17483",
         "status":4,
         "height":17457,
         "timestamp":"1550199551",
         "hash":"0x9b9cd1306346a692258f9b2c1ee2a0cdb66956efbf41e9c43658cf078fc2c229",
         "parent_hash":"0x16b6d178380af8fb580f6d055919744f8dbee0c850d685f7f9dc34507db8f716",
         "proposer":"0x9f1233798e905e173560071255140b4a8abd3ec6",
         "state_hash":"0xbb018c8e3b6c7d94bc8d1e547fe748296df5ef8f5734a9abfd5faaa54d11c858",
         "transactions_hash":"0x06d08fc4e13b021868f1394af440d53f4eca60e55015eb3dea7e8fcdf5d595ea",
         "num_txs":4,
         "txs":[...]
      },
      {  
         "epoch":"17484",
         "status":4,
         "height":17458,
         "timestamp":"1550199557",
         "hash":"0x70e1102013273079484dff737c36850765eb9794e2fde402fa3c4c2ddb45fc7b",
         "parent_hash":"0x9b9cd1306346a692258f9b2c1ee2a0cdb66956efbf41e9c43658cf078fc2c229",
         "proposer":"0x7631958d57cf6a5605635a5f06aa2ae2e000820e",
         "state_hash":"0xd3915c55728a568c6272de77dbea60aa20a1c1fb6c096a7fd4eecdb0bdde005d",
         "transactions_hash":"0xe51b8bea2fa6e9ff2c28bf488913c66d081647dbcf0c85311099b84fcc3769be",
         "num_txs":4,
         "txs":[...]
      }
   ],
   "totalPageNumber":1746,
   "currentPageNumber":"1"
}

Transaction APIs

GetTransaction

This API returns the details of the transaction being queried with hash.

REST Uri: /transaction/{hash}

Query Parameters

  • hash: the transaction hash

Returns

  • block_height: height of the block that contains the transaction
  • hash: the hash of the transaction itself
  • data: the details of the transaction
  • type: transaction type
  • totalTxsNumber: total number of transactions in database
  • timestamp: the time stamp of the block contains this block
  • number: the sequence number of the transaction in database

Example

{  
   "type":"transaction",
   "body":{  
      "hash":"0XF16402022FFFADA96C4BA9A78F79730903F8D99EF44D221FC5869EC4191260EC",
      "type":5,
      "data":{  
         "fee":{  
            "thetawei":"0",
            "tfuelwei":"1000000000000"
         },
         "source":{  
            "address":"0x02990c3f7f75865bcd2fb28450f01065754f9372",
            "coins":{  
               "thetawei":"0",
               "tfuelwei":"1150000000000000"
            },
            "sequence":"0",
            "signature":"0x66cb200ad7def6a0b4e9d377fd6a54cf19f952d089772b2dda8bd0f0927434825acec09e5c2c7aaaf9c4d18a2730786ee619a593fd49395913785aa4255e164001"
         },
         "target":{  
            "address":"0x49e2268b8962a7b5680512173f2b320418003082",
            "coins":{  
               "thetawei":"0",
               "tfuelwei":"0"
            },
            "sequence":"126",
            "signature":"0xdd6aecdf642a001b9ae299cf44aa5c142dac45dd58666d326870dc53670dc204548951880ebce343afb27c968bb99488c23bc9af43a60c4de6299c6242cf07ac00"
         },
         "payment_sequence":"1550282279177",
         "reserve_sequence":"178",
         "resource_id":"vidivz187ttu9eck65d"
      },
      "number":196771,
      "block_height":"30615",
      "timestamp":"1550282330"
   },
   "totalTxsNumber":196771
}

GetTransactionsByRange

This API returns a list of blocks given the page number and limit number.

REST Uri: /transactions/range

Query Parameters

  • pageNumber: the page number, 0 stands for the latest
  • limit: the limit size of each page

Returns

  • currentPageNumber: the number of current page
  • totalPageNumber: the total number of pages
  • For each transaction it is similar to the returns of the GetTransaction API. Please see above.

Example

// Request
curl https://explorer.thetatoken.org:8443/api/transactions/range?pageNumber=1&limit=10

// Result
{  
   "type":"transaction_list",
   "body":[  
      {...},
      {...},
      {...},
      {...},
      {...},
      {...},
      {...},
      {...},
      {...},
      {...}
   ],
   "totalPageNumber":20354,
   "currentPageNumber":"1"
}

Account APIs

GetAccount

This API returns the details of the account being queried with address.

REST Uri: /account/{address}

Query Parameters

  • address: the address of the account

Returns

  • address: the account address
  • balance: the native token balance
  • reserved_funds: fund reserved for micropayment through the off-chain resource-oriented payment pool
  • sequence: the current sequence number of the account
  • txs_counter: the counter map contains how many transactions of each transaction type include this account

Example

// Request
curl https://explorer.thetatoken.org:8443/api/account/0x3c6D5ED0353c22c31c5F91688A9D10E7Af2DF636

// Result
{
  "type": "account",
  "body": {
    "address": "0x3c6d5ed0353c22c31c5f91688a9d10e7af2df636",
    "balance": {
      "thetawei": "0",
      "tfuelwei": "1540957523000000000000"
    },
    "sequence": "0",
    "reserved_funds": [],
    "txs_counter": {
      "2": 2,
      "5": 973
    }
  }
}

GetAccountTxHistory

This API returns the details of the account being queried with address.

REST Uri: /accountTx/:address

Query Parameters

  • address: the address of the account
  • type: type of the transaction (see the Transaction Types note above)
  • isEqualType: true returns a transaction list only include the type above, false returns a transaction list exclude the type above.
  • pageNumber: the number of page
  • limitNumber: the size of each page

Returns

  • currentPageNumber: the number of current page
  • totalPageNumber: the total number of
  • For each transaction it is similar to the returns of the GetTransaction API. Please see above.

Example

// Request
curl "https://explorer.thetatoken.org:8443/api/accounttx/0x3c6D5ED0353c22c31c5F91688A9D10E7Af2DF636?type=2&pageNumber=1&limitNumber=50&isEqualType=true"

// Result
{
  "type": "account_tx_list",
  "body": [
    {...},
    {...}
  ],
  "totalPageNumber": 1,
  "currentPageNumber": 1
}

GetTopTokenHolders

This API returns the list of top token holders.

REST Uri: /account/top/:tokenType/:limit

Query Parameters

  • tokenType: type of the token(theta/tfuel)
  • limit: the size of returns

Returns

  • For each account it is similar to the returns of the GetAccount API. Please see above.

Example

// Request
curl "https://explorer.thetatoken.org:8443/api/account/top/theta/5"

// Result
{
"type": "account_list",
"body": [
   {...},
   {...},
   {...},
   {...},
   {...}
   ]
}

Stake APIs

GetAllStakes

This API returns all stake records.

REST Uri: /stake/all

Returns

  • stakes: json representation of the stakes
  • _id: the ID for the stake record
  • type: this stake is in the validator candidate pool or the guardian candidate pool
  • holder: the holder account's address
  • source: the source account's address
  • amount: the staked thetawei amount
  • withdrawn: true returns the stake is withdrawn, false returns the stake is not withdrawn
  • return_height: the expected height the tokens return to the staking wallet if a node withdraws its stake

Example

// Request 
curl https://explorer.thetatoken.org:8443/api/stake/all

// Result
{
   "type": "stake",
   "body": [{
      "_id": "5eb9f45d38696f556cc3334d",
      "type": "vcp",
      "holder": "0x80eab22e27d4b94511f5906484369b868d6552d2",
      "source": "0x4aefa39caeadd662ae31ab0ce7c8c2c9c0a013e8",
      "amount": "20000000000000000000000000",
      "withdrawn": false,
      "return_height": "18446744073709551615"
      },{
         "_id": "5eb9f45d38696f556cc3334e",
         "type": "vcp",
         "holder": "0x80eab22e27d4b94511f5906484369b868d6552d2",
         "source": "0x747f15cac97b973290e106ef32d1b6fe65fef5a1",
         "amount": "40000000000000000000000000",
         "withdrawn": false,
         "return_height": "18446744073709551615"
      },{
         "_id": "5eb9f45d38696f556cc33351",
         "type": "vcp",
         "holder": "0xa61abd72cdc50d17a3cbdceb57d3d5e4d8839bce",
         "source": "0x0c9a45926a44a6fc9c8b6f9cb45c20483038698c",
         "amount": "32000000000000000000000000",
         "withdrawn": false,
         "return_height": "18446744073709551615"
      }
      ...
   ]
}

GetTotalStakedAmount

This API returns the total amount of stakes.

REST Uri: /stake/totalAmount

Returns

  • totalAmount: the total amount of staked thetawei
  • totalNodes: the total amount of stake nodes

Example

// Request 
curl https://explorer.thetatoken.org:8443/api/stake/totalAmount

// Result
{
   "totalAmount": "317702156000000000000000000",
   "totalNodes": 12
}

GetStakeByAddress

This API returns the stakes being queried with address.

REST Uri: /stake/:address

Returns

For each stake it is similar to the returns of the GetAllStakes API. Please see above.

Example

// Request 
curl https://explorer.thetatoken.org:8443/api/stake/totalAmount

// Result
{
   "type": "stake",
   "body": {
   "holderRecords": [],
   "sourceRecords": [
      {
         "_id": "5eb9f60638696f556cc33aa3",
         "type": "vcp",
         "holder": "0xe2408dff7a1f9bc247c803e43efa2f0a37b10ba6",
         "source": "0xc15149236229bd13f0aec783a9cc8e8059fb28da",
         "amount": "30000000000000000000000000",
         "withdrawn": false,
         "return_height": "18446744073709551615"
      },
      {
         "_id": "5eb9f60638696f556cc33aa5",
         "type": "vcp",
         "holder": "0x15cc4c3f21417c392119054c8fe5895146e1a493",
         "source": "0xc15149236229bd13f0aec783a9cc8e8059fb28da",
         "amount": "30000000000000000000000000",
         "withdrawn": false,
         "return_height": "18446744073709551615"
      },
      {
         "_id": "5eb9f60638696f556cc33aa4",
         "type": "vcp",
         "holder": "0xa144e6a98b967e585b214bfa7f6692af81987e5b",
         "source": "0xc15149236229bd13f0aec783a9cc8e8059fb28da",
         "amount": "30000000000000000000000000",
         "withdrawn": false,
         "return_height": "18446744073709551615"
      }
   ]
   }
}

Supply APIs

GetThetaAmount

his API returns the total amount and circulation amount of Theta.

REST Uri: /supply/theta

Returns

  • total_supply: the total amount of theta supplied
  • circulation_supply: the circulation amount of theta supplied

Example

// Request 
curl https://explorer.thetatoken.org:8443/api/supply/theta

// Result
{
   "total_supply":1000000000,
   "circulation_supply":1000000000
}

GetTFuelAmount

This API returns the circulation amount of TFuel.

REST Uri: /supply/tfuel

Returns

  • circulation_supply: the circulation amount of tfuel supplied

Example

// Request 
curl https://explorer.thetatoken.org:8443/api/supply/tfuel

// Result
{
   "circulation_supply":5000000000
}

What’s Next
Did this page help you?