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

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
}
Atoms.subscribeUpdate:
{
"subscriberId": number
"atoms": any[],
"isHead": boolean
}

Atom Cancel Subscription

This method cancels a previous subscription to an Atom update.

Request
Response

Endpoint

Websocket

wss://[node IP]/rpc

Headers

Header

Value

Content-Type

application/json

Body parameters

{
"method": "Atoms.cancel",
"params": {
"subscriberId": "<Subscriber_ID>"
},
"id": 0
}

Close Atom Status Notifications

This method cancels a previous subscription to an Atom status update.

Request
Response

Endpoint

Websocket

wss://[node IP]/rpc

Headers

Header

Value

Content-Type

application/json

Body parameters

{
"method": "Atoms.closeAtomStatusNotifications",
"params": {
"subscriberId": "<Subscriber_ID>"
},
"id": 0
}

Get Atom Status Notifications

This method subscribes to status updates for a defined Atom.

Request
Response

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

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

Get Peers

This method allows you to get all the Peers known by the Node.

Request
Response

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

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

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

Submit Atom

This method submits an Atom to the ledger.

Request
Response

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

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