Skip to content

JSON RPC

Jump to bottom Edit New page
Razvan Ceana edited this page Feb 10, 2019 · 7 revisions

Table of Contents generated with DocToc

JSON RPC API

JSON is a lightweight data-interchange format. It can represent numbers, strings, ordered sequences of values, and collections of name/value pairs.

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over HTTP, or in many various message passing environments. It uses JSON (RFC 4627) as data format.

JSON-RPC Endpoint

Default JSON-RPC endpoints:

Client URL
Node http://localhost:{port}

Port must be defined explicitly by passing the number through the environment variable JSON_RPC_SERVER_PORT

Node

JSON_RPC_SERVER_PORT=3334 npm run commands

Environment Variables

Variable Mandatory Default Value Description
JSON_RPC_SERVER_HOST No 127.0.0.1 The IP address on which the server will listen
JSON_RPC_SERVER_PORT Yes {no-value} The Port on which the server will listen (if not defined, the server will not start)
JSON_RPC_BASIC_AUTH_ENABLE No False Whether the basic authentication is enabled or not
JSON_RPC_BASIC_AUTH_USER No {no-value} The basic authentication username
JSON_RPC_BASIC_AUTH_PASS No {no-value} The basic authentication password
JSON_RPC_RATE_LIMIT_WINDOW No 60000 The Rate limiter window (1 minute, 60 * 1000ms)
JSON_RPC_RATE_LIMIT_MAX_REQUESTS No 60 The Rate limiter maximum requests in the specified window
JSON_RPC_RATE_LIMIT_ENABLE No True Whether the Rate limiter is enabled or not

Curl Examples Explained

The curl options below might return a response where the node complains about the content type, this is because the --data option sets the content type to application/x-www-form-urlencoded . If your node does complain, manually set the header by placing -H "Content-Type: application/json" at the start of the call.

The examples also do not include the URL/IP & port combination which must be the last argument given to curl e.x. 127.0.0.1:3334

JSON-RPC methods

JSON RPC API Reference

clientVersion

Returns the current client version.

Parameters

none

Returns

String - The current client version.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"clientVersion","params":[],"id":1}'

// Result
{
    "id":1,
    "jsonrpc":"2.0",
    "result": "1.0.0"
}

netVersion

Returns the current network.

Parameters

none

Returns

String - The current network id.

  • "1": Webdollar MainNet
  • "2": Webdollar TestNet
Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"netVersion","params":[],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": {
        "id": 1,
        "name": "Webdollar MainNet"
    }
}

peerCount

Returns number of peers currently connected to the client.

Parameters

none

Returns

Object - Information about the connected peers.

  • clients: QUANTITY
  • servers: QUANTITY
  • webpeers: QUANTITY
Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"peerCount","params":[],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": {
        "clients": 1,
        "servers": 10,
        "webpeers": 0
    }
}

protocolVersion

Returns the current webdollar protocol version.

Parameters

none

Returns

String - The current webdollar protocol version.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"protocolVersion","params":[],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": "1.200.0"
}

syncing

Returns an object with data about the sync status.

Parameters

none

Returns

Object, An object with sync status data or FALSE, when not syncing:

  • currentBlock: QUANTITY - The current block, same as blockNumber
  • isSynchronized: Boolean - If the node is in sync with the network
  • secondsBehind: QUANTITY - The estimated number of seconds behind
Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"syncing","params":[],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": {
        "currentBlock": 160,
        "isSynchronized": true,
        "secondsBehind": 10.84
    }
}

accounts

Returns a list of accounts in the wallet.

Parameters
  1. Boolean - If true, the response will include also the balance
Returns

Array of Object, The accounts included in the wallet

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"accounts","params":[],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": ["WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$"]
}

// or with balance
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"accounts","params":[true],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": [
        {
            "address": "WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$",
            "balance": 200,
            "balance_raw": 2000000
        }
    ]
}

deleteAccount

Removes an account from the wallet.

Parameters
  1. String - The account to remove
  2. String - The encryption password, if the account was previously encrypted
Returns

Boolean, The status of the operation

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"deleteAccount","params":["WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$"],"id":1}'

// Result
{
    "id"     : 1,
    "jsonrpc": "2.0",
    "result" : true
}

// or with password if the account was previously encrypted
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"deleteAccount","params":["WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$", "<12 words password>"],"id":1}'

// Result
{
    "id"     : 1,
    "jsonrpc": "2.0",
    "result" : true
}

encryptAccount

Encrypt an existing account from the wallet, which is not already encrypted.

Parameters
  1. String - The account to encrypt
Returns

String, The generated password for the account

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"encryptAccount","params":["WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$"],"id":1}'

// Result
{
    "id"     : 1,
    "jsonrpc": "2.0",
    "result" : "<12 words password>"
}

exportAccount

Exports an existing account from the wallet.

Parameters
  1. String - The account to export
Returns

Object, The JSON containing all the informations describing the account

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"exportAccount","params":["WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$"],"id":1}'

// Result
{
    "id"     : 1,
    "jsonrpc": "2.0",
    "result" : {
        "version"   : "0.1",
        "address"   : "WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$",
        "publicKey" : "<address public key>",
        "privateKey": "<address private key>"
    }
}

importAccount

Imports an existing account from a JSON Object.

Parameters
  1. Object - The JSON object containing the informations describing an account
Returns

Object, An object describing the imported account

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"importAccount","params":["WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$"],"id":1}'

// Result
{
    "id"     : 1,
    "jsonrpc": "2.0",
    "result" : {
        "address"   : "WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$",
        "publicKey" : "<address public key>",
    }
}

newAccount

Creates a new account in the wallet.

Parameters
  1. Boolean - If true, the account will be encrypted and the response will include also the generated password
Returns

Object, An object containing the newly created account and the generated password (in case encryption was set)

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"newAccount","params":[],"id":1}'

// Result
{
    "id"     : 1,
    "jsonrpc": "2.0",
    "result" : {
        "address" : "WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$"
    }
}

// or if the account should be encrypted
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"newAccount","params":[true],"id":1}'

// Result
{
    "id"     : 1,
    "jsonrpc": "2.0",
    "result" : {
        "address" : "WEBD$gCA2Ydie63YGu+4ZVIfA+xP6n$7@r4txvL$",
        "password": "<12 words password>"
    }
}

blockNumber

Returns the number of most recent block.

Parameters

none

Returns

QUANTITY - integer of the current block number

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"blockNumber","params":[],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": 1045
}

WEBD$gCt+f$3rJ7Q@AGrGVhqZ$2ke+o8E6BVpbv$

getBalance

Returns the balance of the account of given address.

Parameters
  1. String, address to check for balance.
params: [
   "WEBD$gCt+f$3rJ7Q@AGrGVhqZ$2ke+o8E6BVpbv$"
]
Returns

QUANTITY - integer of the current balance, in webdollar coins.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getBalance","params":["WEBD$gCt+f$3rJ7Q@AGrGVhqZ$2ke+o8E6BVpbv$"],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": 4257200000
}

getTransactionCount

Returns the number of transactions sent from an address.

!!! Important: This method is not available yet

Parameters
  1. String, address to check for the number of transactions.
  2. QUANTITY|TAG - integer block number, or the string "latest", "earliest" or "pending" 
params: [
   "WEBD$gCt+f$3rJ7Q@AGrGVhqZ$2ke+o8E6BVpbv$",
   "latest" // state at the latest block
]
Returns

QUANTITY - integer of the number of transactions send from this address.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getTransactionCount","params":["WEBD$gCt+f$3rJ7Q@AGrGVhqZ$2ke+o8E6BVpbv$","latest"],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": 1
}

getBlockTransactionCountByHash

Returns the number of transactions in a block from a block matching the given block hash.

Parameters
  1. String, hash of a block.
params: [
    "0000000000d31971c54e65f7e253ae2d45df5d0dab52d05d04da6bd470c90e4f"
]
Returns

QUANTITY - integer of the number of transactions in this block.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getBlockTransactionCountByHash","params":["0000000000d31971c54e65f7e253ae2d45df5d0dab52d05d04da6bd470c90e4f"],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": 16
}

getBlockTransactionCountByNumber

Returns the number of transactions in a block matching the given block number.

Parameters
  1. QUANTITY|TAG - integer of a block number, or the string "earliest", "latest" or "pending" 
params: [
    "105789",
]
Returns

QUANTITY - integer of the number of transactions in this block.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getBlockTransactionCountByNumber","params":["105789"],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": 25
}

sendTransaction

Creates new transaction.

Parameters
  1. Object - The transaction object
  • from: String, - The address the transaction is sent from.
  • to: String, - The address the transaction is directed to.
  • value: QUANTITY - Integer of the value sent with this transaction (in Webdollar coins)
  • fee: QUANTITY - (optional) Integer of the fee for this transaction (in Webdollar coins)
  • password: String - (optional) The password corresponding to the "from" address, if this is encrypted
params: [{
    "from": "WEBD$gCt+f$3rJ7Q@AGrGVhqZ$2ke+o8E6BVpbv$",
    "to": "WEBD$gDs#W$n1#8zf@9JmLsgV7vvRirfdrC+Y@v$",
    "value": 500000,
    "fee": 100000,
    "password": "AAAA BBBB CCCC DDDD EEEE FFFF GGGGG HHHH IIII JJJJ KKKK LLLL"
}]
Returns

String - the transaction hash.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"sendTransaction","params":[{see above}],"id":1}'

// Result
{
    "id":1,
    "jsonrpc": "2.0",
    "result": "9dfc1de8fc6877f77a61ba1af6e9d4da310d09061cb5ca59fa45f7bf3b2217e3"
}

sendRawTransaction

Creates new transaction from a pre-signed (offline) transaction.

Parameters
  1. String, The base64 encoded transaction data.
params: ["{base64 encoded transaction}"]
Returns

String - the transaction hash

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"sendRawTransaction","params":[{see above}],"id":1}'

// Result
{   
    "id":1,
    "jsonrpc": "2.0",
    "result": "9dfc1de8fc6877f77a61ba1af6e9d4da310d09061cb5ca59fa45f7bf3b2217e3"
}

getBlockByHash

Returns information about a block by hash.

Parameters
  1. String - Hash of a block.
  2. Boolean - If true it returns the full transaction objects, if false only the hashes of the transactions. (default: false)
  3. Boolean - If true it will process the block according to hard-forks. (default: true)
params: [
   '0000000000d31971c54e65f7e253ae2d45df5d0dab52d05d04da6bd470c90e4f',
   true,
   true
]
Returns

Object - A block object, or null when no block was found:

  • id: Integer - the block number
  • block_id: Integer - the block number
  • hash: String - hash of the block
  • nonce: Integer - the nonce of the block
  • nonce_raw: Integer - the unprocessed nonce of the block
  • version: Integer - the version of the block
  • previous_hash: String - hash of the previous block.
  • timestamp: String - the formatted timestamp for when the block was created.
  • timestamp_UTC: Integer - the timestamp in UTC for when the block was created.
  • timestamp_block: Integer - the raw timestamp for when the block was created.
  • hash_data: String - the hash of the data stored in the block.
  • miner_address: String - the address that mined the block.
  • trxs_hash_data: String - the hash of the transaction data.
  • trxs_number: Integer - the number of transactions included in the block.
  • trxs: Array - the transactions included in the block (hashes or the full object).
  • reward: Integer - the reward for the block.
  • reward_raw: Integer - the reward for the block in Webdollar coins.
  • createdAtUTC: String - the formatted timestamp in UTC for when the block was created.
  • block_raw: String - the raw enoded block information
Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getBlockByHash","params":["0000000000d31971c54e65f7e253ae2d45df5d0dab52d05d04da6bd470c90e4f", true, true],"id":1}'

// Result
{
    "id":1,
    "jsonrpc":"2.0",
    "result": {
        "id": 100,
        "block_id": 100,
        "hash": "00000000349a2c3c93dea00bf56ca0fa83553b1d3ce0b5e0292ad704b6da21f1",
        "nonce": 0,
        "nonce_raw": 0,
        "version": 1,
        "previous_hash": "0000000017af4e3d05aa745c4de982085887b6cfd165d69f311aed059a170bd6",
        "timestamp": "Fri, 14 Dec 2018 12:02:53 GMT",
        "timestamp_UTC": 1544788973,
        "timestamp_block": 5275394,
        "hash_data": "950d45f13e32cfce6e52f6e69ad72a2ce744fdf600f281ec171d94475bff1e0b",
        "miner_address": "WEBD$gCt+f$3rJ7Q@AGrGVhqZ$2ke+o8E6BVpbv$",
        "trxs_hash_data": "5df6e0e2761359d30a8275058e299fcc0381534545f55cf43e41983f5d4c9456",
        "trxs_number": 0,
        "trxs": [],
        "reward": 6000,
        "reward_raw": 60000000,
        "createdAtUTC": "2018-12-14T12:02:53.000Z",
        "block_raw": "MDAwMDAwMDAzND@hMmMzYzkzZGVhMD{.........}mZGI0YjAwZjg3NzAwMDAwMDAwMDAwMA=="
    }
}

getBlockByNumber

Returns information about a block by block number.

Parameters
  1. QUANTITY|TAG - integer of a block number, or the string "earliest", "latest"
  2. Boolean - If true it returns the full transaction objects, if false only the hashes of the transactions. (default: false)
  3. Boolean - If true it will process the block according to hard-forks. (default: true)
params: [
   100,
   true,
   true
]
Returns

See getBlockByHash

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getBlockByNumber","params":[100, true, true],"id":1}'

Result see getBlockByHash

getTransactionByHash

Returns the information about a transaction requested by transaction hash.

!!! Important: This method is not available yet

Parameters
  1. String - hash of a transaction
params: [
   "44692aa0762d7699d3849837cb823dcfd727b3ff7f65cfc55194484929842e7d"
]
Returns

Object - A transaction object, or null when no transaction was found:

  • trx_id: String - hash of the transaction.
  • version: Integer - version of the transaction.
  • nonce: Integer - the nonce of the transaction.
  • index: Integer - the index of the transaction in the block.
  • time_lock: Integer - the time_lock of the transaction.
  • from_length: Integer - the number of "from" addresses.
  • to_length: Integer - the number of "to" addresses.
  • fee: Integer - the fee of the transaction.
  • fee_raw: Integer - the fee of the transaction in Webdollar coins.
  • timestamp: String - the timestamp of the transaction. null when its pending.
  • timestamp_UTC: Integer - the timestamp of the transaction in UTC. null when its pending.
  • timestamp_block: Integer - the timestamp of the block. null when its pending.
  • createdAtUTC: String - the formatted timestamp in UTC for when the block was created. null when its pending.
  • block_id: Integer - block number where this transaction was in. null when its pending.
  • from: Object - The list of sending addresses
    • from[trxs]: Array - The information about a single address
      • from[trxs][][trx_from_address] - The address
      • from[trxs][][trx_from_pub_key] - The public key of the address
      • from[trxs][][trx_from_signature] - The signature of the address
      • from[trxs][][trx_from_amount] - The amount sent
      • from[trxs][][trx_from_amount_raw] - The amount sent in Webdollar coins
    • from[addresses]: Array - The list of the receiving addresses
    • from[amount]: Float - The sent amount (including the fee)
    • from[amount_raw]: Integer - The sent amount (including the fee) in Webdollar coins
  • to: Object - The list of receiving addresses
    • to[trxs]: Array - The information about a single address
      • to[trxs][][trx_to_address] - The address
      • to[trxs][][trx_to_amount] - The amount received
      • to[trxs][][trx_to_amount_raw] - The amount received in Webdollar coins
    • to[addresses]: Array - The list of the receiving addresses
    • to[amount]: Float - The received amount
    • to[amount_raw]: Integer - The received amount in Webdollar coins
Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getTransactionByHash","params":["44692aa0762d7699d3849837cb823dcfd727b3ff7f65cfc55194484929842e7d"],"id":1}'

// Result
{
    "jsonrpc":"2.0",
    "id":1,
    "result": {
        "trx_id": "44692aa0762d7699d3849837cb823dcfd727b3ff7f65cfc55194484929842e7d",
        "version": 2,
        "nonce": 0,
        "index": 0,
        "time_lock": 71,
        "from_length": 1,
        "to_length": 1,
        "fee": 8.12,
        "fee_raw": 81200,
        "timestamp": null,
        "timestamp_UTC": null,
        "timestamp_block": null,
        "timestamp_raw": null,
        "createdAtUTC": null,
        "block_id": null,
        "from": {
            "trxs": [
                {
                    "trx_from_address": "WEBD$gAaGpKWMi#$#1HgTW0qgndTbd1a71BM@7H$",
                    "trx_from_pub_key": "6df10437fc31019404258ea58da62a49973b03a81425eccacc82bee3ee229bf2",
                    "trx_from_signature": "149bf40b2efdce42b78054db342d9d38742c0bf27963883a1f1f26df4e52a5f8438afda342d78b6b95e78200719a46ebd53b5840f3f2cef6612cb214f296ec00",
                    "trx_from_amount": 28.12,
                    "trx_from_amount_raw": 281200
                }
            ],
            "addresses": [
                "WEBD$gAaGpKWMi#$#1HgTW0qgndTbd1a71BM@7H$"
            ],
            "amount": 28.12,
            "amount_raw": 281200
        },
        "to": {
            "trxs": [
                {
                    "trx_to_address": "WEBD$gD$DU#wKt@xIEMU3j@CFqakpRciWn006o7$",
                    "trx_to_amount": 20,
                    "trx_to_amount_raw": 200000
                }
            ],
            "addresses": [
                "WEBD$gD$DU#wKt@xIEMU3j@CFqakpRciWn006o7$"
            ],
            "amount": 20,
            "amount_raw": 200000
        },
        "isConfirmed": false
    }
}

getTransactionByBlockHashAndIndex

Returns information about a transaction by block hash and transaction index position.

Parameters
  1. String - hash of a block.
  2. Integer - transaction index position.
params: [
   '44692aa0762d7699d3849837cb823dcfd727b3ff7f65cfc55194484929842e7d',
   0
]
Returns

See getTransactionByHash

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getTransactionByBlockHashAndIndex","params":["44692aa0762d7699d3849837cb823dcfd727b3ff7f65cfc55194484929842e7d", 0],"id":1}'

Result see getTransactionByHash

getTransactionByBlockNumberAndIndex

Returns information about a transaction by block number and transaction index position.

Parameters
  1. Integer|TAG - a block number, or the string "earliest", "latest" or "pending"
  2. Integer - the transaction index position.
params: [
   100678,
   0
]
Returns

See getTransactionByHash

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getTransactionByBlockNumberAndIndex","params":[100678, 0],"id":1}'

Result see getTransactionByHash

Add a custom footer
Add a custom sidebar
Clone this wiki locally