Skip to content

API Specification

This section will provide you APIs which you can use as a developer or integrator to DCore.

In case you want to browse all APIs from the beginning, please, visit:


API Structure

There are 2 main types of API depending on source of API provider.

  • Daemon API - To call them you need to be connected to running daemon (decentd).
  • Wallet API - To call them you need to be connected to running CLI Wallet.

Daemon API is separated into the following API sets:

  • login - Containes login and enable_api APIs. This is the only apiset (along with database API) that does not need to be enabled before the first call is done. All other apisets needs to be enabled by calling the enable_api previously, to retrieve the access and also get the apiset id, which will be used for every api call from that particular apiset. This will be explained in example calls below.
  • database - Contains APIs to receive information from the full node database, regarding objects, transactions, blocks, accounts, properties, etc. .
  • history - Contains APIs, which provides a transaction history.
  • network_broadcast - Contains APIs to broadcast to the network.
  • network_node - Contains APIs to get or change P2P network settings. This API subgroup provides sensitive data and is not available by default.
  • crypto - Contains APIs to sign and do verifications.
  • messaging - Contains APIs to send and receive messages.

Wallet API has no API sets.


Communication Protocols

Communication protocols used in API calls are HTTP and websocket. The main difference is HTTP protocol does not hold a session status so we are able to call only one API set from the Daemon API set - the database set. The Wallet API can be called both via websocket and HTTP, as running CLI Wallet can hold a session data for every connection.

At first, we provide examples with websocket protocol and then we provide examples with HTTP protocol.


Prerequisites for Websocket Usage

The following guide provides simple setup of environment to test APIs.

In order to call daemon or wallet API via websocket you need:

In order to call daemon or wallet API via websocket you need:

  • running decentd (decentd is called daemon as well),
  • running CLI Wallet listening for websocket connections (wallet API only),
  • installed wscat application.

This testing environment can be installed on Linux, MacOS and Windows.

The instructions how to run decentd and CLI Wallet are provided here.

To install wscat run:

npm install -g wscat

Tip

If npm has not been installed yet, you can download it from Node.js webpage.

Calling DCore Daemon API via Websocket

Run the Test Environment for Daemon

Start the DCore daemon by executing decentd:

./decentd

Connect the websocket console to the DCore daemon:

wscat -c ws://127.0.0.1:8090

Login API

To call any API from any API set successfully, first call the login API, found in the login set, which is enabled by default.

Attention

Not all api sets can be enabled in every case (network_node can be enabled only on daemon, that is configured to grant access to this API set - for security reasons).

The rest of the API sets mentioned in the list above are available for any connection.

API call JSON structure:

  • id - call_id (number identifying the API call, used to pair requests with responses)
  • method - call - commands to call the API
  • params - [apiset_id,api_name,[list_of_params]]
    • first parameter apiset_id is the id of the API set,
    • second parameter api_name is the name of the API to call,
    • third parameter [list_of_params] is the list of parameters for the particular API, any parameter can be also a list of values, in this case the list is also nested in brackets.

Call - login api:

{"id":1,"method":"call","params":[1,"login",["",""]]}

Response:

{"id":1,"result":true}

Note

To call login API set apiset_id to 1. The value is defined by default and is constant.

Enabling a Particular API Set

To enable a particular API set the enable_api is called. This API is from login API set and is available by default.

Call - enabling the database API set:

{"id":1,"method":"call","params":[1,"database",[]]}

Response:

{"id":1,"result":2}

When the API set is accessible, its member name, id, is returned as a value of name result (its value is 2 in previous example). This id can be used for every call of any database API for now (as apiset_id, the first parameter from the params). Note that this id can differ for every connection (depending on the order of the enabling api sets).

Info

Let us notice you by another possibility to call database API set, without the need to make a call for login API first. To do so, use the call structure as is shown in call login example and do the following changes:

  • use 0 for apiset_id value, and
  • use database as value of apiset_name.

Calling API from Enabled API Set

Let us assume, the chosen API is get_account_balances and we want to see balances of the account with id = 1.2.21. As this is API from database API set, we already have the API set, id = 2, so the exact call is:

Call - get_account_balances api:

{"id":1,"method":"call","params":[2,"get_account_balances",["1.2.21",[]]]}

Response:

{"id":1,"result":[{"amount":"15400490000","asset_id":"1.3.0"}]}

Another example for calling API from another API set is API get_account_history from history API set.

Call - enable the history API set:

{"id":1,"method":"call","params":[1,"history",[]]}

Response:

{"id":1,"result":3}

Note that, every API set enabling needs to be called just once.

A returned value of member's name result is used as API set id for the get_account_history call. For example, we would like to see the last 2 history records for the account with id = 1.2.21.

Call - get_account_history api:

{"id":1,"method":"call","params":[3,"get_account_history",["1.2.21","1.7.1",2,"1.7.1212121"]]}

Response (list of history records):

{
  "id": 1,
  "result": [
    {
      "id": "1.7.38270",
      "op": [
        1,
        {
          "fee": {
            "amount": 500000,
            "asset_id": "1.3.0"
          },
          "registrar": "1.2.21",
          "name": "myaccount",
          "owner": {
            "weight_threshold": 1,
            "account_auths": [
            ],
            "key_auths": [
              [
                "DCT66RkRV5vpanRc7iAXdFyAMwFTbmLHCUe9eBB6aQjaHkrTZfBHL",
                1
              ]
            ]
          },
          "active": {
            "weight_threshold": 1,
            "account_auths": [
            ],
            "key_auths": [
              [
                "DCT66RkRV5vpanRc7iAXdFyAMwFTbmLHCUe9eBB6aQjaHkrTZfBHL",
                1
              ]
            ]
          },
          "options": {
            "memo_key": "DCT66RkRV5vpanRc7iAXdFyAMwFTbmLHCUe9eBB6aQjaHkrTZfBHL",
            "voting_account": "1.2.3",
            "num_miner": 0,
            "votes": [
            ],
            "extensions": [
            ],
            "allow_subscription": false,
            "price_per_subscribe": {
              "amount": 0,
              "asset_id": "1.3.0"
            },
            "subscription_period": 0
          },
          "extensions": {
          }
        }
      ],
      "result": [
        1,
        "1.2.4143"
      ],
      "block_num": 702030,
      "trx_in_block": 0,
      "op_in_trx": 0,
      "virtual_op": 37303
    },
    {
      "id": "1.7.37253",
      "op": [
        1,
        {
          "fee": {
            "amount": 500000,
            "asset_id": "1.3.0"
          },
          "registrar": "1.2.21",
          "name": "myaccount",
            "owner": {
            "weight_threshold": 1,
            "account_auths": [
            ],
            "key_auths": [
              [
                "DCT66RkRV5vpanRc7iAXdFyAMwFTbmLHCUe9eBB6aQjaHkrTZfBHL",
                1
              ]
            ]
          },
          "active": {
            "weight_threshold": 1,
            "account_auths": [
            ],
            "key_auths": [
            [
                "DCT66RkRV5vpanRc7iAXdFyAMwFTbmLHCUe9eBB6aQjaHkrTZfBHL",
                1
              ]
            ]
          },
          "options": {
            "memo_key": "DCT66RkRV5vpanRc7iAXdFyAMwFTbmLHCUe9eBB6aQjaHkrTZfBHL",
            "voting_account": "1.2.3",
            "num_miner": 0,
            "votes": [
            ],
            "extensions": [
            ],
            "allow_subscription": false,
            "price_per_subscribe": {
              "amount": 0,
              "asset_id": "1.3.0"
            },
            "subscription_period": 0
          },
          "extensions": {
          }
        }
      ],
      "result": [
        1,
        "1.2.4142"
      ],
      "block_num": 701189,
      "trx_in_block": 0,
      "op_in_trx": 0,
      "virtual_op": 37286
    }
  ]
}

Calling Wallet API via Websocket

Run the Test Environment for Wallet

Start the DCore daemon by executing decentd:

./decentd

Run the CLI Wallet listening for websocket connections on default port:

cli_wallet -r

Connect the websocket console to CLI Wallet:

wscat -c ws://127.0.0.1:8091

Call Wallet API

Calling of API is done by setting values method and params according to the particular API specification. Note that, the params value is list of params put into brackets. The value of id can be any number and it is used in the response for pairing the call and returned responses.

Call format:

{
  "jsonrpc": "2.0",
  "id": "call_id",
  "method": "api_name",
  "params": ["param_1", "param_2", "...", "param_N"]
}

Where parameters are:

  • id - Any number identifying the API call, will appear in JSON response.
  • method - A full name of the called API.
  • params - A list of parameters for the particular API, any parameter can be also a list of values, in this case the list is also nested in brackets.

For example, the API unlock is defined in the documentation as follows:

public void unlock(string password)

So, the websocket call is defined below.

Call - unlock api:

{"jsonrpc":"2.0","id":1,"method":"unlock","params":["myUnlockPwd"]}

Response:

{"id":1,"result":null}

Another example is get_account.

Call - get_account api:

{"jsonrpc":"2.0","id":1,"method":"get_account","params":["1.2.21"]}

Response:

{
  "id": 1,
  "result": {
    "id": "1.2.21",
    "registrar": "1.2.20",
    "name": "decent-go",
    "owner": {
      "weight_threshold": 1,
      "account_auths": [
      ],
      "key_auths": [
        [
          "DCT8gwQkHXNYgHp1kzo56oZCLdrm3qV99xN15yeE1QhBcbAYsMDZy",
          1
        ]
      ]
    },
    "active": {
      "weight_threshold": 1,
      "account_auths": [
      ],
      "key_auths": [
        [
          "DCT8gwQkHXNYgHp1kzo56oZCLdrm3qV99xN15yeE1QhBcbAYsMDZy",
          1
        ]
      ]
    },
    "options": {
      "memo_key": "DCT8gwQkHXNYgHp1kzo56oZCLdrm3qV99xN15yeE1QhBcbAYsMDZy",
      "voting_account": "1.2.3",
      "num_miner": 0,
      "votes": [
      ],
      "extensions": [
      ],
      "allow_subscription": false,
      "price_per_subscribe": {
        "amount": 0,
        "asset_id": "1.3.0"
      },
      "subscription_period": 0
    },
    "rights_to_publish": {
      "is_publishing_manager": false,
      "publishing_rights_received": [
      ],
      "publishing_rights_forwarded": [
      ]
    },
    "statistics": "2.5.21",
    "top_n_control_flags": 0
  }
}

Calling DCore Daemon API via HTTP

Run the DCore Daemon

Start the DCore daemon by executing decentd:

./decentd

Calling Database API

All API calls have the same data structure as the calls via websocket.

For example, we will call the get_accounts API with one account id parameter: 1.2.69.

The HTTP request - get_accounts api:

curl --data '{"jsonrpc":"2.0","id":1,"method":"get_accounts","params":[["1.2.69"]]}' http://127.0.0.1:8090/rpc

Response:

{
  "id": 1,
  "result": [
    {
      "id": "1.2.69",
      "registrar": "1.2.15",
      "name": "ronald",
      "owner": {
        "weight_threshold": 1,
        "account_auths": [
        ],
        "key_auths": [
          [
            "DCT8SFcioQFYXnNHNSAEcLb5o5EovrhjPk4SMbYnag6t6VhwuvMAc",
            1
          ]
        ]
      },
      "active": {
        "weight_threshold": 1,
        "account_auths": [
        ],
        "key_auths": [
          [
            "DCT8SFcioQFYXnNHNSAEcLb5o5EovrhjPk4SMbYnag6t6VhwuvMAc",
            1
          ]
        ]
      },
      "options": {
        "memo_key": "DCT8SFcioQFYXnNHNSAEcLb5o5EovrhjPk4SMbYnag6t6VhwuvMAc",
        "voting_account": "1.2.3",
        "num_miner": 0,
        "votes": [
          "0:1",
          "0:11"
        ],
        "extensions": [
        ],
        "allow_subscription": true,
        "price_per_subscribe": {
          "amount": 100000000,
          "asset_id": "1.3.0"
        },
        "subscription_period": 7
      },
      "rights_to_publish": {
        "is_publishing_manager": false,
        "publishing_rights_received": [
        ],
        "publishing_rights_forwarded": [
        ]
      },
      "statistics": "2.5.69",
      "top_n_control_flags": 0
    }
  ]
}

Calling Wallet API via HTTP

Run the DCore Daemon and the Wallet

Start the DCore daemon by executing decentd (decentd is called daemon as well):

./decentd

Run the CLI Wallet listening for HTTP requests:

cli_wallet -H

Wallet API Call Example

The data structure of wallet API calls is the same for HTTP as for the calls via websocket.

For example, the call for API unlock is shown below.

Wallet command:

locked >>> unlock myPassword

HTTP request - unlock api:

curl --data '{"jsonrpc":"2.0","id":1,"method":"unlock","params":["myPassword"]}' http://127.0.0.1:8093/rpc

Response:

{
  "id": 1,
  "result": null
}

Once the wallet is unlocked, we can call, for example, a simple DCT transfer.

Wallet command:

transfer fromAccount toAccount 1 DCT "note" true

HTTP request - transfer api:

curl --data '{"jsonrpc":"2.0","id":1,"method":"transfer","params":["fromAccount" "mictoAccountkey" "1" "DCT" "nate" "true"]}' http://127.0.0.1:8093/rpc

Response:

{
  "id": 1,
  "result": {
    "ref_block_num": 43971,
    "ref_block_prefix": 4115917218,
    "expiration": "2018-01-16T09:53:15",
    "operations": [
      [
        0,
        {
          "fee": {
            "amount": 500000,
            "asset_id": "1.3.0"
          },
          "from": "1.2.69",
          "to": "1.2.73",
          "amount": {
            "amount": 100000000,
            "asset_id": "1.3.0"
          },
          "memo": {
            "from": "DCT8SFcioQFYXnNHNSAEcLb5o5EovrhjPk4SMbYnag6t6VhwuvMAc",
            "to": "DCT5yt9cuR2d6UDmtQQZBckT4eNJ3u9fmmWnBfiBEgqz1PnQyzHqD",
            "nonce": "3964683768455640627",
            "message": "5ccbbb3b98a916ef7bc60c8aff06198a"
          },
          "extensions": [
          ]
        }
      ]
    ],
    "extensions": [
    ],
    "signatures": [
      "1f7e2844d458182ac9490accdda00e61c47ac416bda9502c758dae0cbb3b3603ff70d32c019c5a23bef8944be8ad7c7d2a5f8080f41159a5c483593c51973ad535"
    ]
  }
}