Code examples

Runnable examples for the workflows most integrations need, as a command line and as Python.

Node queries

Chain height, blocks, mempool and peers. No authentication ceremony, good first target.

Wallet: connect and read

The encrypted handshake, opening a wallet, and reading a balance.

Wallet: send and receive

A complete transfer, receiving, cancelling and payment proofs.

Which surface to target

Task	Surface	Credential
Node status, peers	Node /v2/owner	Basic, secret auto-created
Blocks, headers, kernels, mempool	Node /v2/foreign	None
Submit a raw transaction	Node /v2/foreign	None
Anything involving keys or balances	Wallet Owner API /v3/owner	ECDH handshake and a wallet token
Receive a transfer	Wallet Foreign API, or epic-wallet listen	None

The node's JSON-RPC methods are split across two paths: /v2/owner is administration, and every chain read is on /v2/foreign. See the node API.

Prerequisites

CLI

curl and jq.

sudo apt install curl jq      # Debian and Ubuntu

winget install jqlang.jq      # Windows, where curl is already present

Python

Python 3.10 or newer.

pip install requests coincurve pycryptodome

coincurve provides secp256k1 and pycryptodome provides AES-GCM, both for the wallet Owner API. Node queries need requests alone.

Conventions in these examples

• Run commands from the examples directory of the repository, which is where the Python modules import each other from.
• The node is at port 3413, the wallet Owner API at 3420 and the wallet Foreign API at 3415. Every client honours NODE_URL, EPIC_OWNER_URL and EPIC_FOREIGN_URL so you can point it somewhere else.
• Amounts are integers, counted in freeman. 1 EPIC is 100,000,000.
• Secrets are read from their files, and the wallet password from EPIC_WALLET_PASSWORD.

The response envelope

Every Epic JSON-RPC method returns HTTP 200 with a JSON-RPC result, and inside that result is a second envelope. A successful operation carries Ok:

{"id": 1, "jsonrpc": "2.0", "result": {"Ok": {"...": "the actual data"}}}

A failed one carries Err in the same position:

{"id": 1, "jsonrpc": "2.0", "result": {"Err": {"NotEnoughFunds": {"available": 0, "needed": 100000000}}}}

Write one unwrap helper and use it everywhere. _unwrap in the wallet client on connect and read raises on Err and returns the value on Ok, and every call in that client goes through it.

Field by field, the envelope is documented in the API overview.

Where the reference clients live

The wallet repository ships a Python client that performs the same handshake: doc/samples/python/secure_api_example.py.

The method signatures are defined in api/src/owner_rpc_s.rs, which carries a worked JSON request and response in the documentation comment for almost every method.