Introduction - Zhentan

The Zhentan server exposes a REST API used by the client and agent to manage the transaction lifecycle — from queueing and risk scoring to execution and portfolio data.

Base URL

Environment	URL
Local	`http://localhost:3001`
Production	Set via `NEXT_PUBLIC_BACKEND_URL` in the client

Authentication

The API is currently unauthenticated. It is designed to run locally alongside the client and agent. In production, CORS_ORIGIN restricts access to the configured origin.

Endpoints

Method	Endpoint	Description
`POST`	`/queue`	Propose a signed SafeTx — validated, mirrored to the Safe Transaction Service, risk-scored
`POST`	`/execute`	Relay a queued SafeTx on-chain (agent pays gas; relay-only when user signatures meet the threshold)
`POST`	`/transactions/:id/cosign`	Backup key completes a screening-off SafeTx queued below threshold
`POST`	`/transactions/:id/sign`	User completes an agent-proposed (pre-signed) transaction
`GET`	`/transactions`	List transactions with status
`POST`	`/safe/derive`	Server-side counterfactual address derivation for a new account
`GET`	`/users/by-signer/:address`	Resolve an existing account by its signer key
`GET`	`/safe/nonce`	Next unused Safe nonce (Transaction Service queue-aware)
`GET`	`/invoices`	List pending invoices
`POST`	`/notify-resolve`	Update Telegram message with final outcome
`GET`	`/portfolio`	Live portfolio data via Zerion
`GET`	`/health`	Health check

Live API playground coming soon. You’ll be able to test endpoints directly from this page.