Massa JSON-RPC API

The JsonRPC API allows you to communicate with the Massa blockchain.

The Massa JSON-RPC API is split into two parts:

Private API: used for node management. Default port: 33034 e.g. http://localhost:33034
Public API: used for blockchain interactions. Default port: 33035 e.g. http://localhost:33035

The complete Massa OpenRPC specification is available here.

The Interactive API Specification documents every available method and allows you to play with the API.

info

Massa has a new experimental API with both Http and WebSocket support: Default port: 33036

Http: used for node management and blockchain interactions. e.g. http://localhost:33036
WebSocket: used for streaming blockchain events. e.g. ws://localhost:33036 :::

Integrations

JavaScript: The massa-web3 TypeScript library can be used to call the JSON-RPC API... and much more.
Postman: You can find our Massa Postman collections on our official workspace.

Explore the Blockchain

In this section we'll learn how to interact with Massa blockchain using the public API via cURL commands which will create JSON-RPC request calls.

get_status

Summary of the current state: time, last final blocks (hash, thread, slot, timestamp), clique count, connected nodes count.

cURL (Mainnet)
cURL (Buildnet)

curl --location --request POST 'https://mainnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_status",
    "params": []
}'

curl --location --request POST 'https://buildnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_status",
    "params": []
}'

Example response:

{
  "jsonrpc": "2.0",
  "result": {
    "node_id": "N1VRyXjUaHeJd4Rmr3waVmpZDFzzH5ARRi3f5ye5BYgxBmxHC7X",
    "node_ip": "141.94.218.103",
    "version": "SECU.27.0",
    "current_time": 1699881695772,
    "current_cycle": 208,
    "current_cycle_time": 1699879784000,
    "next_cycle_time": 1699881832000,
    "connected_nodes": {
      "N13Ykon8Zo73PTKMruLViMMtE2rEG646JQ4sCcee2DnopmVM3P5": [
        "::ffff:51.75.60.228",
        false
      ],
      "N1XxexKa3XNzvmakNmPawqFrE9Z2NFhfq1AhvV1Qx4zXq5p1Bp9": [
        "::ffff:158.69.23.120",
        false
      ],
      "N1qxuqNnx9kyAMYxUfsYiv2gQd5viiBX126SzzexEdbbWd2vQKu": [
        "::ffff:198.27.74.5",
        false
      ],
      "N12UbyLJDS7zimGWf3LTHe8hYY67RdLke1iDRZqJbQQLHQSKPW8j": [
        "::ffff:149.202.86.103",
        false
      ],
      "N12rPDBmpnpnbECeAKDjbmeR19dYjAUwyLzsa8wmYJnkXLCNF28E": [
        "::ffff:158.69.120.215",
        false
      ],
      "N12vxrYTQzS5TRzxLfFNYxn6PyEsphKWkdqx2mVfEuvJ9sPF43uq": [
        "::ffff:149.202.89.125",
        false
      ]
    },
    "last_slot": {
      "period": 26743,
      "thread": 15
    },
    "next_slot": {
      "period": 26743,
      "thread": 16
    },
    "consensus_stats": {
      "start_timespan": 1699881635772,
      "end_timespan": 1699881695772,
      "final_block_count": 121,
      "stale_block_count": 0,
      "clique_count": 1
    },
    "pool_stats": [0, 96],
    "network_stats": {
      "in_connection_count": 6,
      "out_connection_count": 0,
      "known_peer_count": 7,
      "banned_peer_count": 0,
      "active_node_count": 6
    },
    "execution_stats": {
      "time_window_start": 1699881635772,
      "time_window_end": 1699881695772,
      "final_block_count": 121,
      "final_executed_operations_count": 0,
      "active_cursor": {
        "period": 26743,
        "thread": 11
      },
      "final_cursor": {
        "period": 26741,
        "thread": 14
      }
    },
    "config": {
      "genesis_timestamp": 1699453800000,
      "end_timestamp": null,
      "thread_count": 32,
      "t0": 16000,
      "delta_f0": 1088,
      "operation_validity_periods": 10,
      "periods_per_cycle": 128,
      "block_reward": "1.02",
      "roll_price": "100",
      "max_block_size": 300000
    }
  },
  "id": 1
}

get_cliques

Get information about the block cliques of the graph.

cURL (Mainnet)
cURL (Buildnet)

curl --location --request POST 'https://mainnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_cliques",
    "params": []
}'

curl --location --request POST 'https://buildnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_cliques",
    "params": []
}'

Example response:

{
    "jsonrpc": "2.0",
"result": [
    {
        "block_ids": [
            "B12RHJKyPx8DdGHMevdP8Uyxidcg3nThb9XEnHXEJR7cbBi6JrR9",
            ...
            "B12c7xPkmdy3qbAF1rWn7XeTBdum6VHbYJiW5MUuyBGnshrf5NW8"
        ],
        "fitness": 1117,
        "is_blockclique": true
    }
],
"id": 1
}

get_stakers

Get information about active stakers and their roll counts for the current cycle.

cURL (Mainnet)
cURL (Buildnet)

curl --location --request POST 'https://mainnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_stakers",
    "params": [ {"offset": 0, "limit": 2 }]
}'

curl --location --request POST 'https://buildnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_stakers",
    "params": [ {"offset": 0, "limit": 2 }]
}'

Example response:

{
  "jsonrpc": "2.0",
  "result": [
    ["AU12gAkmGeozFceJD4tQmbVvihYdX2KyWZcYLL8xdYZeP4EuWYdex", 145],
    ["AU18A67vpbjHPq7KgFnMbezoJuGcjVLZsF4ybx4rEbnA3wZ1Gy7c", 124]
  ]
}

get_addresses

Get information about address (es) (balances, block creation, ...).

Starting with MAIN.5.1, the final_datastore_keys and candidate_datastore_keys fields list at most max_datastore_keys_query keys each (500 on the default configuration, reported by get_status). Keys beyond the cap are left out silently, without error. Earlier releases listed every datastore key of the address.

To list the keys of an address, use get_addresses_datastore_keys, which supports prefix filtering and pagination. :::

cURL (Mainnet)
cURL (Buildnet)

curl --location --request POST 'https://mainnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_addresses",
    "params": [["AU12gAkmGeozFceJD4tQmbVvihYdX2KyWZcYLL8xdYZeP4EuWYdex"]]
}'

curl --location --request POST 'https://buildnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_addresses",
    "params": [["AU12gAkmGeozFceJD4tQmbVvihYdX2KyWZcYLL8xdYZeP4EuWYdex"]]
}'

Example response:

{
    "jsonrpc": "2.0",
"result": [
    {
        "address": "AU12gAkmGeozFceJD4tQmbVvihYdX2KyWZcYLL8xdYZeP4EuWYdex",
       "thread": 27,
       "final_balance": "153.519945908",
       "final_roll_count": 145,
       "final_datastore_keys": [],
       "candidate_balance": "153.755240036",
       "candidate_roll_count": 145,
       "candidate_datastore_keys": [],
       "deferred_credits": [],
       "next_block_draws": [
           {
               "period": 25784,
               "thread": 5
           },
           ...
           {
               "slot": {
                   "period": 25791,
                   "thread": 29
               },
               "index": 1
           }
       ],
       "created_blocks": [
           "B12Y4eqmeJ5uWakcgZXRqDxRzFstKt8KJd2MgMSysqcMX4eWoaw4",
           "B12CANhVvuBpXtjyVS5kkZBGmw5wanvEuuF34ct3GABHLLAMroxT",
           "B122nYsgcJ72Cor9RcZB6ZGduc4pFm97srfGEPiijeZq9k1VatBS",
           "B12TC646QjDoQWAPuAYhsy9i8f3qdzajFas25eJsRXaj1mbBhGRk",
           "B12aFhukUBCz8TXJK5SakyT6MW18GTFNiRoeUKqzXT6e2ePbutor"
       ],
       "created_operations": [],
       "created_endorsements": [
           "E12uK8JkAkMpC5gDXaa26Vxvu8nRL5ZvD61WFjToeyTDVexnzYcH",
           ...
           "E12XbfbSzPvVRyW1mGhxBpkrDBzVdGdZvRkaYpDbrUP96fCZteSy"
       ],
       "cycle_infos": [
           {
               "cycle": 197,
               "is_final": true,
               "ok_count": 48,
               "nok_count": 0,
               "active_rolls": null
           },
           ...
           {
               "cycle": 201,
               "is_final": false,
               "ok_count": 11,
               "nok_count": 0,
               "active_rolls": 145
           }
       ]
   }
],
"id": 1
}

get_addresses_datastore_keys

Available from versions MAIN.4.0 for Mainnet / DEVN.29.0 for Buildnet.

Retrieve datastore keys for given addresses.

Parameters

Field	Type	Mandatory	Default	Description
`address`	`string`	Yes	N/A	The blockchain address for which to retrieve datastore keys.
`prefix`	`array<integer>`	Yes	`[]`	A prefix to filter the datastore keys (bytes represented as array of integers).
`is_final`	`boolean`	Yes	`true`	Whether to retrieve keys from the final state of the blockchain.
`start_key`	`array<integer>`	No	`null`	The key to start filtering from (inclusive by default). Bytes as array of integers.
`inclusive_start_key`	`boolean`	No	`true`	Include or exclude the start_key.
`end_key`	`array<integer>`	No	`null`	The key to end filtering at (inclusive by default). Bytes as array of integers.
`inclusive_end_key`	`boolean`	No	`true`	Include or exclude the end_key.
`count`	`integer`	No	`500`	The maximum number of keys to retrieve. Cannot exceed the node's configured cap (`500` on the default configuration); a higher value is rejected with an error.

caution

The result is capped and truncated silently.

Starting with MAIN.5.1, omitting count defaults it to the node's maximum (500 on the default configuration). Earlier releases documented the same default but did not enforce it, and returned every matching key instead. The node reports its maximum in the max_datastore_keys_query field of get_status (null when it applies no cap).

The response carries no indicator that keys were left out: a truncated result is indistinguishable from a complete one. An address holding more keys than the cap therefore returns a partial list rather than an error.

If you need every key, paginate as shown below, or use getStorageKeys from massa-web3 5.3.0 or later, which paginates internally.

Pagination

Keys are returned in ascending lexicographic byte order. To read a full range, request pages of count keys and start each page just after the last key of the previous one, by passing it as start_key with inclusive_start_key set to false:

const PAGE_SIZE = 500 // must not exceed the node's cap
let startKey = null
const keys = []

for (;;) {
  const [res] = await rpc('get_addresses_datastore_keys', [[{
    address,
    prefix,
    is_final: true,
    start_key: startKey,
    // the start key was already returned by the previous page
    inclusive_start_key: startKey ? false : null,
    end_key: null,
    inclusive_end_key: null,
    count: PAGE_SIZE,
  }]])

  if (res.keys.length === 0) break
  keys.push(...res.keys)
  // a short page means the end of the range has been reached
  if (res.keys.length < PAGE_SIZE) break
  startKey = res.keys[res.keys.length - 1]
}

cURL (Mainnet)
cURL (Buildnet)

curl --location --request POST 'https://mainnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_addresses_datastore_keys",
    "params": [
        [
            {
                "address": "AS1iBwn89sM1GsTRu7PCK1DuYqZ7ckuF7M9gM1Ybx7rpzMw2tKc1",
                "prefix": [107],
                "is_final": true,
                "start_key": [107,101,121,49],
                "inclusive_start_key": true,
                "end_key": [107,101,121,51],
                "inclusive_end_key": false,
                "count": 10
            }
        ]
    ]
}'

curl --location --request POST 'https://buildnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_addresses_datastore_keys",
    "params": [
        [
            {
                "address": "AS1iBwn89sM1GsTRu7PCK1DuYqZ7ckuF7M9gM1Ybx7rpzMw2tKc1",
                "prefix": [107],
                "is_final": true,
                "start_key": [107,101,121,49],
                "inclusive_start_key": true,
                "end_key": [107,101,121,51],
                "inclusive_end_key": false,
                "count": 10
            }
        ]
    ]
}'

Example response:

{
    "jsonrpc": "2.0",
    "result": [
        {
            "address": "AS12KMSMMARaHNZYkWeUSBE9JrjBPSQr6q7NXHGDoGweCrdNkHELj",
            "is_final": true,
            "keys": [
              [107,101,121,49],
              [107,101,121,50]
            ]
        }
    ],
    "id": 1
}

get_graph_interval

Get information about block graph within the specified time interval.

cURL (Mainnet)
cURL (Buildnet)

curl --location --request POST 'https://mainnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_graph_interval",
    "params": [{"start": 1678095527706, "end": 1678095529706}]
}'

curl --location --request POST 'https://buildnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_graph_interval",
    "params": [{"start": 1678095527706, "end": 1678095529706}]
}'

Example response:

{
    "jsonrpc": "2.0",
"result": [
    {
        "id": "B1pd4hCpPnHM8QMvKp9uGM5sdUZoq6s9wERwk7z9ANoo8FSTJ7j",
        "is_final": false,
        "is_stale": false,
        "is_in_blockclique": true,
        "slot": {
            "period": 25795,
            "thread": 17
        },
        "creator": "AU12tr8pSnamJRQEdm4K9DaogpdANXF636XNV13iNHAL6bLpKxooR",
        "parents": [
            "B12echxHFVHsCsWaRxL5pxPmYtefjhuJDNtd7TX6iseF6jxdyZnS",
            ...
            "B12WQuyYopKPLkK9HF2eRaJDRbnE2cAhqT19XpGT2gMh9o4E2BrL"
        ]
    },
    {
        "id": "B12G3GVLNct669ZiAQQDsXW9Mbo5PHtmwrEKNAvnBVa11kqqps5n",
        "is_final": false,
        "is_stale": false,
        "is_in_blockclique": true,
        "slot": {
            "period": 25795,
            "thread": 16
        },
        "creator": "AU1LJYrJQiQZYqiktgrbb5MWgSnd1FuUQqhQsw48PPdrAB3uqLCS",
        "parents": [
            "B12echxHFVHsCsWaRxL5pxPmYtefjhuJDNtd7TX6iseF6jxdyZnS",
            ...
            "B12WQuyYopKPLkK9HF2eRaJDRbnE2cAhqT19XpGT2gMh9o4E2BrL"
        ]
    },
    {
        "id": "B12RYZz9S8PuqWvQUFStxmTDb4j3UqfVEkNqeBwYDvwCrnzBMJ8J",
        "is_final": false,
        "is_stale": false,
        "is_in_blockclique": true,
        "slot": {
            "period": 25795,
            "thread": 18
        },
        "creator": "AU1vWZXTD4YdfdbqWS3RRgnH5DBdJSfgwVi9vJztH2V3iNMakzKo",
        "parents": [
            "B12echxHFVHsCsWaRxL5pxPmYtefjhuJDNtd7TX6iseF6jxdyZnS",
            ...
            "B12WQuyYopKPLkK9HF2eRaJDRbnE2cAhqT19XpGT2gMh9o4E2BrL"
        ]
    }
],
"id": 1
}

get_blocks

Get information about block(s) associated to a given hash(s).

cURL (Mainnet)
cURL (Buildnet)

curl --location --request POST 'https://mainnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_blocks",
    "params": [["B122ByHzPVJ3QFwmuYcZ4vZYzq6rfkqx7BJSJdFNHWp9j2o5Fpxv"]]
}'

curl --location --request POST 'https://buildnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_blocks",
    "params": [["B122ByHzPVJ3QFwmuYcZ4vZYzq6rfkqx7BJSJdFNHWp9j2o5Fpxv"]]
}'

Example response:

{
    "jsonrpc": "2.0",
"result": [
    {
        "id": "B122ByHzPVJ3QFwmuYcZ4vZYzq6rfkqx7BJSJdFNHWp9j2o5Fpxv",
        "content": {
            "is_final": true,
            "is_in_blockclique": false,
            "is_candidate": false,
            "is_discarded": false,
            "block": {
                "header": {
                    "content": {
                        "slot": {
                            "period": 25787,
                            "thread": 4
                        },
                        "parents": [
                            "B12L3Cvj8EZiX6sCryti4fqZ3nZ4tbDiYjtyAxVoYfJUxfPuN2Lm",
                            ...
                            "B1xMgVk5hcp8qdFzvCeG3SqS3AA4i52fAXw7kZn4DzJWnXGgZDW"
                        ],
                        "operation_merkle_root": "8uJok77DvcHgdzqzMQ62yu6nV9tKqTU6JhsCtvWxBK6VsabSZ",
                        "endorsements": [
                            {
                                "content": {
                                    "slot": {
                                        "period": 25787,
                                        "thread": 4
                                    },
                                    "index": 0,
                                    "endorsed_block": "B1PF5E4D3LKa6soJ8BXv6nveHFHRPzBYtqysVWhLZT5fmnedc6T"
                                },
                                "signature": "V21cLHbr5mUzpRrRHc66EkvsDh5KZHvWKfFhFo2B2ni9qVK9p8nhPuE14btaWXAN7ru4d7q7jm9TcW55McXd2smhd6NbP",
                                "content_creator_pub_key": "P1bi78ormwmdSYuvmk77ZbQsyz4VDqEZZGKnXVWyksJYitx6nwJ",
                                "content_creator_address": "AU12ta1W4CcLrQmBAYEc7BPCopj8zqyJzBmFncYcXQQw2N2M5SC6U",
                                "id": "E1KLYEDm4qBUxi1SDHo3tf3dCGJ5kDYL3w8N766KgnYZV6A7omy"
                            },
                            ...
                            {
                                "content": {
                                    "slot": {
                                        "period": 25787,
                                        "thread": 4
                                    },
                                    "index": 15,
                                    "endorsed_block": "B1PF5E4D3LKa6soJ8BXv6nveHFHRPzBYtqysVWhLZT5fmnedc6T"
                                },
                                "signature": "E3HGbZvJEPVZcRUYDUpnk4R8t9p941MKZTK3awTXTMpG1pufThBu9CpNd7YDW1mkEc4ZJB31Hcvp8cKVPe57MBUJutu1c",
                                "content_creator_pub_key": "P123qyM3ZzUw5Mi7uxj8mKYNHo7H7ybTQWZy53cR7BHhXbTxrT8z",
                                "content_creator_address": "AU1Xr8m6utu6DBXyRCFGrD2jPCa62tnwNwkkJSCnh4iWQG3M63za",
                                "id": "E12rQSKKLw1wXBXajvjGS9PB8NYEhuDf2TxKgQ7PfAccEff51QyM"
                            }
                        ]
                    },
                    "signature": "4vKvfytWkgv5YjTQQiVwADpBMpvAF6W79KBHzAs1iybLswUZ2VhWPh6dMTnifVeiBYXVJuvgcMkKkRH8VjL2izkRVTAxs",
                    "content_creator_pub_key": "P1snABBASHQQuCDERNdUBzg2kJ37LLFK8L7sgBoBd32mRU38ev9",
                    "content_creator_address": "AU1WqP6GTsR8w4eyRPHQkrQhujmRb3hmLaQt3HZfeTVHWVZade48",
                    "id": "B122ByHzPVJ3QFwmuYcZ4vZYzq6rfkqx7BJSJdFNHWp9j2o5Fpxv"
                },
                "operations": [
                    "O116jye7zBAttWHfCufcMVQEQaa9JMTqv6To5mE2CzmzBs7cZ7W",
                    ...
                    "O12we35pSQhP8i31B2i9wXRNgfkFMCN7CUGgF2HCoRj1XB3LXUNw"
                ]
            }
        }
    }
],
"id": 1
}

get_operations

Get information about operation (s) information associated to a given operation(s) ID(s).

cURL (Mainnet)
cURL (Buildnet)

curl --location --request POST 'https://mainnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_operations",
    "params": [["O1LMr9xyL9fVSbUvZao4jy6t2Pj5UPtLG8x1fxvS6SD7dPb5S52"]]
}'

curl --location --request POST 'https://buildnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_operations",
    "params": [["O1LMr9xyL9fVSbUvZao4jy6t2Pj5UPtLG8x1fxvS6SD7dPb5S52"]]
}'

Example response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "id": "O1LMr9xyL9fVSbUvZao4jy6t2Pj5UPtLG8x1fxvS6SD7dPb5S52",
      "in_pool": true,
      "in_blocks": ["B1CM6E6CcSvFtXD1VHhVezt9CvpUGsB7TcSh3Z9k1HW6J3zLDyP"],
      "is_operation_final": false,
      "thread": 8,
      "operation": {
        "content": {
          "fee": "0",
          "expire_period": 25824,
          "op": {
            "Transaction": {
              "recipient_address": "AU12WQRoxQJKMjNG8hVjkyh4YgBwaYeUH4BsqJEEdTUJda37GhSx9",
              "amount": "0.000600754"
            }
          }
        },
        "signature": "D3JUUhPiQTDvdYKa4Gv38xUNSpfHbYUU9qsw3rLypwZdjbniVdmHn15VnaF1NDrmSqUPf6UFs5xpDmid3xzmMqoXBV83",
        "content_creator_pub_key": "P1YSCrgzD8QXQCmMUEqrGvroBsu9UMCbWJUgCUnW3txDyFajBW5",
        "content_creator_address": "AU1Y6Zhw2GWt2ETWxyym3GnJSv4ZW3rXRQVxcLUDprB3ybr5LKAq",
        "id": "O1LMr9xyL9fVSbUvZao4jy6t2Pj5UPtLG8x1fxvS6SD7dPb5S52"
      },
      "op_exec_status": true
    }
  ],
  "id": 1
}

get_endorsements

Get information about endorsement (s) (content, finality ...)

cURL (Mainnet)
cURL (Buildnet)

curl --location --request POST 'https://mainnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_endorsements",
    "params": [["E12kB72Jz4iMWkVkckS2e6cUBm4e5XEW77biDjSysAWmQkNrvuJr"]]
}'

curl --location --request POST 'https://buildnet.massa.net/api/v2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_endorsements",
    "params": [["E12kB72Jz4iMWkVkckS2e6cUBm4e5XEW77biDjSysAWmQkNrvuJr"]]
}'

Example response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "id": "E12kB72Jz4iMWkVkckS2e6cUBm4e5XEW77biDjSysAWmQkNrvuJr",
      "in_pool": false,
      "in_blocks": ["B1CM6E6CcSvFtXD1VHhVezt9CvpUGsB7TcSh3Z9k1HW6J3zLDyP"],
      "is_final": true,
      "endorsement": {
        "content": {
          "slot": {
            "period": 25817,
            "thread": 8
          },
          "index": 6,
          "endorsed_block": "B17nShoffS6PVyB1qZQSgLmgWvczzPDinhkcHWUxWP2q9fg646A"
        },
        "signature": "H6bsbwfUwkyMYdKU7vdWdft61bCacYPv77Gsxmp9rng7wTZSRYjuqXi6uy5eFwh8qM9iggRAabumbv4ZT9ChC42ZVYeuK",
        "content_creator_pub_key": "P12KNCqp2tSrQtFBF8wUxDJ1aSdrvyqg6UPShhXUVSWA9udJFcfV",
        "content_creator_address": "AU1AZf2B9Cn3V7zSvoCm7Egdi5ZUx5m35sADYHcPujHsb2fLPQXs",
        "id": "E12kB72Jz4iMWkVkckS2e6cUBm4e5XEW77biDjSysAWmQkNrvuJr"
      }
    }
  ],
  "id": 1
}

WebSockets support

In this section we'll learn how to enable and subscribe to WebSockets via Postman client.

caution

Experimental support for WebSocket is a feature that is subject to change in a future releases.

Available subscriptions:

subscribe_new_blocks/unsubscribe_new_blocks: subscribe/unsubscribe to/from new produced blocks.
subscribe_new_blocks_headers/unsubscribe_new_blocks_headers: subscribe/unsubscribe to/from new produced blocks headers.
subscribe_new_filled_blocks/unsubscribe_new_filled_blocks: subscribe/unsubscribe to/from new produced filled blocks with operations content.
subscribe_new_operations/unsubscribe_new_operations: subscribe/unsubscribe to/from new produced operations.

To enable WebSocket support in Massa node, edit file massa-node/config/config.toml (create it if absent) with the following contents:

[api]
   # whether to broadcast for blocks, endorsement and operations
   enable_broadcast = true
   # whether to enable WS.
   enable_ws = true

Postman brings support for WebSocket APIs, more information about it here.

run the massa node
connect to ws://localhost:33036
send the request message:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe_new_filled_blocks",
  "params": []
}

If the request succeed, the response will contains a subscription id:

{
  "jsonrpc": "2.0",
  "result": 3508678639232691,
  "id": 1
}

Result:

{
  "jsonrpc": "2.0",
  "method": "new_filled_blocks",
  "params": {
    "subscription": 3508678639232691,
    "result": "FILLED_BLOCK_CONTENT_0"
  }
}

A message is received everytime a filled block is produced:

{
  "jsonrpc": "2.0",
  "method": "new_filled_blocks",
  "params": {
    "subscription": 3508678639232691,
    "result": "FILLED_BLOCK_CONTENT_N"
  }
}

unsubscribe and stop receiving new filled blocks:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "unsubscribe_new_filled_blocks",
  "params": [3508678639232691]
}

Result:

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 1
}

note

Multiple subscriptions are supported

Error codes

When a call to Massa API fails, it MUST return a valid JSON-RPC error object.

Code	Message	Meaning
-32600	Invalid request	The JSON sent is not a valid Request object
-32601	Method not found	The method does not exist / is not available
-32602	Invalid params	Invalid method parameter(s)
-32603	Internal error	Internal JSON-RPC error
-32700	Parse error	Invalid JSON, parsing issue
-32000	Bad request	Indicates that the server cannot or will not process the request due to something that is perceived to be a client error
-32001	Internal server error	The server encountered an unexpected issue
-32003	Service Unavailable	Indicates that the server is not ready to handle the request
-32004	Not found	Indicates that the server cannot find the requested resource
-32005	Method not allowed	Indicates that the server knows the request method, but the target resource doesn't support this method
-32006	Send channel error	Send channel error
-32007	Receive channel error	Receive channel error
-32008	Massa hash error	`massa_hash` error
-32009	Consensus error	Error from Consensus module
-32010	Execution error	Error from Execution module
-32012	Protocol error	Error from Protocol module
-32013	Models error	Error in Models
-32014	Time error	Error from Time module
-32015	Wallet error	Error from Wallet module
-32016	Inconsistency error	Inconsistency in the result of request
-32017	Missing command sender	Missing command sender
-32018	Missing config	Missing configuration
-32019	Wrong API	The wrong API (either Public or Private) was called

Example error:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32400,
    "message": "Bad request: too many arguments, maximum authorized 2 but found 3"
  },
  "id": 1
}

Massa JSON-RPC API

Integrations​

Explore the Blockchain​

get_status​

get_cliques​

get_stakers​

get_addresses​

get_addresses_datastore_keys​

Parameters​

Pagination​

get_graph_interval​

get_blocks​

get_operations​

get_endorsements​

WebSockets support​

Error codes​

Integrations

Explore the Blockchain

get_status

get_cliques

get_stakers

get_addresses

get_addresses_datastore_keys

Parameters

Pagination

get_graph_interval

get_blocks

get_operations

get_endorsements

WebSockets support

Error codes