API Reference

REST API served by the Express server. Base URL is configured via the NEXT_PUBLIC_API_URL environment variable. All requests include credentials: "include" for cookie-based authentication.

Authentication

The server uses SIWS (Sign In With Solana) for authentication. The flow starts with a nonce request, the wallet signs a message containing the nonce, and the server verifies the signature to issue a JWT stored in an httpOnly cookie. All protected routes automatically filter data by the authenticated wallet public key.

Auth Endpoints

POST/api/auth/siws/nonce

Generate a SIWS nonce for wallet signing. Returns a unique nonce string that must be included in the SIWS message signed by the wallet.

POST/api/auth/siws/verify

Verify the wallet signature and issue a JWT. Expects the signed SIWS message and signature in the request body. Sets an httpOnly cookie on success.

DELETE/api/auth/sessionsAuth

Revoke all active sessions for the authenticated wallet and clear the JWT cookie.

Transaction Endpoints

GET/api/transactionsAuth

Paginated list of guarded transactions for the authenticated wallet. Returns transaction signature, verdict, amount, target program, and timestamp.

Query parameters:

limit — Number of results per page (default: 20)
offset — Pagination offset (default: 0)
policy — Filter by policy PDA public key

GET/api/transactions/:sigAuth

Transaction detail by on-chain signature. Includes the Guardian Agent verdict, associated incident (if any), and prev/next navigation links.

Incident Endpoints

GET/api/incidentsAuth

Paginated list of agent pause incidents for the authenticated wallet. Each incident includes the pause reason, who triggered it, and whether a Guardian Agent report is attached.

Query parameters:

limit — Number of results per page (default: 20)
offset — Pagination offset (default: 0)
policy — Filter by policy PDA public key

GET/api/incidents/:idAuth

Incident detail by UUID. Returns the full Guardian Agent report including behavioral analysis, risk assessment, and recommended actions.

Policy Endpoints

GET/api/policiesAuth

All policies owned by the authenticated wallet. Returns policy PDA, agent key, label, active status, and on-chain configuration summary.

PATCH/api/policies/:pubkeyAuth

Update the policy label (a database-only field not stored on-chain). Used for giving agents human-readable names in the dashboard.

Escalation Endpoints

POST/api/escalations/reportAuth

Report an escalated transaction. Called when a guarded_execute fails with EscalatedToMultisig, recording the transaction details for Squads proposal creation.

GET/api/escalationsAuth

List all escalation proposals for policies owned by the authenticated wallet. Includes proposal status, amount, and associated policy.

GET/api/escalations/:idAuth

Escalation detail by UUID. Returns the reconstructed instruction data, target program, amount, and current Squads proposal status.

PATCH/api/escalations/:idAuth

Update an escalation record with the Squads proposal PDA and transaction index after the multisig proposal has been created on-chain.

Fleet Endpoints

GET/api/fleet/summaryAuth

Aggregated fleet metrics for the authenticated wallet. Returns counts of active and paused agents, total incidents, aggregate spend across all policies, and 24h trend data.

GET/api/spend-trackersAuth

On-chain spend tracker snapshots for all policies owned by the wallet. Includes policy metadata, 24h and 1h spend totals, transaction counts, and budget utilization percentages.

Real-Time Events (SSE)

GET/api/eventsAuth

Server-Sent Events stream for real-time dashboard updates. Opens a persistent connection that pushes events as they occur. Events carry full payloads and are inserted directly into the client-side TanStack Query cache.

The SSE stream emits the following event types. Each event includes a type field and a data payload:

Event Type	Description
`new_transaction`	A new guarded transaction has been recorded
`verdict`	Guardian Agent has rendered a verdict on a transaction
`agent_paused`	An agent has been paused via the kill switch
`report_ready`	Guardian Agent incident report is available
`escalation_created`	A new escalation proposal has been created
`escalation_updated`	An escalation proposal status has changed
`agent_rotated`	An agent key rotation has completed
`policy_closed`	A policy has been permanently closed

Audit & Settings

GET/api/auditAuth

Unified action timeline for all policies owned by the wallet. Includes pause, resume, rotate, close, and escalation events in chronological order.

GET/api/sessionAuth

Current JWT session metadata including wallet public key, issued-at timestamp, and expiration.

GET/api/settings/webhook-statusAuth

Helius webhook configuration and ingestion metrics. Returns the registered webhook URL, last event timestamp, and event counts.

GET/api/settings/llmAuth

Resolved LLM model configuration for the Guardian Agent. Returns the active model name, provider, and any overrides.