# Explorer API

Memento includes an API that exports the indexed data in the format required by the [Ethereum Lite Explorer by Alethio](https://github.com/Alethio/ethereum-lite-explorer).

The API is exposed by default on port `3001` and prefixed with `/api/explorer` .&#x20;

{% hint style="info" %}
Most of the fields follow the [EthOn Ontology](https://ethon.consensys.net/). If you don't know what a field means, search it there first.
{% endhint %}

## Get block details

<mark style="color:blue;">`GET`</mark> `http://localhost:3000/api/explorer/block/:number`

This endpoint returns the block details as well as the list of transactions included with minimal details.

#### Path Parameters

| Name   | Type   | Description                                    |
| ------ | ------ | ---------------------------------------------- |
| number | number | The number of the block or the string "latest" |

{% tabs %}
{% tab title="200 Block details successfuly retrieved." %}
```
{
   "data":{
      "number":1366167,
      "blockHash":"923448a9f427f1dbd084669b9d93c862b41230cc1ebe67119084849dd8567cca",
      "parentBlockHash":"64003d594cd4447fa0be0a3d2391832f118e57751c9f2a31377285a2f62b4221",
      "blockCreationTime":1569511060,
      "blockGasLimit":"8000000",
      "blockGasUsed":"391256",
      "blockDifficulty":"2",
      "totalBlockDifficulty":"2117728",
      "blockExtraData":"44505020417574686f726974790000000000000000000000000000000000000024a3ca164bd0e46423162d0047d24823182655d36a2ae7a01ccf4730f7475ba06d1ebff10e65aa578399e527c91918b2e1ff7d6dfdbb71ffd5d797fb0b653a8f01",
      "blockMixHash":"",
      "blockNonce":"",
      "blockSize":1430,
      "blockLogsBloom":"00004080000000000000000400000000000000000000002000000000000000000000000000000000000000000400000000000004004000000000000200000000000000000000008000000000000000080000000000000010400000000000000000000000000000000000000000000000100000400000000000000000000000000000000100000000000000000000000000000002000000000000000000000040000400000000000000000000000000000000000040000000001000000001000000000000100000040000002040000002080000000000000000000000000000000000410000000000080800000000000000800000000000000100000000000000",
      "includesUncle":null,
      "hasBeneficiary":"5dfe3772ceb73531357c3c747b6999cf59a59533",
      "hasReceiptsTrie":"e49804feedd0db7fd390e2068532c12a475ce2ad18caecac93ceda5295203a04",
      "hasTxTrie":"a2d34417c97ce4e4ec8a737ba39e92602d869ea97437ffe9b3f5fee3a5fbcb09",
      "sha3Uncles":"1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "numberOfUncles":0,
      "numberOfTxs":4,
      "txs":[
         {
            "txHash":"fc6b8ffc590c9a1e62f4841b9d9d968e732332f396b8cbeef23e8e20f30cdee2",
            "txIndex":0,
            "from":"d13e9b904c6e57ee929811f70db22cd308a56cf0",
            "to":"9526ec0e58ac5bb1e24d655e964f0eaa46054d16",
            "value":"0",
            "msgGasLimit":"127151",
            "txGasUsed":"97809",
            "txGasPrice":"30000000000"
         },
         ...
      ]
   },
   "status":200
}
```
{% endtab %}

{% tab title="404 Could not find block (does not exist in the database)." %}
```
{
    "data": null,
    "status": 404
}
```
{% endtab %}
{% endtabs %}

## Get block range

<mark style="color:blue;">`GET`</mark> `http://localhost:3000/api/explorer/block-range/:start/:end`

Returns a list of blocks in the \[start, end] interval ordered in descending order by block number.

#### Path Parameters

| Name  | Type   | Description               |
| ----- | ------ | ------------------------- |
| end   | number | The ending block number   |
| start | number | The starting block number |

{% tabs %}
{% tab title="200 Found at least one block in this interval" %}
```
{
   "data":[
      {
         "blockCreationTime":1569511240,
         "hasBeneficiary":"0000000000000000000000000000000000000000",
         "number":1366179,
         "numberOfTxs":4
      },
      {
         "blockCreationTime":1569511225,
         "hasBeneficiary":"0000000000000000000000000000000000000000",
         "number":1366178,
         "numberOfTxs":1
      },
      {
         "blockCreationTime":1569511210,
         "hasBeneficiary":"0000000000000000000000000000000000000000",
         "number":1366177,
         "numberOfTxs":0
      }
      ...
   ],
   "status":200
}
```
{% endtab %}

{% tab title="400 Input parameters are not correct" %}
```
{
    "data": "invalid request: block number must be numeric",
    "status": 400
}
```
{% endtab %}

{% tab title="404 Could not find any block in the specified interval" %}
```
{
    "data": null,
    "status": 404
}
```
{% endtab %}
{% endtabs %}

## Get uncle details

<mark style="color:blue;">`GET`</mark> `http://localhost:3000/api/explorer/uncle/:hash`

Returns the details of an uncle by hash.

#### Path Parameters

| Name | Type   | Description                |
| ---- | ------ | -------------------------- |
| hash | string | The blockHash of the uncle |

{% tabs %}
{% tab title="200 Uncle details successfully retrieved" %}
```
{
   "data":{
      "number":1366167,
      "includedInBlock":1366167,
      "uncleIndex":0,
      "blockHash":"923448a9f427f1dbd084669b9d93c862b41230cc1ebe67119084849dd8567cca",
      "blockCreationTime":1569511060,
      "blockGasLimit":"8000000",
      "blockGasUsed":"391256",
      "blockDifficulty":"2",
      "blockExtraData":"44505020417574686f726974790000000000000000000000000000000000000024a3ca164bd0e46423162d0047d24823182655d36a2ae7a01ccf4730f7475ba06d1ebff10e65aa578399e527c91918b2e1ff7d6dfdbb71ffd5d797fb0b653a8f01",
      "blockMixHash":"",
      "blockNonce":"",
      "blockLogsBloom":"00004080000000000000000400000000000000000000002000000000000000000000000000000000000000000400000000000004004000000000000200000000000000000000008000000000000000080000000000000010400000000000000000000000000000000000000000000000100000400000000000000000000000000000000100000000000000000000000000000002000000000000000000000040000400000000000000000000000000000000000040000000001000000001000000000000100000040000002040000002080000000000000000000000000000000000410000000000080800000000000000800000000000000100000000000000",
      "hasBeneficiary":"5dfe3772ceb73531357c3c747b6999cf59a59533",
      "sha3Uncles":"1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347"
   },
   "status":200
}
```
{% endtab %}

{% tab title="404 Could not find uncle" %}
```
{
    "data": null,
    "status": 404
}
```
{% endtab %}
{% endtabs %}

## Get transaction details

<mark style="color:blue;">`GET`</mark> `http://localhost:3000/api/explorer/tx/:txHash`

Returns transaction details identified by transaction hash.

#### Path Parameters

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| txHash | string | The hash of the transaction |

{% tabs %}
{% tab title="200 Transaction details retrieved successfuly." %}
```
{
    "data": {
        "txHash": "d52e0710c772793a873cb7a377b29edb9eec23eca945d7350d279c631f29ae99",
        "includedInBlock": 1683030,
        "txIndex": 4,
        "from": "6e43d05adfd2a089665fe72fc12f68b19bacff88",
        "to": "da1fbc048f503635950058953f5c60fc1f564ee6",
        "value": "0",
        "txNonce": 1,
        "msgGasLimit": "111034",
        "txGasUsed": "70189",
        "txGasPrice": "1000001145",
        "cumulativeGasUsed": "328287",
        "msgPayload": "63ea01430000000000000000000000000000000000000000000000000000000000000a4c0000000000000000000000006e43d05adfd2a089665fe72fc12f68b19bacff880000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000002136365bb483240101ebc8258785c32d6ee856fe",
        "msgStatus": "0x1",
        "msgError": false,
        "msgErrorString": "",
        "creates": "",
        "txLogsBloom": "00000000001000000000000000000004000000000000000000000000000000000000000001000000000000000000000000000000000001000000000000000001000000000000000000000008000000400000000000000000080000000000000000000000000000000100000000000000000000000000000000000010000000080000000000200000000000000008000000000040000000000000008000000000400000000000000000000000000000000000000000000000000000000000000000000002000000000000000000001000800000000001000000000000000000000000000100000000000000000000000000000000000000000000000000000000",
        "blockCreationTime": 1574265142,
        "logEntriesTriggered": 2
    },
    "status": 200
}
```
{% endtab %}

{% tab title="404 Could not find transaction" %}
```
{
    "data": null,
    "status": 404
}
```
{% endtab %}
{% endtabs %}

## Get log entries for a transaction

<mark style="color:blue;">`GET`</mark> `http://localhost:3000/api/explorer/tx/:txHash/log-entries`

Returns details about the LogEntries of a transaction

#### Path Parameters

| Name   | Type   | Description                 |
| ------ | ------ | --------------------------- |
| txHash | string | The hash of the transaction |

{% tabs %}
{% tab title="200 LogEntries details retrieved successfuly." %}
```
{
   "data":[
      {
         "txHash":"5bb9129d1474132a382dab8fd9bab8ad2bbfa199dc43d04e394d7759cf354735",
         "logIndex":0,
         "logData":"00000000000000000000000000000000000000000000000000000000000001f4",
         "loggedBy":"9526ec0e58ac5bb1e24d655e964f0eaa46054d16",
         "hasLogTopics":[
            "669a4b0ac0b9994c0f82ed4dbe07bb421fe74e5951725af4f139c7443ebf049d",
            "000000000000000000000000000000000000000000000000000000000000001f",
            "000000000000000000000000778ee4252b7e75380fad54caa30c0471568a4934",
            "000000000000000000000000d13e9b904c6e57ee929811f70db22cd308a56cf0"
         ],
         "eventDecoded":{
            "event":"",
            "inputs":[
               {
                  "indexed":true,
                  "name":"topic1",
                  "type":"raw",
                  "value":"000000000000000000000000000000000000000000000000000000000000001f"
               },
               {
                  "indexed":true,
                  "name":"topic2",
                  "type":"raw",
                  "value":"000000000000000000000000778ee4252b7e75380fad54caa30c0471568a4934"
               },
               {
                  "indexed":true,
                  "name":"topic3",
                  "type":"raw",
                  "value":"000000000000000000000000d13e9b904c6e57ee929811f70db22cd308a56cf0"
               },
               {
                  "name":"data0",
                  "type":"raw",
                  "value":"00000000000000000000000000000000000000000000000000000000000001f4"
               }
            ],
            "topic0":"0x669a4b0ac0b9994c0f82ed4dbe07bb421fe74e5951725af4f139c7443ebf049d"
         },
         "eventDecodedError":""
      }
   ],
   "status":200
}
```
{% endtab %}

{% tab title="404 Could not find any LogEntry matching the txHash" %}
```
{
    "data": null,
    "status": 404
}
```
{% endtab %}
{% endtabs %}

## Get account transactions

<mark style="color:blue;">`GET`</mark> `http://localhost:3000/api/explorer/account/:address/txs`

Returns a paginated list of transactions related to an account.

#### Path Parameters

| Name    | Type   | Description                |
| ------- | ------ | -------------------------- |
| address | string | The address of the account |

#### Query Parameters

| Name            | Type   | Description                                                                                                                  |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| limit           | number | How many transactions to return                                                                                              |
| txIndex         | number | Use together with `includedInBlock` to return transactions in the same block but with lower `txIndex`. Used as cursor.       |
| includedInBlock | number | Return all txs included in blocks with `number` lower than `includedInBlock` . To be used together with `txIndex` as cursor. |

{% tabs %}
{% tab title="200 Found transactions for the specified account." %}
```
{
   "data":[
      {
         "txHash":"9297079dd6dad3025ef7e2f2fdb69d7642391455b19b2ff5059fcb53faf361fc",
         "includedInBlock":1366204,
         "txIndex":3,
         "from":"d13e9b904c6e57ee929811f70db22cd308a56cf0",
         "to":"9526ec0e58ac5bb1e24d655e964f0eaa46054d16",
         "value":"0",
         "txGasUsed":"60037",
         "txGasPrice":"30000000000",
         "blockCreationTime":1569511615
      },
      {
         "txHash":"73c6e382c0b2351721d5311913d0b0635934c618c520fd2900cc255544c5b971",
         "includedInBlock":1366197,
         "txIndex":0,
         "from":"d13e9b904c6e57ee929811f70db22cd308a56cf0",
         "to":"62083c80353df771426d209ef578619ee68d5c7a",
         "value":"0",
         "txGasUsed":"45419",
         "txGasPrice":"30000000000",
         "blockCreationTime":1569511510
      },
      {
         "txHash":"688b547abb156adde0295e671a756a6286c3800d271d93413fd302121ef02a01",
         "includedInBlock":1366179,
         "txIndex":3,
         "from":"d13e9b904c6e57ee929811f70db22cd308a56cf0",
         "to":"9526ec0e58ac5bb1e24d655e964f0eaa46054d16",
         "value":"0",
         "txGasUsed":"60037",
         "txGasPrice":"30000000000",
         "blockCreationTime":1569511240
      }
   ],
   "status":200
}
```
{% endtab %}

{% tab title="404 Could not find any transaction matching the query." %}
```
{
    "data": null,
    "status": 404
}
```
{% endtab %}
{% endtabs %}

## Get account code

<mark style="color:blue;">`GET`</mark> `http://localhost:3000/api/explorer/account/:address/code`

Proxy endpoint. Queries the node for account's code and returns it.&#x20;

#### Path Parameters

| Name    | Type   | Description                |
| ------- | ------ | -------------------------- |
| address | string | The address of the account |

{% tabs %}
{% tab title="200 " %}
```
{
    "data": {
        "code": "60806040..."
    },
    "status": 200
}
```
{% endtab %}

{% tab title="400 Address is malformed." %}
```
{
    "data": "bad request: address is malformed",
    "status": 400
}
```
{% endtab %}
{% endtabs %}

## Get account balance

<mark style="color:blue;">`GET`</mark> `http://localhost:3000/api/explorer/account/:address/balance`

Proxy endpoint. Queries the node for account's latest balance and returns it.&#x20;

#### Path Parameters

| Name    | Type   | Description                |
| ------- | ------ | -------------------------- |
| address | string | The address of the account |

{% tabs %}
{% tab title="200 " %}
```
{
    "data": {
        "balance": "0"
    },
    "status": 200
}
```
{% endtab %}

{% tab title="400 Address is malformed" %}
```
{
    "data": "bad request: address is malformed",
    "status": 400
}
```
{% endtab %}
{% endtabs %}

## Search

<mark style="color:blue;">`GET`</mark> `http://localhost:3000/api/explorer/search/:query`

Accepts a 32 bytes hash (64 characters long hex or 66 if `0x`-prefixed) and returns the type of the entity if it matches anything.&#x20;

#### Path Parameters

| Name  | Type   | Description                                                   |
| ----- | ------ | ------------------------------------------------------------- |
| query | string | 32 bytes hash (64 characters long hex or 66 if `0x`-prefixed) |

{% tabs %}
{% tab title="200 Found a matching entity " %}
```
# hash matched a block
{
    "data": {
        "data": {
            "number": 1683030
        },
        "entity": "block"
    },
    "status": 200
}

# hash matched a tx
{
    "data": {
        "data": null,
        "entity": "tx"
    },
    "status": 200
}

#hash matched an uncle
{
    "data": {
        "data": null,
        "entity": "uncle"
    },
    "status": 200
}
```
{% endtab %}

{% tab title="400 Invalid query string" %}
```
{
    "data": "invalid request: invalid query string",
    "status": 400
}
```
{% endtab %}
{% endtabs %}
