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

# Technical Flow

> End-to-end request lifecycle: payment, orchestration, execution, verification, and payout

This page explains how a request moves through Terminus from first API call to final response.

## System Path

Every request passes through five stages:

1. payment handshake,
2. orchestration and selection,
3. specialist execution,
4. verification and settlement,
5. response and telemetry.

## End-to-End Sequence

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client as Dashboard / Client Agent
    participant CP as Control Plane
    participant Node as Specialist Node
    participant Settle as x402 Settlement Path

    User->>Client: Submit request
    Client->>CP: POST /api/chat (unsigned)
    CP-->>Client: 402 + PAYMENT-REQUIRED
    Client->>CP: POST /api/chat + PAYMENT-SIGNATURE

    CP->>CP: Validate payment requirements
    CP->>CP: Analyze intent + select specialists
    CP->>Node: Dispatch job(s)

    activate Node
    Node->>Node: Execute provider + tools
    Node-->>CP: Return execution result
    deactivate Node

    CP->>CP: Verify results + aggregate output
    CP->>Settle: Settle user payment
    CP->>Settle: Distribute supplier payouts
    CP-->>Client: 200 + response + payment metadata
    Client-->>User: Render final answer
```

## Stage 1: Payment Handshake

`/api/chat` uses x402 request semantics:

* first call receives `PAYMENT-REQUIRED`,
* client retries with `PAYMENT-SIGNATURE`,
* successful path returns `PAYMENT-RESPONSE`.

This keeps payment tied to a single request lifecycle instead of account-credit side effects.

## Stage 2: Orchestration and Supplier Selection

After payment validation, control plane:

* classifies the request intent,
* selects specialist candidates,
* applies liveness and availability filters,
* reserves dispatch targets to avoid race collisions.

The goal is deterministic routing under parallel load.

## Stage 3: Specialist Execution

Specialist nodes execute jobs on operator infrastructure and return structured outcomes.

Execution may include:

* model calls,
* tool calls,
* domain-specific post-processing.

Control plane treats execution output as untrusted until origin and integrity checks pass.

## Stage 4: Verification, Settlement, and Payout

Control plane verifies:

* node identity and authenticated session,
* execution integrity and success conditions,
* aggregation consistency for final output.

Charging rule:

* charge only when the request is successful and at least one specialist execution is successful,
* if no specialist succeeds, settlement is skipped.

Payout rule:

* payout is allocated only to successful contributing suppliers,
* payout metadata is returned in response payload for auditability.

Compensation direction:

* payout logic is moving toward complexity-aware weighting (effort, quality, reliability, and scarcity signals), while preserving deterministic settlement.

## Stage 5: Response and Telemetry

Client receives:

* final aggregated response,
* payment and payout metadata,
* status fields required for UI and analytics.

In parallel, telemetry is emitted for:

* reliability metrics,
* node health,
* settlement and payout outcomes.

## Failure Branches

The flow is designed to fail safely:

* payment handshake failure -> no execution,
* no healthy suppliers -> no charge,
* execution failure with zero successful results -> no settlement,
* partial supplier payout failure -> response still returns with payout status details.

## Security Boundaries

Technical flow relies on layered controls:

* challenge-signature auth for worker sessions,
* identity checks for payout eligibility,
* request-level wallet auth on protected user routes,
* admin auth on mutating/debug routes,
* public-safe redacted monitoring outputs.