API reference
Epic exposes seven programmable surfaces across three pieces of software. Which one you want depends on whether you need chain data or key operations.
Chain data, blocks, the mempool, peers and transaction submission.
Balances, transfers, proofs. 37 methods. This is the one that can spend.
Six listener methods for receiving slates and building mining rewards.
The WebSocket protocol that carries slates between wallets.
Which surfaces expect a credential, and how to put TLS in front of them.
At a glance
| Surface | Where | Protocol | Default port | Can spend |
|---|---|---|---|---|
Node /v1/* | node | REST, chain reads and administration | 3413 | No |
Node /v2/owner | node | JSON-RPC 2.0, node administration | 3413 | No |
Node /v2/foreign | node | JSON-RPC 2.0, chain reads and tx submission | 3413 | No |
Wallet Owner /v3/owner | wallet | JSON-RPC 2.0, encrypted | 3420 | Yes |
Wallet Owner /v2/owner | wallet | JSON-RPC 2.0, unencrypted | 3420 | Yes |
Wallet Foreign /v2/foreign | wallet | JSON-RPC 2.0 | 3415 | No |
| Epicbox relay | relay | WebSocket over TLS | 443 | No |
Documented against node 4.0.3 and wallet 4.0.0.
The node serves /v1 and /v2 from one listener on one port, as
two interface styles rather than two generations. Both are live and
that page maps every v1 route onto its JSON-RPC method.
The wallet serves its two owner surfaces from one listener too, and the unencrypted
/v2/owner is the older of the pair.
Choosing a surface
Reading chain data. JSON-RPC on the node: /v2/foreign for blocks, kernels and outputs,
/v2/owner for node status and peers. No keys involved. Start at
node queries.
Anything involving balances, keys or transfers. Wallet Owner API. It requires an ECDH handshake and a wallet token, which is covered step by step in connect and read.
Receiving a payment. Running epic-wallet listen handles this automatically via the epicbox protocol
or HTTP. To process a slate programmatically, the Foreign API method is receive_tx.
Operating relay infrastructure. The epicbox protocol.
The response envelope
Every Epic JSON-RPC method returns HTTP 200 with a JSON-RPC result, and inside that result is a second
Ok or Err envelope. A request can succeed at both the HTTP and JSON-RPC layers and still have failed:
{"id": 1, "jsonrpc": "2.0", "result": {"Ok": {"...": "data"}}}
{"id": 1, "jsonrpc": "2.0", "result": {"Err": {"NotEnoughFunds": {"available": 0}}}}
One function unwraps both layers. _unwrap in
examples/python/epic_wallet.py
raises on Err and returns the value on Ok, and every call in that client goes through it.
Amounts
Every amount is an integer count of freemans, and 1 EPIC is
100,000,000 of them. The wallet Owner API serialises its u64 fields as JSON strings, so
retrieve_summary_info returns total and every amount_ field as a string, and node_height
returns height as one. Parse before doing arithmetic. The node's JSON-RPC returns bare integers,
including supply and max_supply on get_status.