Saltar al contenido principal

Promotion Gates API

The Promotion Gates API governs the transition of strategy artifacts from the LLM Plane (Research) to the Money Plane (Live Trading). All crossings require a Human-in-the-Loop (HITL) approval step-up MFA.

Since August 2026 the gate chain can additionally require lab evidence (deflated Sharpe / overfitting statistics backed by the trial ledger), and pending requests can expire on a TTL (see Approval queues). Both are default-off feature flags.

Endpoints​

Submit Promotion Request​

POST /promotion/requests

Submits a new promotion request. The request is immediately put through deterministic gates (e.g., risk limits, statistical validation).

Request Body: A serialized StrategyPromotionRequest (alphaswarm_core.contracts) containing:

  • request_id: Unique id for this promotion request.
  • kind: strategy, drl_policy, or allocation.
  • artifact: A ProductionStrategyArtifact (required for strategy/drl_policy kinds) — the production-ready strategy/DRL artifact being promoted.
  • allocation: An AllocationProposal (required for the allocation kind) — the proposed capital allocation.
  • validation: A ValidationVerdict — the independent (SR 11-7 effective-challenge) validation outcome; must not be FAIL.
  • risk: A RiskDecision — the deterministic risk-engine verdict.
  • requested_by: The user or agent submitting the request.
  • requires_human_approval (bool, default true) / human_approved (bool, default false).

Response: The created promotion request object with its initial status (e.g., pending, denied, approved).

List Promotion Requests​

GET /promotion/requests

Lists historical and pending promotion requests.

Query Parameters:

  • status (string, optional): Filter by status (pending, approved, rejected).
  • limit (integer, default: 100).

Get Promotion Detail​

GET /promotion/requests/{request_id}

Retrieves the full detail of a promotion request, including the gate outcomes and human decision logs.

Approve Promotion​

POST /promotion/requests/{request_id}/approve

Requires Step-up MFA.

Approves the promotion request. This triggers the actual deployment/activation of the strategy in the Money Plane.

Request Body:

  • note (string, optional): Approval rationale.

Security:

  • Requires a recent MFA step-up.
  • Implements a four-eyes check: the approver cannot be the same user who submitted the request.

Reject Promotion​

POST /promotion/requests/{request_id}/reject

Requires Step-up MFA.

Rejects the promotion request, preventing it from crossing into the Money Plane.

Revoke Promotion​

POST /promotion/requests/{request_id}/revoke

Requires Step-up MFA.

Retires an already-promoted strategy, flipping it out of promoted status so it stops being treated as live-eligible. Only a request in promoted status can be revoked.

Pending Approvals Queue​

GET /promotion/approvals

Retrieves the list of requests currently awaiting human decision.

Lifecycle Statuses​

  • pending: Awaiting human decision.
  • approved: Human-approved; the deterministic gates passed but the crossing may still require finalization.
  • promoted: The strategy has completed the crossing into the Money Plane.
  • rejected: Human-rejected.
  • denied: Failed deterministic validation gates (e.g. a hard gate such as the kill switch) before or during human review.
  • revoked: A previously promoted strategy has been retired via the revoke endpoint.
  • expired: The request's TTL elapsed before a human decision. Set by the approval-expiry sweeper when approval_expiry_enforcement_enabled is on; deciding an expired request returns HTTP 410 Gone. Requests created before the feature was enabled (expires_at NULL) are never default-expired.

Evidence requirements (flag-gated)​

With ALPHASWARM_PROMOTION_LAB_EVIDENCE_ENFORCE in strict mode, the gate chain fails closed unless the request carries a complete lab EvidenceBundle — deflated Sharpe ratio (DSR), probability of backtest overfitting (PBO), and trial counts sourced from the TrialLedger. With ALPHASWARM_TRIAL_LEDGER_N_ENFORCE on, the DSR/PBO trial count N is derived from the ledger rather than self-reported. Paper execution additionally refuses to start without an ApprovedPromotion token.