JSON-RPC

Overview
The Radix Node API uses the JSON-RPC 2.0 specification to encode its messages. The following subsections describe the contents of the JSON messages that follow this spec.
For further reference check the official JSON-RPC 2.0 specification.
Request
An RPC call is represented by sending a request message to the node. The request message has the following members:
id: A unique identifier established by the client that contains a string or number. The server must reply with the same value in the response message. This member is used to correlate the context between both messages.
method: A string containing the name of the method to be invoked.
params: A structured value that holds the parameter values to be used during the invocation of the method.
You can find request examples for each API method in the next section.
Successful response
When an RPC call is made, the server replies with a response message. In case of a successful response, the response message will contain the following members:
jsonrpc: A string specifying the version of the JSON-RPC protocol. It must be 2.0.
id: Must match the value of the id member in the request message.
result: Its value is determined by the method invoked on the server.
You can find successful response examples in the API methods section.
Error response
When an RPC call is made, the server replies with a response message. In case of an error response, the response message will contain the following members:
jsonrpc: A string specifying the version of the JSON-RPC protocol. It must be 2.0.
id: Must match the value of the id member in the request message. If there was an error in detecting the id in the request message (e.g. Parse Error/Invalid Request), id is null.
error: A message describing the error through the following members:
code: An integer number that indicates the error type that occurred.
message: A string providing a short description of the error.
The following example shows a typical error response:
{
    "error": {
        "code": -32601,
        "message": "Method not found"
    },
    "id": 0,
    "jsonrpc": "2.0"
}
Websockets support
Method
HTTP (POST)
WebSockets
Atom Subscribe
​❌ 
​✅ 
Atom Cancel Subscription
​❌ 
​✅ 
Close Atom Status Notifications
​❌ 
​✅ 
Get Atom Status Notifications
​❌ 
​✅ 
Get Live Peers
​✅ 
​✅ 
Get Peers
​✅ 
​✅ 
Get Info
​✅ 
​✅ 
Get Universe
​✅ 
​✅ 
Submit Atom
​✅ 
​✅ 
API methods
Atom Subscribe
This methods subscribes to Atom(s) updates.
Request
Response
Request
Endpoint
Websocket
wss://[node IP]/rpc
Headers
Header
Value
Content-Type
application/json
Body parameters
{
  "method": "Atoms.subscribe",
  "params": {
    "subscriberId": "<Subscriber_ID>",
    "query": {
      "address": "a Radix address",
    }
  },
  "id": 0
}
Response
Atoms.subscribeUpdate:
{
    "subscriberId": number
    "atoms": any[],
    "isHead": boolean
}
Atom Cancel Subscription
This method cancels a previous subscription to an Atom update.
Request
Response
Request
Endpoint
Websocket
wss://[node IP]/rpc
Headers
Header
Value
Content-Type
application/json
Body parameters
{
  "method": "Atoms.cancel",
  "params": {
    "subscriberId": "<Subscriber_ID>"
  },
  "id": 0
}
Response
​
Close Atom Status Notifications
This method cancels a previous subscription to an Atom status update.
Request
Response
Request
Endpoint
Websocket
wss://[node IP]/rpc
Headers
Header
Value
Content-Type
application/json
Body parameters
{
  "method": "Atoms.closeAtomStatusNotifications",
  "params": {
    "subscriberId": "<Subscriber_ID>"
  },
  "id": 0
}
Response
​
Get Atom Status Notifications
This method subscribes to status updates for a defined Atom.
Request
Response
Request
Endpoint
Websocket
wss://[node IP]/rpc
Headers
Header
Value
Content-Type
application/json
Body parameters
{
  "id": 0,
  "method": "Atoms.getAtomStatusNotifications",
  "params":
  {
    "aid": <aid>,
    "subscriberId": 0
  }
}
Response
{
  "method": "Atoms.nextStatusEvent",
  "params":
  {
    "status": "<DOES_NOT_EXIST|EVICTED_INVALID_ATOM|EVICTED_FAILED_CM_VERIFICATION|EVICTED_CONFLICT_LOSER|PENDING_CM_VERIFICATION|PENDING_DEPENDENCY_VERIFICATION|MISSING_DEPENDENCY|CONFLICT_LOSER|STORED>",
    "data": {}
  }
}
Possible values
DOES_NOT_EXIST
EVICTED_INVALID_ATOM
EVICTED_FAILED_CM_VERIFICATION
EVICTED_CONFLICT_LOSER
PENDING_CM_VERIFICATION
PENDING_DEPENDENCY_VERIFICATION
MISSING_DEPENDENCY
CONFLICT_LOSER
STORED
Get Live Peers
This method allows you to get the Node's current live Peers. 
Live peers are nodes which are still seen to be connected to the network.
Request
Response
Request
Endpoints
HTTP POST
https://[node IP]/rpc
Websocket
wss://[node IP]/rpc
Headers
Header
Value
Content-Type
application/json
Body parameters
{
  "method": "Network.getLivePeers",
  "params": [],
  "id": 0
}
Example call
curl --insecure --data-binary '{"method": "Network.getLivePeers","params": [],"id": 0}' -H 'content-type:application/json;' https://betanet-demo.radixnode.net/rpc
Response
Get Peers
This method allows you to get all the Peers known by the Node.
Request
Response
Request
Endpoints
HTTP POST
https://[node IP]/rpc
Websocket
wss://[node IP]/rpc
Headers
Header
Value
Content-Type
application/json
Body parameters
{
  "method": "Network.getPeers",
  "params": [],
  "id": 0
}
Example call
curl --insecure --data-binary '{"method": "Network.getPeers","params": [],"id": 0}' -H 'content-type:application/json;' https://betanet-demo.radixnode.net/rpc
Response
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "data": [
      {
        "attempts": 1,
        "ban_reason": "Connecting to self",
        "hash": "203853a3ba39a8839a2440874d98d00279100913aa83a3088b80094753023752",
        "host": {
          "inbound": {
            "host": "192.168.1.111",
            "port": 52948
          },
          "outbound": {
            "host": "192.168.1.111",
            "port": 30000
          }
        },
        "id": "-10579238518545579974299481554",
        "serializer": {
          "class_id": 1560569988
        },
        "statistics": {
          "duration": 1517235996418,
          "traffic_in": 0,
          "traffic_out": 0
        },
        "system": {
          "agent": "/Radix:/2090000",
          "clock": 46,
          "id": "-10579238518545579974299481554",
          "partitions": {
            "high": 9223372036854776000,
            "low": -9223372036854776000
          },
          "period": 0,
          "serializer": {
            "class_id": -1833998801
          },
          "services": [
            {
              "domain": "CORE",
              "id": "1990584267",
              "name": "CLIENT"
            }
          ],
          "version": {
            "agent": 2090000,
            "object": 100,
            "protocol": 100
          }
        },
        "timestamps": {
          "active": 1517235996417,
          "banned": 3664719643418,
          "connected": 0,
          "disconnected": 1517235996418
        },
        "version": {
          "object": 100
        }
      }
    ]
  }
}
Get Info
This endpoint allows you to get the Node's detailed information.
Request
Response
Request
Endpoints
HTTP POST
https://[node IP]/rpc
Websocket
wss://[node IP]/rpc
Headers
Header
Value
Content-Type
application/json
Body parameters
{
  "method": "Network.getInfo",
  "params": [],
  "id": 0
}
Example call
curl --insecure --data-binary '{"method": "Network.getInfo","params": [],"id": 0}' -H 'content-type:application/json;' https://betanet-demo.radixnode.net/rpc
Response
{
    "id": 0,
    "jsonrpc": "2.0",
    "result": {
        "agent": {
            "name": ":str:/Radix:/2700000",
            "protocol": 100,
            "version": 2700000
        },
        "clock": 604,
        "commitment": ":hsh:c163067c287f46f7119c644a35c8e0e3ae0c8d1c112f2a02e531e8ea0b65596b",
        "events": {
            "broadcast": 995298,
            "dequeued": 42209,
            "processed": {
                "asynchronous": 42209,
                "synchronous": 41131
            },
            "processing": 0,
            "queued": 42209
        },
        "hid": ":uid:565f9d83e478dcbf527487e5267b599c",
        "key": ":byt:AxG+dTmjmfRtIV1n3Quy72M8QlEeTp78L74qgoGAkFIx",
        "ledger": {
            "checksum": 4862339469912619842,
            "faults": {
                "assists": 0,
                "failed": 0,
                "stitched": 0,
                "tears": 0
            },
            "latency": {
                "path": 0,
                "persist": 0
            },
            "processed": 604,
            "processing": 0,
            "stored": 604,
            "storing": 0
        },
        "memory": {
            "free": 35041688,
            "max": 5519704064,
            "total": 196083712
        },
        "messages": {
            "inbound": {
                "discarded": 0,
                "pending": 0,
                "processed": 630080,
                "received": 630084
            },
            "outbound": {
                "aborted": 2,
                "pending": 0,
                "processed": 322882,
                "sent": 322884
            }
        },
        "nid": ":uid:df9e7ad3981668cb6cbf70c2b0a77431",
        "planck": 25852923,
        "port": 30000,
        "processors": 2,
        "serializer": 195914042,
        "shards": {
            "high": 9223372036854775807,
            "low": -9223372036854775808
        },
        "version": 100
    }
}
Get Universe
This method allows you to get the Node's current Universe.
Request
Response
Request
Endpoints
HTTP POST
https://[node IP]/rpc
Websocket
wss://[node IP]/rpc
Headers
Header
Value
Content-Type
application/json
Body parameters
{
  "method": "Universe.getUniverse",
  "params": [],
  "id": 0
}
Example call
curl --insecure --data-binary '{"method": "Universe.getUniverse","params": [],"id": 0}' -H 'content-type:application/json;' https://betanet-demo.radixnode.net/rpc
Response
Submit Atom
This method submits an Atom to the ledger.
Request
Response
Request
Endpoints
HTTP POST
https://[node IP]/rpc
Websocket
wss://[node IP]/rpc
Headers
Header
Value
Content-Type
application/json
Body parameters
{
  "method": "Atoms.submitAtom",
  "params": {
    "metaData": {
        "powNonce": ":str:28427",
        "timestamp": ":str:1560467870861"
    },
    "serializer": "radix.atom",
    "version": 100,
    "particleGroups": [
        {
            "serializer": "radix.particle_group",
            "particles": [
                {
                    "spin": -1,
                    "serializer": "radix.spun_particle",
                    "particle": {
                        "destinations": [":uid:07211570238763c92d835f38644dc037"],
                        "rri": ":rri:/JG9sPSMyVvDEdjM4wtP5GkLFQ9KHeQSZ2uyGV99Tw1fE81VNsno/JOSH",
                        "serializer": "radix.particles.rri",
                        "version": 100,
                        "nonce": 0
                    },
                    "version": 100
                },
                {
                    "spin": 1,
                    "serializer": "radix.spun_particle",
                    "particle": {
                        "symbol": ":str:JOSH",
                        "address": ":adr:JG9sPSMyVvDEdjM4wtP5GkLFQ9KHeQSZ2uyGV99Tw1fE81VNsno",
                        "granularity": ":u20:1000000000000000000",
                        "permissions": {
                            "burn": ":str:none",
                            "mint": ":str:token_creation_only"
                        },
                        "destinations": [":uid:07211570238763c92d835f38644dc037"],
                        "name": ":str:Josh",
                        "serializer": "radix.particles.token_definition",
                        "description": ":str:hello",
                        "version": 100
                    },
                    "version": 100
                },
                {
                    "spin": 1,
                    "serializer": "radix.spun_particle",
                    "particle": {
                        "amount": ":u20:115792089237316195423570985008687907853269984665640564039457584007913129639935",
                        "granularity": ":u20:1000000000000000000",
                        "permissions": {
                            "burn": ":str:none",
                            "mint": ":str:token_creation_only"
                        },
                        "destinations": [":uid:07211570238763c92d835f38644dc037"],
                        "serializer": "radix.particles.unallocated_tokens",
                        "version": 100,
                        "nonce": 1560467870856,
                        "tokenDefinitionReference": ":rri:/JG9sPSMyVvDEdjM4wtP5GkLFQ9KHeQSZ2uyGV99Tw1fE81VNsno/JOSH"
                    },
                    "version": 100
                }
            ],
            "version": 100
        }
    ],
    "signatures": {"07211570238763c92d835f38644dc037": {
        "r": ":byt:z7k9gXUqXkBXzmQ0poS5yji+tOpfqP7h6bMxNBB6jg0=",
        "s": ":byt:c9SLSo33put4rBwwvb8zcNgWHUARl0vgIjLMKMt7bFw=",
        "serializer": "crypto.ecdsa_signature",
        "version": 100
    }}
},
  "id": 0
}
Example call
curl --location --request POST "{{host}}/rpc" \
  --header "Content-Type: application/json" \
  --data "{
  \"method\": \"Atoms.submitAtom\",
  \"params\": {
    \"metaData\": {
        \"powNonce\": \":str:28427\",
        \"timestamp\": \":str:1560467870861\"
    },
    \"serializer\": \"radix.atom\",
    \"version\": 100,
    \"particleGroups\": [
        {
            \"serializer\": \"radix.particle_group\",
            \"particles\": [
                {
                    \"spin\": -1,
                    \"serializer\": \"radix.spun_particle\",
                    \"particle\": {
                        \"destinations\": [\":uid:07211570238763c92d835f38644dc037\"],
                        \"rri\": \":rri:/JG9sPSMyVvDEdjM4wtP5GkLFQ9KHeQSZ2uyGV99Tw1fE81VNsno/JOSH\",
                        \"serializer\": \"radix.particles.rri\",
                        \"version\": 100,
                        \"nonce\": 0
                    },
                    \"version\": 100
                },
                {
                    \"spin\": 1,
                    \"serializer\": \"radix.spun_particle\",
                    \"particle\": {
                        \"symbol\": \":str:JOSH\",
                        \"address\": \":adr:JG9sPSMyVvDEdjM4wtP5GkLFQ9KHeQSZ2uyGV99Tw1fE81VNsno\",
                        \"granularity\": \":u20:1000000000000000000\",
                        \"permissions\": {
                            \"burn\": \":str:none\",
                            \"mint\": \":str:token_creation_only\"
                        },
                        \"destinations\": [\":uid:07211570238763c92d835f38644dc037\"],
                        \"name\": \":str:Josh\",
                        \"serializer\": \"radix.particles.token_definition\",
                        \"description\": \":str:hello\",
                        \"version\": 100
                    },
                    \"version\": 100
                },
                {
                    \"spin\": 1,
                    \"serializer\": \"radix.spun_particle\",
                    \"particle\": {
                        \"amount\": \":u20:115792089237316195423570985008687907853269984665640564039457584007913129639935\",
                        \"granularity\": \":u20:1000000000000000000\",
                        \"permissions\": {
                            \"burn\": \":str:none\",
                            \"mint\": \":str:token_creation_only\"
                        },
                        \"destinations\": [\":uid:07211570238763c92d835f38644dc037\"],
                        \"serializer\": \"radix.particles.unallocated_tokens\",
                        \"version\": 100,
                        \"nonce\": 1560467870856,
                        \"tokenDefinitionReference\": \":rri:/JG9sPSMyVvDEdjM4wtP5GkLFQ9KHeQSZ2uyGV99Tw1fE81VNsno/JOSH\"
                    },
                    \"version\": 100
                }
            ],
            \"version\": 100
        }
    ],
    \"signatures\": {\"07211570238763c92d835f38644dc037\": {
        \"r\": \":byt:z7k9gXUqXkBXzmQ0poS5yji+tOpfqP7h6bMxNBB6jg0=\",
        \"s\": \":byt:c9SLSo33put4rBwwvb8zcNgWHUARl0vgIjLMKMt7bFw=\",
        \"serializer\": \"crypto.ecdsa_signature\",
        \"version\": 100
    }}
},
  \"id\": 0
}"
Response
AtomSubmissionState.onNext:
{
    "result": {
        "aid": "b55cba852e71ce49be7f27beef73a7e3f723301ea45ac90c07211570238763c9",
        "status": "PENDING_CM_VERIFICATION",
        "timestamp": 1561831269184
    },
    "id": 0,
    "jsonrpc": "2.0"
}
Possible values
DOES_NOT_EXIST
EVICTED_INVALID_ATOM
EVICTED_FAILED_CM_VERIFICATION
EVICTED_CONFLICT_LOSER
PENDING_CM_VERIFICATION
PENDING_DEPENDENCY_VERIFICATION
MISSING_DEPENDENCY
CONFLICT_LOSER
STORED
REST
JSON schemas
Last updated 2 years ago
Method	HTTP (POST)	WebSockets
Atom Subscribe	❌	✅
Atom Cancel Subscription	❌	✅
Close Atom Status Notifications	❌	✅
Get Atom Status Notifications	❌	✅
Get Live Peers	✅	✅
Get Peers	✅	✅
Get Info	✅	✅
Get Universe	✅	✅
Submit Atom	✅	✅