Skip to content

Stratum mining server API

This page describes the current Stratum RPC protocol implemented in EPIC.

This API is used to communicate between epic stratum server and mining software.

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


When running epic node with defaults, stratum API URL is available at localhost:3416.

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

API Methods

getjobtemplate

A message initiated by the miner. Miner can request a job with this message.

{
   "id":"2",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "params":null
}
OK response
{
   "id":"0",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "result":{
      "difficulty":1,
      "height":13726,
      "job_id":4,
      "pre_pow":"00010000000000003c4d0171369781424b39c81eb39de10cdf4a7cc27bbc6769203c7c9bc02cc6a1dfc6000000005b50f8210000000000395f123c6856055aab2369fe325c3d709b129dee5c96f2db60cdbc0dc123a80cb0b89e883ae2614f8dbd169888a95c0513b1ac7e069de82e5d479cf838281f7838b4bf75ea7c9222a1ad7406a4cab29af4e018c402f70dc8e9ef3d085169391c78741c656ec0f11f62d41b463c82737970afaa431c5cabb9b759cdfa52d761ac451276084366d1ba9efff2db9ed07eec1bcd8da352b32227f452dfa987ad249f689d9780000000000000b9e00000000000009954"
   }
}
Error response
{
   "id":"10",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "error":{
      "code":-32000,
      "message":"Node is syncing - Please wait"
   }
}

job

A message initiated by the Stratum server. Stratum server will send job automatically to connected miners. The miner SHOULD interrupt current job if job_id = 0, and SHOULD replace the current job with this one after the current graph is complete.

{
   "id":"Stratum",
   "jsonrpc":"2.0",
   "method":"job",
   "params":{
      "difficulty":1,
      "height":16375,
      "job_id":5,
      "pre_pow":"00010000000000003ff723bc8c987b0c594794a0487e52260c5343288749c7e288de95a80afa558c5fb8000000005b51f15f00000000003cadef6a45edf92d2520bf45cbd4f36b5ef283c53d8266bbe9aa1b8daaa1458ce5578fcb0978b3995dd00e3bfc5a9277190bb9407a30d66aec26ff55a2b50214b22cdc1f3894f27374f568b2fe94d857b6b3808124888dd5eff7e8de7e451ac805a4ebd6551fa7a529a1b9f35f761719ed41bfef6ab081defc45a64a374dfd8321feac083741f29207b044071d93904986fa322df610e210c543c2f95522c9bdaef5f598000000000000c184000000000000a0cf"
   }
}

No response is required for this message.

keepalive

A message initiated by the miner in order to keep the connection alive.

{
   "id":"2",
   "jsonrpc":"2.0",
   "method":"keepalive",
   "params":null
}

{
   "id":"2",
   "jsonrpc":"2.0",
   "method":"keepalive",
   "result":"ok",
   "error":null
}

login

A message initiated by the miner. Miner can log in on a EPIC Stratum server with a login, password and agent (usually statically set by the miner program).

{
   "id":"0",
   "jsonrpc":"2.0",
   "method":"login",
   "params":{
      "login":"login",
      "pass":"password",
      "agent":"epic-miner"
   }
}

{
   "id":"1",
   "jsonrpc":"2.0",
   "method":"login",
   "result":"ok",
   "error":null
}

Not yet implemented. Should return error -32500 "Login first" when login is required.

status

A message initiated by the miner. This message allows a miner to get the status of its current worker and the network.

{
   "id":"2",
   "jsonrpc":"2.0",
   "method":"status",
   "params":null
}

{
   "id":"5",
   "jsonrpc":"2.0",
   "method":"status",
   "result":{
      "id":"5",
      "height":13726,
      "difficulty":1,
      "accepted":0,
      "rejected":0,
      "stale":0
   },
   "error":null
}

submit

A message initiated by the miner. When a miner find a share, it will submit it to the node.

{
   "id":"0",
   "jsonrpc":"2.0",
   "method":"submit",
   "params":{
      "edge_bits":29,
      "height":16419,
      "job_id":0,
      "nonce":8895699060858340771,
      "pow":[
         4210040,10141596,13269632,24291934,28079062,84254573,84493890,100560174,100657333,120128285,130518226,140371663,142109188,159800646,163323737,171019100,176840047,191220010,192245584,198941444,209276164,216952635,217795152,225662613,230166736,231315079,248639876,263910393,293995691,298361937,326412694,330363619,414572127,424798984,426489226,466671748,466924466,490048497,495035248,496623057,502828197, 532838434
         ]
   }
}

{
   "id":"2",
   "jsonrpc":"2.0",
   "method":"submit",
   "result":"ok",
   "error":null
}

{
   "id":"6",
   "jsonrpc":"2.0",
   "method":"submit",
   "result":"blockfound - 23025af9032de812d15228121d5e4b0e977d30ad8036ab07131104787b9dcf10",
   "error":null
}

{
   "id":"5",
   "jsonrpc":"2.0",
   "method":"submit",
   "error":{
      "code":-32503,
      "message":"Solution submitted too late"
   }
}

Two possibilities: the solution cannot be validated or the solution is of too low difficulty. 

{
   "id":"5",
   "jsonrpc":"2.0",
   "method":"submit",
   "error":{
      "code":-32502,
      "message":"Failed to validate solution"
   }
}

{
   "id":"5",
   "jsonrpc":"2.0",
   "method":"submit",
   "error":{
      "code":-32501,
      "message":"Share rejected due to low difficulty"
   }
}


Error Messages

EPIC Stratum protocol implementation contains the following error messages:

Error code Error Message
-32000 Node is syncing - please wait
-32500 Login first
-32501 Share rejected due to low difficulty
-32502 Failed to validate solution
-32503 Solution Submitted too late
-32600 Invalid Request
-32601 Method not found

Miner behavior

Info

Miners SHOULD, MAY or MUST respect the following rules:

  • Miners SHOULD randomize the job nonce before starting
  • Miners MUST continue mining the same job until the server sends a new one, though a miner MAY request a new job at any time
  • Miners MUST NOT send RPC response to a job request from the server
  • Miners MAY set the RPC "id" and expect responses to have that same id
  • Miners MAY send a keepalive message
  • Miners MAY send a login request (to identify which miner finds shares / solutions in the logs), the login request MUST have all 3 params.
  • Miners MUST return the supplied job_id with submit messages.