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.
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.
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.
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"}
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 | ✅ | ✅ |
This methods subscribes to Atom(s) updates.
Atoms.subscribeUpdate:{"subscriberId": number"atoms": any[],"isHead": boolean}
This method cancels a previous subscription to an Atom update.
This method cancels a previous subscription to an Atom status update.
This method subscribes to status updates for a defined Atom.
{"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 |
|
|
|
|
|
|
|
|
|
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.
https://[node IP]/rpc
wss://[node IP]/rpc
Header | Value |
Content-Type | application/json |
{"method": "Network.getLivePeers","params": [],"id": 0}
curl --insecure --data-binary '{"method": "Network.getLivePeers","params": [],"id": 0}' -H 'content-type:application/json;' https://betanet-demo.radixnode.net/rpc
This method allows you to get all the Peers known by the Node.
https://[node IP]/rpc
wss://[node IP]/rpc
Header | Value |
Content-Type | application/json |
{"method": "Network.getPeers","params": [],"id": 0}
curl --insecure --data-binary '{"method": "Network.getPeers","params": [],"id": 0}' -H 'content-type:application/json;' https://betanet-demo.radixnode.net/rpc
{"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}}]}}
This endpoint allows you to get the Node's detailed information.
https://[node IP]/rpc
wss://[node IP]/rpc
Header | Value |
Content-Type | application/json |
{"method": "Network.getInfo","params": [],"id": 0}
curl --insecure --data-binary '{"method": "Network.getInfo","params": [],"id": 0}' -H 'content-type:application/json;' https://betanet-demo.radixnode.net/rpc
{"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}}
This method allows you to get the Node's current Universe.
https://[node IP]/rpc
wss://[node IP]/rpc
Header | Value |
Content-Type | application/json |
{"method": "Universe.getUniverse","params": [],"id": 0}
curl --insecure --data-binary '{"method": "Universe.getUniverse","params": [],"id": 0}' -H 'content-type:application/json;' https://betanet-demo.radixnode.net/rpc
This method submits an Atom to the ledger.
https://[node IP]/rpc
wss://[node IP]/rpc
Header | Value |
Content-Type | application/json |
{"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}
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}"
AtomSubmissionState.onNext:
{"result": {"aid": "b55cba852e71ce49be7f27beef73a7e3f723301ea45ac90c07211570238763c9","status": "PENDING_CM_VERIFICATION","timestamp": 1561831269184},"id": 0,"jsonrpc": "2.0"}
Possible values |
|
|
|
|
|
|
|
|
|