Skip to main content
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

​
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.