API Reference

Complete reference for Epistery's CLI, web endpoints, and client-side JavaScript API

Command Line Interface (CLI)

The Epistery CLI provides domain-based wallet management and authenticated HTTP requests.

epistery initialize

epistery initialize <domain>

Initialize a domain with a new wallet. Creates ~/.epistery/{domain}/config.ini with wallet keys and provider configuration.

                            epistery initialize localhost
epistery initialize wiki.rootz.global
                        

epistery curl

epistery curl [options] <url>

Make authenticated HTTP request. Automatically performs key exchange on first use.

Options:

-w, --wallet <domain> - Use specific domain (overrides default)
-X, --request <method> - HTTP method (default: GET)
-d, --data <data> - Request body data
-H, --header <header> - Additional headers
-b, --bot - Use bot auth header (default: session cookie)
-v, --verbose - Show detailed output

                            # GET request
epistery curl https://wiki.rootz.global/wiki/Home

# POST request
epistery curl -X POST \
  -d '{"title":"Test","body":"# Test"}' \
  https://wiki.rootz.global/wiki/Test

# Bot mode (no session)
epistery curl --bot https://wiki.rootz.global/session/context
                        

epistery info

epistery info [domain]

Show domain information including wallet address, provider configuration, and session status.

                            epistery info              # Show default domain
epistery info localhost     # Show specific domain
                        

epistery set-default

epistery set-default <domain>

Set the default domain for CLI operations, eliminating the need to specify -w flag.

epistery set-default localhost

Web Endpoints

Epistery exposes these endpoints when attached to your web server

/.well-known/epistery

GET /.well-known/epistery

Returns JSON data presenting the signing identity/wallet of the site and its capabilities.

                            {
  "server": {
    "walletAddress": "0x...",
    "provider": "polkadot-hub-testnet",
    "chainId": 420420422
  },
  "capabilities": ["data-wallet", "ipfs"]
}
                        

/.well-known/epistery/status

GET /.well-known/epistery/status

Human-readable version of the above, plus overview of the site's activity and interactive features.

/.well-known/epistery/data/*

                            POST /.well-known/epistery/data/create
GET /.well-known/epistery/data/{id}
PUT /.well-known/epistery/data/{id}
DELETE /.well-known/epistery/data/{id}
                        

Data-wallet module API for creating, reading, updating and deleting data wallets.

Client-Side JavaScript API

Include the Epistery client library to enable blockchain-backed interactions in your web application

Include Library

<script src="/.well-known/epistery/lib/client.js"></script>

Include this script in your HTML to access the window.epistery object.

window.epistery.data.write()

const result = await window.epistery.data.write(data);

Create a data wallet for any digital object. Returns IPFS address and blockchain transaction receipt.

                            const myThing = {
  title: "My Document",
  content: "Hello World"
};

const result = await window.epistery.data.write(myThing);
console.log(result.ipfs.address);
console.log(result.transaction.hash);
                        

window.epistery.data.read()

const data = await window.epistery.data.read(address);

Retrieve data from a data wallet by its IPFS address.

Configuration

Root Configuration

System-wide settings stored in ~/.epistery/config.ini

                            [profile]
name=Your Name
email=your@email.com

[ipfs]
url=https://rootz.digital/api/v0

[default.provider]
chainId=420420422
name=polkadot-hub-testnet
rpc=https://testnet-passet-hub-eth-rpc.polkadot.io

[cli]
default_domain=localhost
                        

Domain Configuration

Per-domain settings stored in ~/.epistery/{domain}/config.ini

                            [domain]
domain=localhost

[wallet]
address=0x...
mnemonic=word word word...
publicKey=0x04...
privateKey=0x...

[provider]
chainId=420420422
name=polkadot-hub-testnet
rpc=https://testnet-passet-hub-eth-rpc.polkadot.io

[ssl]
key=/path/to/key.pem
cert=/path/to/cert.pem
modified=2025-01-10T12:00:00Z
                        

Session Management

CLI sessions auto-saved in ~/.epistery/{domain}/session.json

                            {
  "domain": "https://wiki.rootz.global",
  "cookie": "session_token_here",
  "authenticated": true,
  "timestamp": "2025-01-10T12:00:00.000Z"
}
                        

Server Integration

Install and attach Epistery to your Express.js application

1

Install Package

npm install epistery

2

Initialize Domain

epistery initialize mydomain.com

Creates wallet and configuration in ~/.epistery/mydomain.com/

3

Attach to Express

                                import express from 'express';
import { Epistery } from 'epistery';

const app = express();

// Connect and attach Epistery
const epistery = await Epistery.connect();
await epistery.attach(app);

// Access domain config in your routes
app.use((req, res, next) => {
  const domainConfig = req.app.locals.epistery.domain;
  next();
});

app.listen(3000);
                            

Authentication Modes

Session Cookie (Default)

Performs key exchange once, saves session cookie
Subsequent requests use cookie
Best for multiple requests to same server
Session automatically saved to ~/.epistery/{domain}/session.json

epistery curl https://wiki.rootz.global/wiki/Home

Bot Auth Header

Signs each request individually
No session management required
Best for distributed systems or one-off requests
Use --bot flag

epistery curl --bot https://wiki.rootz.global/session/context

Security

Domain Isolation: Each domain has its own isolated wallet. Keys are stored in ~/.epistery/{domain}/ with 0600 permissions (user-only access).

Private Key Protection: Private keys are never transmitted. Only signatures are sent over the network. All cryptographic operations happen locally.

Browser Wallets: Client-side wallets use browser localStorage, which is strictly domain-isolated per W3C standards. Anonymous, ephemeral identities are perfect for low-value micro-transactions like engagement tracking and ad views.