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.

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:

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:

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:

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:

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:

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

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:

Or for the WAGMI Subnetwork on the Dijets TestNet testnet:

Websocket EVM Endpoints

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

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

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:

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:

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

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

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, which is a base-58 encoding with a checksum.