# State

## Overview

State APIs provide access to the blockchain state and other database access and management functions. State functions can be accessed from the JSON-API endpoints and within the console environment.

## state\_getBranches

Returns a list of all known branches. 

**Parameters:** None

**Curl Example:** 

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBranches" ,"id":21}'
```

#### Console Example

```javascript
> state.getBranches()
```

#### Returns:

`Array<Object>`&#x20;

| Field             | Type                                                                                                                                    | Description                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| height            | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The height of the branch.                         |
| id                | String                                                                                                                                  | The unique branch ID.                             |
| isBranch          | Boolean                                                                                                                                 | Whether the chain is a branch.                    |
| length            | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The number of blocks in the branch.               |
| parentBlockHash   | String                                                                                                                                  | The hash of the block where the branch started.   |
| parentBlockNumber | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The number of the block where the branch started. |
| totalDifficulty   | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The total difficulty of the branch.               |
| timestamp         | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The unix time of creation of the branch.          |

#### Output:

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": [
      {
          "height": "0x1fdf",
          "id": "0xd64e1f13182149cf31a5654aca5df231bce538cf9bc466a919bcc6083d10a913",
          "timestamp": "0x1562c9ab49894e99",
          "totalDifficulty": "0x13048b3a00"
      },
      {
          "height": "0xb0",
          "id": "0x0a08d0a6dae1031f36390fad495072e2e4a243691e54103ead70a1eb7dc4e843",
          "isBranch": true,
          "length": "0x1",
          "parentBlockHash": "0x1c0c76ccfb63bc3aa4dcd096c8db51531529d5522b3a9d6dea93e2ad82cd8fe0",
          "parentBlockNumber": "0xaf",
          "timestamp": "0x1562cc956b3f41b0",
          "totalDifficulty": "0x68e77800"
      }
  ]
}
```

## state\_getBlock

Get a block by its number/height.&#x20;

**Parameters**

| Argument | Type    | Description        |
| -------- | ------- | ------------------ |
| number   | Integer | The block's number |

{% hint style="info" %}
Set number to **0** to return the most recent block on the main branch.
{% endhint %}

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBlock", "params": 2 ,"id":21}'
```

#### Console Example

```javascript
> state.getBlock(number)
```

#### Returns:

[`Block`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/block)&#x20;

#### Output:

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": {
    "hash": "0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659",
    "header": {
      "creatorPubKey": "48YQpehoRDYsivCbnedrz19DfTvh345PwWAKGN3jdUjPNdG3Lte",
      "difficulty": "0x989680",
      "extra": "0x",
      "nonce": "0x61879fb427b56cef",
      "number": "0x2",
      "parentHash": "0x211df3aed05b45d620850f40c9b4eac006da7ee0f76a7fa99d5ac16a2c2ca42c",
      "stateRoot": "0xc222870b2ca3f71d30b8d06b8e3f633812a8c0473cecc38b6fcc12eb5cad89ec",
      "timestamp": "0x5bda0ad4",
      "totalDifficulty": "0x1312d00",
      "transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000"
    },
    "sig": "0x3e001b22d640331fbf324138b6182ab851e2989319c37ec33044b5495cd86e2160ca0ca2291e66a06ed329a21f1acc7c1c5fa67d96d0b87f6aaec4892cfcac05",
    "transactions": []
  }
}
```

## state\_getBlockByHash

Get a block by its hash.&#x20;

**Parameters**

| Argument | Type   | Description      |
| -------- | ------ | ---------------- |
| hash     | String | The block's hash |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBlockByHash", "params": "0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659" ,"id":21}'
```

#### Console Example

```javascript
> state.getBlockByHash("0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659")
```

#### Returns:

[`Block`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/block)&#x20;

#### Output

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": {
    "hash": "0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659",
    "header": {
      "creatorPubKey": "48YQpehoRDYsivCbnedrz19DfTvh345PwWAKGN3jdUjPNdG3Lte",
      "difficulty": "0x989680",
      "extra": "0x",
      "nonce": "0x61879fb427b56cef",
      "number": "0x2",
      "parentHash": "0x211df3aed05b45d620850f40c9b4eac006da7ee0f76a7fa99d5ac16a2c2ca42c",
      "stateRoot": "0xc222870b2ca3f71d30b8d06b8e3f633812a8c0473cecc38b6fcc12eb5cad89ec",
      "timestamp": "0x5bda0ad4",
      "totalDifficulty": "0x1312d00",
      "transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000"
    },
    "sig": "0x3e001b22d640331fbf324138b6182ab851e2989319c37ec33044b5495cd86e2160ca0ca2291e66a06ed329a21f1acc7c1c5fa67d96d0b87f6aaec4892cfcac05",
    "transactions": []
  }
}
```

## state\_getMinedBlocks

Get information about blocks that were mined on the node.&#x20;

**Parameters**

| Argument      | Type    | Description                                                                                             |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| limit         | Integer | The maximum number of results to return (default: 25)                                                   |
| lastHash      | String  | <p>Forces the query to return results after the specified </p><p>block hash. Useful for pagination.</p> |
| creatorPubKey | String  | <p>Forces the query to return results for only blocks </p><p>created by a given public key.</p>         |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getMinedBlock", "params": { "limit": 1 } ,"id":21}'
```

#### Console Example

```javascript
> state.getMinedBlocks({ limit: 10 })
```

#### Returns

`Object`

| Field                | Type                                                                                                                                 | Description                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| **blocks**           | Array\<Object>                                                                                                                       | The slice of objects describing the blocks.         |
| blocks.creatorPubKey | String                                                                                                                               | The block creator's public key.                     |
| blocks.hash          | [S](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber)tring | The block's hash.                                   |
| blocks.number        | Integer                                                                                                                              | The block's number.                                 |
| blocks.timestamp     | Integer                                                                                                                              | The block's timestamp.                              |
| blocks.totalFees     | String                                                                                                                               | The total transaction fees from the block.          |
| blocks.txCount       | Integer                                                                                                                              | The number of transactions in the block.            |
| **hasMore**          | Boolean                                                                                                                              | Indicates that there are more results to be fetched |

#### Output:

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": {
    "blocks": [
      {
        "creatorPubKey": "48jQzKSZ5U1eH7azq7fjqsYCuT129cBMhByrjUQcfQjTTknkE3v",
        "hash": "0x8d51a2c86874744d5c690f1bc789b375d7671bf75a45e913339da16350574cba",
        "number": "0x9",
        "timestamp": 1552074221,
        "totalFees": "0",
        "txCount": 0
      },
      {
        "creatorPubKey": "48jQzKSZ5U1eH7azq7fjqsYCuT129cBMhByrjUQcfQjTTknkE3v",
        "hash": "0xcfcd98936bea3af39959216e6668c0f83c9aeb50f201cf975c26de7127fcd66d",
        "number": "0x8",
        "timestamp": 1552074202,
        "totalFees": "0",
        "txCount": 0
      }
    ],
    "hasMore": true
  }
}
```

## state\_getBestChain

Get the main chain&#x20;

**Parameters:** None

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getBestChain", "id":21}'
```

#### Console Example

```javascript
> state.getBestChain()
```

#### Returns:&#x20;

`Object`

| Field           | Type                                                                                                                                    | Description                   |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| id              | String                                                                                                                                  | The chain's unique ID.        |
| height          | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The height of chain.          |
| totalDifficulty | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The chain's total difficulty. |
| timestamp       | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The unix time of creation.    |

#### Output

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": {
    "height": "0x1fdf",
    "id": "0xd64e1f13182149cf31a5654aca5df231bce538cf9bc466a919bcc6083d10a913",
    "timestamp": "0x1562c9ab49894e99",
    "totalDifficulty": "0x13048b3a00"
  }
}
```

## state\_getOrphans

Get all known orphan blocks&#x20;

**Parameters:** None

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getOrphans", "id":21}'
```

#### Console Example

```javascript
> state.getOrphans()
```

#### Returns:&#x20;

`Array<`[`Block`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/block)`>`

#### Output

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": [
    {
      "hash": "0x67e62d1da7bf41a7e7667f9273eefe5255756d14e424a135ea543e4bbb40e659",
      "header": {
        "creatorPubKey": "48YQpehoRDYsivCbnedrz19DfTvh345PwWAKGN3jdUjPNdG3Lte",
        "difficulty": "0x989680",
        "extra": "0x",
        "nonce": "0x61879fb427b56cef",
        "number": "0x2",
        "parentHash": "0x211df3aed05b45d620850f40c9b4eac006da7ee0f76a7fa99d5ac16a2c2ca42c",
        "stateRoot": "0xc222870b2ca3f71d30b8d06b8e3f633812a8c0473cecc38b6fcc12eb5cad89ec",
        "timestamp": "0x5bda0ad4",
        "totalDifficulty": "0x1312d00",
        "transactionsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000"
      },
      "sig": "0x3e001b22d640331fbf324138b6182ab851e2989319c37ec33044b5495cd86e2160ca0ca2291e66a06ed329a21f1acc7c1c5fa67d96d0b87f6aaec4892cfcac05",
      "transactions": [...]
    }
  ]
}
```

## state\_getReOrgs

Get records of re-organization events&#x20;

**Parameters:** None

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getReOrgs", "id":21}'
```

#### Console Example

```javascript
> state.getReOrgs()
```

#### Returns:&#x20;

`Array<Object>`

| Field       | Type   | Description                                          |
| ----------- | ------ | ---------------------------------------------------- |
| mainChainID | String | The ID of the main chain before the re-org.          |
| reOrgLen    | Int    | The number of blocks involved in the reorganization. |
| branchID    | String | The unique branch ID.                                |
| branchLen   | Int    | The number of blocks in the branch.                  |
| timestamp   | Int    | The time of creation.                                |

#### Output

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": [      
     {
        "mainChainID": "0xd64e1f13182149cf31a5654aca5df231bce538cf9bc466a919bcc6083d10a913",
        "reOrgLen": 2,
        "branchID": "0x1429ab07a29f5f13b0b360803be463e160df113556313b24db6d90f5c686f53f",
        "branchLen": 2,
        "timestamp": 1541020805
      }
   ]
}
```

## state\_getAccount

Get an account

**Parameters:**&#x20;

| Argument | Type   | Description                              |
| -------- | ------ | ---------------------------------------- |
| address  | String | The address associated with the account. |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getAccount", "params": "eGzzf1HtQL7M9Eh792iGHTvb6fsnnPipad", "id":21}'
```

#### Console Example

```javascript
> state.getAccount("eGzzf1HtQL7M9Eh792iGHTvb6fsnnPipad")
```

#### Returns:&#x20;

[`Account`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/account)

#### Output

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": {
    "address": "eGzzf1HtQL7M9Eh792iGHTvb6fsnnPipad",
    "balance": "100.000000000000000000",
    "nonce": 0,
    "type": 0
  }
}
```

## state\_listAccounts

List all accounts

**Parameters:** None

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_listAccounts", "id":21}'
```

#### Console Example

```javascript
> state.listAccounts()
```

#### Returns:&#x20;

`Array<`[`Account`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/account)`>`

#### Output

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": [
    {
      "address": "e27wBivep3B7XXJWsLhdur5Zq7qvYW8m8c",
      "balance": "100.000000000000000000",
      "nonce": 0,
      "type": 0
    },
    {
      "address": "e27uMdGs5w8vXPJFfGyeFb7ikJTaNThjSV",
      "balance": "100.000000000000000000",
      "nonce": 0,
      "type": 0
    }
  ]
}
```

## state\_listTopAccounts

List accounts ordered by their balance in descending order.

**Parameters:**&#x20;

| Argument | Type | Description                      |
| -------- | ---- | -------------------------------- |
| limit    | Int  | The number of accounts to return |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_listTopAccounts", "params": 10, "id":21}'
```

#### Console Example

```javascript
> state.listTopAccounts(10)
```

#### Returns:&#x20;

`Array<`[`Account`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/account)`>`

#### Output

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": [
    {
      "address": "e27wBivep3B7XXJWsLhdur5Zq7qvYW8m8c",
      "balance": "100.000000000000000000",
      "nonce": 0,
      "type": 0
    },
    {
      "address": "e27uMdGs5w8vXPJFfGyeFb7ikJTaNThjSV",
      "balance": "100.000000000000000000",
      "nonce": 0,
      "type": 0
    }
  ]
}
```

## state\_getAccountNonce

Get the current nonce of an account

**Parameters:**&#x20;

| Argument | Type   | Description                |
| -------- | ------ | -------------------------- |
| address  | String | The address of the account |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getAccountNonce", "params": "e2fFNsXAoyzsYQeopt7PRk3KpKj46nYgvB", "id":21}'
```

#### Console Example

```javascript
> state.getAccountNonce("e2fFNsXAoyzsYQeopt7PRk3KpKj46nYgvB")
```

#### Returns:&#x20;

`Integer`

#### Output

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": 2
}
```

## state\_getTransaction

Get a transaction by its hash

**Parameters:**&#x20;

| Argument | Type   | Description            |
| -------- | ------ | ---------------------- |
| hash     | String | The transaction's hash |

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getTransaction", "params": "0xf91be74146afb8717834f70969d02edff4316508dc62ec8716104968391fc492", "id":21}'
```

#### Console Example

```javascript
> state.getTransaction("0xf91be74146afb8717834f70969d02edff4316508dc62ec8716104968391fc492")
```

#### Returns:&#x20;

[`Transaction`](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/transaction)

#### Output

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": {
    "fee": "0",
    "from": "eNGGuhVSrXWWFYmVQBid9hFhiNLAfvPwzS",
    "hash": "0xf91be74146afb8717834f70969d02edff4316508dc62ec8716104968391fc492",
    "nonce": "0x0",
    "senderPubKey": "497a8Z5sTvCgFZYyQQ8Uh3tgm726uPBzM4v3fNpcygevyCcTJf6",
    "sig": "0xe579837d73b45af9cc9e381cfe7009106c5ea6c65a22356a61103e9724b92bbb8a7243a4765d28d9e2aa89d34df585efc08c07fff9eb4a649f60f03f3310890e",
    "timestamp": "0x5bcc82b7",
    "to": "eGzzf1HtQL7M9Eh792iGHTvb6fsnnPipad",
    "type": "0x2",
    "value": "100"
  }
}
```

## state\_getDifficulty

Get the current difficulty and total difficulty of the main chain.

**Parameters:** None

**Curl Example:**&#x20;

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"state_getDifficulty", "id":21}'
```

#### Console Example

```javascript
> state.getDifficulty()
```

#### Returns:&#x20;

`Object`

| Field           | Type                                                                                                                                    | Description                             |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| difficulty      | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The current difficulty.                 |
| totalDifficulty | [HexNumber](https://ellcrys.gitbook.io/ellcrys/~/edit/drafts/-LPGzTZQXM_D8Pctq4-D/v/master/object-references/hex-value-types#hexnumber) | The total difficulty of the main chain. |

#### Output

```javascript
{
  "id": 21,
  "jsonrpc": "2.0",
  "result": {
    "difficulty": "0x98fdea",
    "totalDifficulty": "0x13048b3a00"
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ellcrys.gitbook.io/ellcrys/api/state-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.