Issue API Calls

Dijets API is a specifically-tailored collection of JSON-RPC API endpoints built to support Web3 usecases and scenarios on Dijets Ternary Chains at almost instant speeds. It is the single point of reference for requests being made to Dijets Primary Network and its chains.

Endpoints#

An API call is made to an endpoint, which is a URL, made up of the base URI which is the address and the port of the node, and the path the particular endpoint the API call is made to.

Base URL#

The base of the URL is always:

[node-ip]:[http-port]

where

node-ip is the IP address of the node the call is to.
http-port is the port the node listens on for HTTP calls. (default value 9650).

For example, if you're making RPC calls on the local node, the base URL might look like this: 127.0.0.1:9650.

If you're making RPC calls to remote nodes, then instead of 127.0.0.1 you should use the public IP of the server where the node is. Note that by default the node will only accept API calls on the local interface, so you will need to set up the http-host config flag on the node. Also, you will need to make sure the firewall and/or security policy allows access to the http-port from the internet.

info

When setting up RPC access to a node, make sure you don't leave the http-port accessible to everyone! There are malicious actors that scan for nodes that have unrestricted access to their RPC port and then use those nodes for spamming them with resource-intensive queries which can knock the node offline. Only allow access to your node's RPC port from known IP addresses!

Endpoint Path#

Each API’s documentation specifies what endpoint path a user should make calls to in order to access the API’s methods.

In general, they are formatted like:

/ext/[api-name]

So for the Admin API, the endpoint path is /ext/admin, for the Info API it is /ext/info and so on. Note that some APIs have additional path components, most notably the chain RPC endpoints which includes the Subnetwork chain RPCs. We'll go over those in detail in the next section.

So, in combining the base URL and the endpoint path we get the complete URL for making RPC calls. For example, to make a local RPC call on the Info API, the full URL would be:

http://127.0.0.1:9650/ext/info

Primary Network and Subnetwork RPC calls#

Besides the APIs that are local to the node, like Admin or Metrics APIs, nodes also expose endpoints for talking to particular chains that are either part of the Primary Network (the Value, Method and Utility Chains), or part of any Subnetworks the node might be syncing or validating.

In general, chain endpoints are formatted as:

ext/bc/[blockchainID]

Primary Network Endpoints#

The Primary Network consists of three chains: X, P and Utility Chain. As those chains are present on every node, there are also convenient aliases defined that can be used instead of the full blockchainIDs. So, the endpoints look like:

ext/bc/Value
ext/bc/Method
ext/bc/Utility

Utility Chain and Subnetwork-EVM Endpoints#

Utility Chain and many Subnetworks run a version of the EthereumVM (EVM). EVM exposes its own endpoints, which are also accessible on the node: JSON-RPC, and Websocket.

JSON-RPC EVM Endpoints

To interact with Utility Chain EVM via the JSON-RPC use the endpoint:

/ext/bc/C/rpc

To interact with Subnetwork instances of the EVM via the JSON-RPC endpoint:

/ext/bc/[blockchainID]/rpc

where blockchainID is the ID of the blockchain running the EVM. So for example, the RPC URL for the Swimmer Network (a Subnetwork that runs the Crabada game) running on a local node would be:

http://127.0.0.1/ext/bc/2K33xS9AyP9oCDiHYKVrHe7F54h2La5D8erpTChaAhdzeSu2RX/rpc

Or for the WAGMI Subnetwork on the Dijets TestNet testnet:

http://127.0.0.1/ext/bc/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/rpc

Websocket EVM Endpoints

To interact with Utility Chain via the websocket endpoint, use:

/ext/bc/C/ws

To interact with other instances of the EVM via the websocket endpoint:

/ext/bc/blockchainID/ws

where blockchainID is the ID of the blockchain running the EVM. For example, to interact with the Utility Chain's Ethereum APIs via websocket on localhost you can use:

ws://127.0.0.1:9650/ext/bc/C/ws

info

When using the Public API or another host that supports HTTPS, use https:// or wss:// instead of http:// or ws://.

Also, note that the public API only supports Utility Chain websocket API calls for API methods that don't exist on the Utility Chain's HTTP API.

Making a JSON RPC Request#

Most of the built-in APIs use the JSON RPC 2.0 format to describe their requests and responses. Such APIs include the Platform API and the Value Chain API.

Suppose we want to call the getTxStatus method of the [Value Chain API](Value Chain.md). The Value Chain API documentation tells us that the endpoint for this API is /ext/bc/Value.

That means that the endpoint we send our API call to is:

[node-ip]:[http-port]/ext/bc/Value

The Value Chain API documentation tells us that the signature of getTxStatus is:

[avm.getTxStatus](Value Chain.md#avmgettxstatus)(txID:bytes) -> (status:string)

where:

Argument txID is the ID of the transaction we’re getting the status of.
Returned value status is the status of the transaction in question.

To call this method, then:

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :4,
    "method" :"avm.getTxStatus",
    "params" :{
        "txID":"2QouvFWUbjuySRxeX5xMbNCuAaKWfbk5FeEa2JmoF85RKLk2dD"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X

jsonrpc specifies the version of the JSON RPC protocol. (In practice is always 2.0)
method specifies the service (avm) and method (getTxStatus) that we want to invoke.
params specifies the arguments to the method.
id is the ID of this request. Request IDs should be unique.

That’s it!

JSON RPC Success Response#

If the call is successful, the response will look like this:

{
  "jsonrpc": "2.0",
  "result": {
    "Status": "Accepted"
  },
  "id": 1
}

id is the ID of the request that this response corresponds to.
result is the returned values of getTxStatus.

JSON RPC Error Response#

If the API method invoked returns an error then the response will have a field error in place of result. Additionally, there is an extra field, data, which holds additional information about the error that occurred.

Such a response would look like:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32600,
        "message": "[Some error message here]",
        "data": [Object with additional information about the error]
    },
    "id": 1
}

Other API Formats#

Some APIs may use a standard other than JSON RPC 2.0 to format their requests and responses. Such extension should specify how to make calls and parse responses to them in their documentation.

Sending and Receiving Bytes#

Unless otherwise noted, when bytes are sent in an API call/response, they are in hex representation. However, Transaction IDs (TXIDs), ChainIDs, and subnetIDs are in CB58 representation, a base-58 encoding with a checksum.

Edit this page on GitHub