> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zhentan.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> The Zhentan server API for queue management, execution, and portfolio data.

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                                                                                        |

<Note>
  Live API playground coming soon. You'll be able to test endpoints directly from this page.
</Note>