REST API

The REST API provides programmatic control of entry nodes. It uses the same TLS certificate as the tunnel and supports Basic authentication.

Enabling the API

Pass --api <addr> when starting an entry node:

wallhack entry --listen :443 --api 127.0.0.1:6566

Basic authentication is required. A random secret is generated at startup and printed to stdout:

[+] REST API listening on 127.0.0.1:6566
[+]   API username: admin
[+]   API secret:   K7mXpQ2nR9sY4wZtBvLjC6dHfAuE3aNp  (auto-generated)

To set fixed credentials, use --api-user and --api-secret:

wallhack entry --listen :443 --api 127.0.0.1:6566 --api-user operator --api-secret mysecret

The API is served over HTTPS. A self-signed certificate is auto-generated unless --cert and --key are provided.

Example Usage

SECRET=K7mXpQ2nR9sY4wZtBvLjC6dHfAuE3aNp  # from startup output

# Get stats
curl -k -u admin:$SECRET https://localhost:6566/stats

# List peers
curl -k -u admin:$SECRET https://localhost:6566/peers

# Add a route through a peer
curl -k -u admin:$SECRET -X POST https://localhost:6566/routes \
  -H 'Content-Type: application/json' \
  -d '{"cidr": "192.168.1.0/24", "peer": "bench"}'

Endpoints

get /health

Process health

Verifies that the node process is active and responding. Always returns 200. No authentication required.

get /ping

Node status

Retrieves high-level node identity and uptime information.

Response

`uptime_ms`	integer	Node uptime in milliseconds.
`version`	string	Binary version string.
`node_role`	string	Operational role of this node (e.g., Entry, Relay, Exit).

get /stats

Traffic metrics

Retrieves current traffic volume and flow statistics.

Response

`bytes_in`	integer	Total bytes received by the node.
`bytes_out`	integer	Total bytes transmitted by the node.
`packets_in`	integer	Total packets received by the node.
`packets_out`	integer	Total packets transmitted by the node.
`active_connections`	integer	Number of currently active peer connections.
`active_flows`	integer	Number of active L4 network flows being tracked.

get /peers

List connections

Retrieves a list of all currently connected peers.

Response

peers PeerResponse[] List of all currently connected peers.

delete /peers/{name}

Disconnect peer

Terminates the connection with a specific peer.

Parameters

name string Name of the peer to disconnect.

Response

`success`	boolean	Indicates if the requested operation completed successfully.
`message`	string	Optional detail providing context for success or failure.

get /routes

List routing table

Retrieves all active routing entries established through this node.

Response

routes RouteResponse[] List of active routing entries.

post /routes

Add route

Configures a new route to a target network through an active peer.

Body

`cidr`	string	Target network in CIDR notation (e.g., 10.0.0.0/24).
`peer`	string	Name of the peer through which the network should be routed.

Response

`success`	boolean	Indicates if the requested operation completed successfully.
`message`	string	Optional detail providing context for success or failure.

delete /routes/{cidr}

Remove route

Deletes a routing entry by its network specification.

Parameters

cidr string URL-encoded CIDR specification (e.g., 10.0.0.0%2F24).

Response

`success`	boolean	Indicates if the requested operation completed successfully.
`message`	string	Optional detail providing context for success or failure.

get /events

Live event stream

Subscribes to real-time node events (peer lifecycle, latency, stats) via Server-Sent Events (SSE).

Response

`type`	"PeerConnected" \| "PeerDisconnected" \| "PeerLatency" \| "StatsUpdate" \| "Error"	The category of the event.
`data`	object	Event-specific payload data.