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:

To get to desired API call continue by reading next parts of the document.


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:

The 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.

Login API Documentation, Doxygen


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.

Database API developer documentation, Doxygen


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

Get Account balances API developer documentation, Doxygen


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.

History API developer documentation, Doxygen


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

Get account history API developer documentation, Doxygen


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.

Wallet API developer documentation

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}

Unlock API developer documentation

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

Get account API developer documentation


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.

Database API developer documentation, Doxygen

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

Get Accounts API developer documentation, Doxygen

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
}

Unlock Wallet API developer documentation

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

DCore 1.4: transfer2 deprecated in favour of transfer

We are deprecating the Wallet API transfer2 method in update 1.4 and will remove it completely in a future release (most likely the next mandatory release).

transfer should be used as a direct replacement for transfer2 and there is nothing required other than replacing usages of transfer2 with 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"
    ]
  }
}

Transfer Wallet API developer documentation



  1. The new DCore API documentation is intended to complement the existing DCore Doxygen documentation