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:
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
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 |
|
-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.

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
}