> For the complete documentation index, see [llms.txt](https://candora.gitbook.io/whitepaper/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://candora.gitbook.io/whitepaper/candora-grid/connect.md). # Connect External API Gateway and Access Layer ### External Gateway, Traffic Orchestration, and Secure Access Layer Candora Connect is the external-facing gateway and access-control layer of Candora Grid. It is responsible for exposing secure, authenticated, and rate-limited access to trading, account, market-data, and streaming services while acting as the primary trust boundary between external participants and the internal exchange infrastructure. Connect serves as the ingress layer of the Grid. Every external request entering Candora passes through Connect before being transformed into internally sequenced events consumable by Orbit, Pulse, Risk Engine, Oracle, and Vault. Unlike conventional API gateways that primarily forward requests downstream, Connect functions as an ingress-control system designed to preserve execution integrity, platform stability, and infrastructure isolation under high-throughput, volatile, and adversarial conditions. Its objective is to ensure that external traffic cannot directly influence execution, risk, pricing, settlement, or custody systems without first passing through authentication, validation, policy enforcement, congestion controls, and system-level protection mechanisms. Connect operates as a stateless, horizontally scalable gateway cluster positioned at the edge of Candora Grid. ### Gateway Security Model Candora Connect follows a zero-trust security model in which all incoming requests are treated as untrusted until fully validated. Every request traverses a deterministic validation pipeline before it is permitted to enter internal processing pathways: ``` Request → Authentication → Signature Verification → Policy Enforcement → Rate-Limit Evaluation → Gateway Validation → Risk Precheck (where applicable) → Internal Event Emission ``` Trading-related endpoints require cryptographic request signing to ensure request authenticity and payload integrity: ``` Signature = HMAC_SHA256(secret_key, payload + timestamp) ``` This mechanism provides ownership verification, tamper resistance, and replay protection. Additional replay safeguards are enforced through timestamp validation and bounded request windows. Requests that fail authentication, authorization, validation, or policy checks are rejected at the gateway boundary before reaching any internal subsystem. Connect does not independently evaluate solvency, pricing, or execution outcomes. Those responsibilities remain within Risk Engine, Oracle, and Orbit respectively. ### Request Normalization External traffic is never propagated internally in its original form. Instead, Connect converts all accepted requests into a standardized internal event structure: ``` E_request = { request_id, session_id, user_id, endpoint_type, permissions_scope, payload_hash, timestamp, seq_n } ``` This normalization layer isolates internal systems from public API complexity, transport-layer differences, client-specific implementation details, session-management behavior, and networking irregularities. As a result, internal infrastructure consumes a stable event grammar rather than heterogeneous external traffic. This separation allows public interfaces to evolve independently from internal processing systems while preserving deterministic replay behavior and operational consistency. ### Identity and Permission Framework Every API credential within Candora Connect is associated with predefined permission scopes and operating constraints. Authorization is enforced entirely at the gateway boundary before requests enter internal processing pathways. Authentication follows a fixed sequence: ``` Client Request ↓ Signature Validation ↓ Permission Verification ↓ Policy Evaluation ↓ Session Context Generation ↓ Internal Event Routing ``` Connect may additionally support hierarchical authorization models that allow participants to separate trading access, operational access, automated strategies, institutional workflows, and service integrations under independent credentials and permission boundaries. Permission enforcement determines access rights only. It does not influence execution priority, queue position, matching treatment, or any behavior within Orbit. ### Session and Streaming Infrastructure For persistent streaming services, Connect establishes managed session contexts that provide a stable communication layer between external participants and internal infrastructure. A session may be represented as: ``` Session = hash(API_key + timestamp + nonce) ``` Session state may include permission scope, expiration policies, connection limits, streaming classifications, and other operational metadata required for lifecycle management. Streaming infrastructure supports market-data dissemination, account updates, execution notifications, platform telemetry, and other real-time services. During periods of elevated load, Connect may prioritize communications that are directly relevant to execution continuity and account integrity, such as order acknowledgements, execution notifications, liquidation-related updates, and account-state changes. These controls affect communication quality and resource allocation only. They do not alter execution priority, queue position, or matching behavior within Orbit. ### Adaptive Load Management Candora Connect implements a multi-dimensional traffic-management framework designed to protect internal infrastructure from abuse, overload conditions, and traffic amplification events. Rate limits may be enforced across API credentials, sessions, endpoint categories, market namespaces, and connection classes. The underlying throttling mechanism follows a token-bucket model: ``` tokens(t) = min(capacity, tokens_prev + refill_rate × Δt) ``` Different endpoint categories may consume different throughput budgets according to their operational cost and downstream impact. Order-submission pathways, for example, may consume more resources than informational requests due to their interaction with execution and risk infrastructure. Connect continuously monitors gateway utilization, request volume, session pressure, service availability, and shared stress-state conditions. As platform stress increases, ingress policies may become progressively more conservative through tighter rate limits, reduced throughput allowances, increased prioritization of critical traffic classes, and slower processing of non-essential requests. The objective is to preserve service continuity and protect core exchange infrastructure during abnormal operating conditions rather than allowing uncontrolled external demand to propagate into execution systems. ### Gateway Isolation Architecture Connect is isolated from execution, pricing, risk, settlement, and custody systems through strict service boundaries. At a high level, external traffic follows the path: ``` External Traffic → Connect → Validation and Policy Controls → Internal Event Bus → Core Systems ``` Core systems include Orbit, Pulse, Risk Engine, Oracle, and Vault. Connect possesses no authority over custody, settlement, execution, matching, ledger mutation, or order-book state. Its responsibility is limited to validating, normalizing, and routing requests into controlled internal pathways. This separation ensures that compromise of gateway infrastructure does not inherently grant access to execution, settlement, pricing, risk, or custody systems. ### Infrastructure Protection Controls Connect continuously applies defensive controls intended to preserve platform integrity and operational stability. These controls include schema validation, request sanitization, replay protection, rate limiting, traffic isolation, session management, anomaly detection, and dead-letter handling mechanisms. The gateway may additionally monitor behavioral signals such as abnormal request velocity, repeated authentication failures, session abuse patterns, automated traffic anomalies, and persistent policy violations. Requests or sessions exhibiting suspicious behavior may be restricted, rate-limited, suspended, or quarantined according to predefined operating policies. The objective is to maintain predictable and auditable protection behavior while minimizing the impact of malicious or disruptive traffic. ### Shared Stress-State Integration Connect participates in Candora's shared stress-state framework and consumes the common stress signal defined within the [Operational Model](/whitepaper/candora-grid/operational-model.md). As systemic stress increases, ingress behavior may adapt through tighter traffic controls, increased throttling sensitivity, prioritization of execution-critical communications, reduction of non-essential traffic, and more conservative resource-allocation policies. These adjustments are intended to align external traffic flow with current platform operating conditions and infrastructure capacity. Connect may also export gateway telemetry used in stress-state computation, including utilization metrics, congestion indicators, session pressure measurements, and traffic-anomaly signals. This allows ingress conditions to contribute to broader infrastructure awareness while preserving separation of responsibility between subsystems. ### Replay and Auditability All accepted request transitions are recorded as replayable event streams. This enables request reconstruction, event-sequence verification, operational auditing, incident analysis, compliance review, and infrastructure debugging. Recovery follows a deterministic reconstruction process: ``` S_recovered = S_snapshot + Σ Δrequest_events ``` Because Connect participates in sequenced event ordering, replay environments can reproduce request ordering, session transitions, routing outcomes, policy decisions, and traffic-management behavior with consistent results. This supports reproducible analysis across live operation, recovery procedures, testing environments, and simulation systems. ### System Role Summary Candora Connect serves as the external gateway and access-control layer of Candora Grid. It authenticates participants, validates requests, normalizes external traffic, manages streaming sessions, enforces ingress policies, and protects internal infrastructure from abusive or destabilizing traffic conditions. All external interaction with Candora Grid ultimately passes through Connect before entering execution, pricing, risk, settlement, or custody systems, making Connect the foundational ingress and access-control layer of the exchange infrastructure.