Massa JSON-RPC API

Through the API documentation, you can find out how to make calls and handle responses.

Massa JSON-RPC API is splitted in two parts:

Find the complete Massa OpenRPC specification here.

Note

We provide an Interactive API Specification which documents every available method and allows you to play with the API.

Warning

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: see massa-web3.js.

Postman: is a tool for software developers to create, test and debug API requests. More details can be found in Postman learning center. Find all maintained Massa Postman collections in our official workspace.

Massa RPC enpoints

Here are the public RPC endpoints currently available.

Name

Address

Features

Massa
JsonRPC

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 (for
example, malformed
request syntax,
invalid request
message framing, or
deceptive request
routing)
-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

Error example:

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

WebSockets support

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

Warning

  • 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 enable WS.
      {
    enable_ws = true

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

../_images/postman_websocket.png
  • 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
    }
    

TEST.23.0 .. note:

Multiple subscriptions are supported

Explore Massa Blockchain

In this section we’ll learn how to interact with Massa blockchain via curl commands which will create JSON-RPC request calls.

Warning

  • We’ll use only public API methods in testnet node.

Public API

a.k.a. user mode methods (running on https://test.massa.net/api/v2)

get_status

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

  • Query:

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

{
"jsonrpc": "2.0",
"result": {
    "node_id": "N1VRyXjUaHeJd4Rmr3waVmpZDFzzH5ARRi3f5ye5BYgxBmxHC7X",
    "node_ip": "141.94.218.103",
    "version": "TEST.23.0",
    "current_time": 1678095036319,
    "current_cycle": 201,
    "current_cycle_time": 1678094448000,
    "next_cycle_time": 1678096496000,
    "connected_nodes": {
        "N13Ykon8Zo73PTKMruLViMMtE2rEG646JQ4sCcee2DnopmVM3P5": [
            "51.75.60.228",
            false
        ],
        ...
        "N12v69D3R9DRQefDVMRuJv4nzkLTtvcoa42pWixZq3zJQPeSBGSh": [
            "46.4.76.149",
            true
        ]
    },
    "last_slot": {
        "period": 25764,
        "thread": 24
    },
    "next_slot": {
        "period": 25764,
        "thread": 25
    },
    "consensus_stats": {
        "start_timespan": 1678094976319,
        "end_timespan": 1678095036319,
        "final_block_count": 120,
        "stale_block_count": 0,
        "clique_count": 1
    },
    "pool_stats": [
        482673,
        1322
    ],
    "network_stats": {
        "in_connection_count": 18,
        "out_connection_count": 13,
        "known_peer_count": 10033,
        "banned_peer_count": 0,
        "active_node_count": 31
    },
    "execution_stats": {
        "time_window_start": 1678094976319,
        "time_window_end": 1678095036319,
        "final_block_count": 120,
        "final_executed_operations_count": 183229,
        "active_cursor": {
            "period": 25764,
            "thread": 20
        }
    },
    "config": {
        "genesis_timestamp": 1677682800000,
        "end_timestamp": 1680292800000,
        "thread_count": 32,
        "t0": 16000,
        "delta_f0": 1088,
        "operation_validity_periods": 10,
        "periods_per_cycle": 128,
        "block_reward": "0.30",
        "roll_price": "100",
        "max_block_size": 1000000
    }
},
"id": 1
}

get_cliques

Get information about the block cliques of the graph.

  • Query:

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

{
"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.

  • Query:

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

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

get_addresses

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

  • Query:

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

 {
"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_graph_interval

Get information about block graph within the specified time interval.

  • Query:

curl --location --request POST 'https://test.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}]
}'
  • Result:

{
"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) <https://docs.massa.net/en/latest/general-doc/architecture/archi-intro.html#block>__ associated to a given hash(s). - Query:

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

{
"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).

  • Query:

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

{
"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 …)

  • Query:

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

{
"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
}