Skip to content

Owner (private) node API

This API is used to query node about various information on the blockchain. Owner (private) API is designed to be used only by owner of the node.

This API is used mostly to manage your connections.

By default, node API is exposed only for local connections and requires authentication.


When running epic node with defaults, owner API URL is available at localhost:3413/v2/owner.

Basic Authentication credentials:

  • user: epic,
  • password saved in ~/.epic/main/.api_secret file.

In order to change URL, authentication and other settings go to (by default) ~/.epic/main/epic-server.toml file.

Make sure your epic node is running before calling API endpoints.

API call must be done via POST requests with JSON payload.

Examples

How to send POST request via cURL

  • With authentication 
    curl -u "epic:$(cat ~/.epic/main/.api_secret)" -d '{\"jsonrpc\": \"2.0\", \"method\": \"get_status\", \"params\": [], \"id\": 1}' -H "Content-Type: application/json" http://localhost:3413/v2/owner
  • Without authentication 
    curl -d '{\"jsonrpc\": \"2.0\", \"method\": \"get_status\", \"params\": [], \"id\": 1}' -H "Content-Type: application/json" http://localhost:3413/v2/owner
  • With authentication 
    curl -u "epic:$(cat ~/.epic/main/.api_secret)" -d '{"jsonrpc": "2.0", "method": "get_status", "params": [], "id": 1}' -H "Content-Type: application/json" http://localhost:3413/v2/owner
  • Without authentication 
    curl -d '{"jsonrpc": "2.0", "method": "get_status", "params": [], "id": 1}' -H "Content-Type: application/json" http://localhost:3413/v2/owner


Example API call:

pip install requests

Python 3.5+
from typing import Union

import requests

api_secret_path = '~\.epic\main\.api_secret'
api_secret = open(api_secret_path, 'r').read()
api_user = 'epic'
api_url = "http://localhost:3413/v2"


def api_call(method: str, params: Union[list, dict], api_type: str):
    payload = {
        'jsonrpc': '2.0',
        'id': 1,
        'method': method,
        'params': params
        }

    url = f"{api_url}/{api_type}"
    auth = (api_user, api_secret)
    response = requests.post(url=url, json=payload, auth=auth)

    try:
        if response.status_code in [200, 201]:
            return response.json()
    except Exception as e:
        print(e)

    return response.text


foreign_call = api_call(method='get_version', params=[], api_type='foreign')
print(foreign_call)

owner_call = api_call(method='get_status', params=[], api_type='owner')
print(owner_call)

npm install request

NodeJS 18.0+
const request = require('request');

const host = "localhost:3413"
const user = 'epic';
const api_secret = " ";  // `cat ~/.epic/main/.api_secret`
const url = `http://${user}:${api_secret}@${host}/v2`

const foreign_method = 'get_version';
const foreign_params = [];
const foreign_payload = {
    id: 1,
    method: foreign_method,
    params: foreign_params,
    jsonrpc: '2.0'
}

const owner_method = 'get_status';
const owner_params = [];
const owner_payload = {
    id: 1,
    method: owner_method,
    params: owner_params,
    jsonrpc: '2.0'
}


// Foreign API Call
request({
    url: `${url}/foreign}`,
    method: "POST",
    json: true,
    body: foreign_payload
}, function (error, response, body){
    console.log(body);
});


// Owner API Call
request({
    url: `${url}/owner}`,
    method: "POST",
    json: true,
    body: owner_payload
}, function (error, response, body){
    console.log(body);
});


Methods

get_status

Returns various information about the node, the network and the current sync status.

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

{
  "id": 1,
    "jsonrpc": "2.0",
    "result": {
      "Ok": {
        "protocol_version": "2",
        "user_agent": "MW/Epic 3.x.x",
        "connections": "8",
        "tip": {
          "height": 371553,
          "last_block_pushed": "00001d1623db988d7ed10c5b6319360a52f20c89b4710474145806ba0e8455ec",
          "prev_block_to_last": "0000029f51bacee81c49a27b4bc9c6c446e03183867c922890f90bb17108d89f",
          "total_difficulty": 1127628411943045
        },
        "sync_status": "header_sync",
        "sync_info": {
          "current_height": 371553,
          "highest_height": 0
        }
      }
    }
}

validate_chain

Trigger a validation of the chain state.

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "Ok": null
  }
}

compact_chain

Trigger a compaction of the chain state to regain storage space.

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "Ok": null
  }
}

get_peers

Retrieves information about peers. If null is provided, get_peers will list all stored peers.

{
    "jsonrpc": "2.0",
    "method": "get_peers",
    "params": ["70.50.33.130:3414"],
    "id": 1
}

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "Ok": [
      {
        "addr": "70.50.33.130:3414",
        "ban_reason": "None",
        "capabilities": {
          "bits": 15
        },
        "flags": "Defunct",
        "last_banned": 0,
        "last_connected": 1570129317,
        "user_agent": "MW/Epic 3.0.0"
      }
    ]
  }
}

get_connected_peers

Retrieves a list of all connected peers.

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "Ok": [
      {
        "addr": "35.176.195.242:3414",
        "capabilities": {
          "bits": 15
        },
        "direction": "Outbound",
        "height": 374510,
        "total_difficulty": 1133954621205750,
        "user_agent": "MW/Epic 3.0.0",
        "version": 1
      },
      {
        "addr": "47.97.198.21:3414",
        "capabilities": {
          "bits": 15
        },
        "direction": "Outbound",
        "height": 374510,
        "total_difficulty": 1133954621205750,
        "user_agent": "MW/Epic 3.0.0",
        "version": 1
      },
      {
        "addr": "148.251.16.13:3414",
        "capabilities": {
          "bits": 15
        },
        "direction": "Outbound",
        "height": 374510,
        "total_difficulty": 1133954621205750,
        "user_agent": "MW/Epic 3.0.0",
        "version": 1
      },
    ]
  }
}

ban_peer

Bans a specific peer.

{
    "jsonrpc": "2.0",
    "method": "ban_peer",
    "params": ["70.50.33.130:3414"],
    "id": 1
}

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "Ok": null
  }
}

unban_peer

Unbans a specific peer.

{
    "jsonrpc": "2.0",
    "method": "unban_peer",
    "params": ["70.50.33.130:3414"],
    "id": 1
}

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "Ok": null
  }
}


RUST Implementation

pub trait OwnerRpc: Sync + Send {
    fn get_status(&self) -> Result<Status, ErrorKind>;

    fn validate_chain(&self) -> Result<(), ErrorKind>;

    fn compact_chain(&self) -> Result<(), ErrorKind>;

    fn get_peers(
        &self, 
        peer_addr: Option<SocketAddr>
    ) -> Result<Vec<PeerData>, ErrorKind>;

    fn get_connected_peers(&self) -> Result<Vec<PeerInfoDisplay>, ErrorKind>;

    fn ban_peer(&self, peer_addr: SocketAddr) -> Result<(), ErrorKind>;

    fn unban_peer(&self, peer_addr: SocketAddr) -> Result<(), ErrorKind>;
}