{"openapi":"3.1.0","info":{"title":"PE Governor API","version":"1.0.0","summary":"Deterministic capital-allocation decisions for autonomous agents.","description":"POST a candidate set, portfolio state and owner constraints; receive a deterministic ALLOCATE / REDUCE / REJECT / HOLD decision with the exact permitted amount. Paid per decision in USDC on Base via Coinbase Business checkouts (x402). No execution, custody, brokerage or LLM decisioning.","license":{"name":"Proprietary","identifier":"LicenseRef-Profit-Engine"}},"servers":[{"url":"https://coinbase.solarly.ai"}],"paths":{"/api/pe/v1/governor":{"get":{"operationId":"getGovernorContract","summary":"Machine-readable contract for the governor endpoint","responses":{"200":{"description":"Contract document","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"createGovernorDecision","summary":"Request a deterministic capital-allocation decision","parameters":[{"name":"X-Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Reserves the logical request and is forwarded to Coinbase so exactly one checkout exists."},{"name":"X-Checkout-Id","in":"header","required":false,"schema":{"type":"string","pattern":"^[0-9a-f]{24}$"},"description":"Checkout id issued in the 402 response, sent on retries."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"},"description":"Bearer credit token (prepaid credits path)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GovernorRequest"},"example":{"schema":"pe-governor-request.v1","requestedAt":"2026-08-11T22:30:00.000Z","ownerId":"owner_demo","portfolio":{"asOf":"2026-08-11T22:29:45.000Z","reconciliationCurrent":true,"killSwitchEngaged":false,"equityUsd":250000,"cashAvailableUsd":90000,"grossNotionalUsd":120000,"dailyNotionalUsedUsd":30000,"realizedLossTodayUsd":400,"drawdownPct":1.8,"openPositions":[{"assetId":"ETH-USD","lane":"SPOT","notionalUsd":20000,"managed":true}]},"constraints":{"capitalReserveUsd":25000,"installThresholdUsd":1000,"maxCandidateNotionalUsd":25000,"maxPositionNotionalUsd":40000,"maxPortfolioNotionalUsd":200000,"maxDailyNotionalUsd":75000,"remainingLossBudgetUsd":3000,"maxDailyLossUsd":5000,"maxDrawdownPct":8,"maxConcurrentPositions":12,"maxConcurrentPositionsPerLane":6,"maxPortfolioStalenessSeconds":120,"minimumEdgeBpsByLane":{"EQUITIES":25,"SPOT":30,"FUTURES":40}},"candidates":[{"candidateId":"cand_spot_btc_01","sourceLane":"SPOT","strategyId":"carry_basis_v3","assetId":"BTC-USD","side":"BUY","reduceOnly":false,"requestedNotionalUsd":30000,"maximumLossUsd":1200,"expectedNetEdgeBps":85,"evidenceStatus":"READY","createdAt":"2026-08-11T22:28:00.000Z","expiresAt":"2026-08-11T22:40:00.000Z","metadata":{"venue":"primary","confidence":0.71}},{"candidateId":"cand_eq_msft_02","sourceLane":"EQUITIES","strategyId":"gap_fade_v2","assetId":"MSFT","side":"BUY","reduceOnly":false,"requestedNotionalUsd":12000,"maximumLossUsd":900,"expectedNetEdgeBps":40,"evidenceStatus":"READY","createdAt":"2026-08-11T22:27:10.000Z","expiresAt":"2026-08-11T22:45:00.000Z"}]}}}},"responses":{"200":{"description":"Decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GovernorDecision"}}}},"202":{"description":"Payment authorized or processing; retry with the same idempotency key"},"400":{"description":"Schema validation error"},"402":{"description":"Payment required: 1.00 USDC on Base via Coinbase Business checkout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"409":{"description":"Idempotency conflict: changed body or mismatched checkout"},"413":{"description":"Body larger than 128 KiB"},"429":{"description":"Rate limited"},"503":{"description":"Agentic checkout not enabled"}}}},"/api/pe/v1/catalog":{"get":{"operationId":"getCatalog","responses":{"200":{"description":"Product catalog"}}}},"/api/pe/v1/health":{"get":{"operationId":"getHealth","responses":{"200":{"description":"Service health"}}}},"/api/pe/v1/webhooks/coinbase":{"post":{"operationId":"coinbaseWebhook","summary":"Signed Coinbase Business payment webhook (Hook0 signature)","responses":{"200":{"description":"Accepted"},"401":{"description":"Invalid signature"}}}}},"components":{"schemas":{"GovernorRequest":{"type":"object","additionalProperties":false,"required":["schema","requestedAt","ownerId","portfolio","constraints","candidates"],"properties":{"schema":{"const":"pe-governor-request.v1"},"requestedAt":{"type":"string","format":"date-time"},"ownerId":{"type":"string","maxLength":128},"portfolio":{"$ref":"#/components/schemas/Portfolio"},"constraints":{"$ref":"#/components/schemas/Constraints"},"candidates":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/Candidate"}}}},"Position":{"type":"object","additionalProperties":false,"required":["assetId","lane","notionalUsd","managed"],"properties":{"assetId":{"type":"string","maxLength":128},"lane":{"enum":["EQUITIES","SPOT","FUTURES"]},"notionalUsd":{"type":"number","minimum":0},"managed":{"type":"boolean"}}},"Portfolio":{"type":"object","additionalProperties":false,"required":["asOf","reconciliationCurrent","killSwitchEngaged","equityUsd","cashAvailableUsd","grossNotionalUsd","dailyNotionalUsedUsd","realizedLossTodayUsd","drawdownPct","openPositions"],"properties":{"asOf":{"type":"string","format":"date-time","description":"Snapshot time; must not be in the future."},"reconciliationCurrent":{"type":"boolean"},"killSwitchEngaged":{"type":"boolean"},"equityUsd":{"type":"number","minimum":0},"cashAvailableUsd":{"type":"number","minimum":0},"grossNotionalUsd":{"type":"number","minimum":0},"dailyNotionalUsedUsd":{"type":"number","minimum":0},"realizedLossTodayUsd":{"type":"number","minimum":0},"drawdownPct":{"type":"number","minimum":0,"maximum":100},"openPositions":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Position"}}}},"Constraints":{"type":"object","additionalProperties":false,"required":["capitalReserveUsd","installThresholdUsd","maxCandidateNotionalUsd","maxPositionNotionalUsd","maxPortfolioNotionalUsd","maxDailyNotionalUsd","remainingLossBudgetUsd","maxDailyLossUsd","maxDrawdownPct","maxConcurrentPositions","maxConcurrentPositionsPerLane","maxPortfolioStalenessSeconds","minimumEdgeBpsByLane"],"properties":{"capitalReserveUsd":{"type":"number","minimum":0},"installThresholdUsd":{"type":"number","minimum":0},"maxCandidateNotionalUsd":{"type":"number","minimum":0},"maxPositionNotionalUsd":{"type":"number","minimum":0},"maxPortfolioNotionalUsd":{"type":"number","minimum":0},"maxDailyNotionalUsd":{"type":"number","minimum":0},"remainingLossBudgetUsd":{"type":"number","minimum":0},"maxDailyLossUsd":{"type":"number","minimum":0},"maxDrawdownPct":{"type":"number","minimum":0,"maximum":100},"maxConcurrentPositions":{"type":"integer","minimum":0,"maximum":10000},"maxConcurrentPositionsPerLane":{"type":"integer","minimum":0,"maximum":10000},"maxPortfolioStalenessSeconds":{"type":"integer","minimum":1,"maximum":86400},"minimumEdgeBpsByLane":{"type":"object","additionalProperties":false,"required":["EQUITIES","SPOT","FUTURES"],"properties":{"EQUITIES":{"type":"number"},"SPOT":{"type":"number"},"FUTURES":{"type":"number"}}}}},"Candidate":{"type":"object","additionalProperties":false,"required":["candidateId","sourceLane","strategyId","assetId","side","requestedNotionalUsd","maximumLossUsd","expectedNetEdgeBps","evidenceStatus","createdAt","expiresAt"],"properties":{"candidateId":{"type":"string"},"sourceLane":{"enum":["EQUITIES","SPOT","FUTURES"]},"strategyId":{"type":"string"},"assetId":{"type":"string"},"side":{"enum":["BUY","SELL"]},"reduceOnly":{"type":"boolean","default":false,"description":"SELL candidates only."},"requestedNotionalUsd":{"type":"number","minimum":0},"maximumLossUsd":{"type":"number","minimum":0,"description":"Caller-supplied; must not exceed notional."},"expectedNetEdgeBps":{"type":["number","null"],"description":"Caller-supplied. Never forecast by us."},"evidenceStatus":{"enum":["READY","COLLECTING","REJECTED"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"Must be strictly after createdAt."},"metadata":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}}}},"RiskCheck":{"type":"object","required":["check","status","observed","limit"],"properties":{"check":{"type":"string"},"status":{"enum":["PASS","FAIL","BLOCKED"]},"observed":{"type":["number","string","boolean","null"]},"limit":{"type":["number","string","boolean","null"]}}},"CandidateDecision":{"type":"object","required":["candidateId","decision","allocationAmountUsd","rank","reasons","riskChecks"],"properties":{"candidateId":{"type":"string"},"decision":{"enum":["ALLOCATE","REDUCE","REJECT","HOLD"]},"allocationAmountUsd":{"type":"number"},"rank":{"type":["integer","null"]},"expectedAfterCostProfitUsd":{"type":"number"},"reasons":{"type":"array","items":{"type":"string"}},"riskChecks":{"type":"array","items":{"$ref":"#/components/schemas/RiskCheck"}}}},"GovernorDecision":{"type":"object","required":["schema","policyVersion","generatedAt","decision","allocationAmountUsd","candidates","execution","alpha","audit"],"properties":{"schema":{"const":"pe-governor-decision.v1"},"policyVersion":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"decision":{"enum":["ALLOCATE","REDUCE","REJECT","HOLD"]},"selectedCandidateId":{"type":["string","null"]},"allocationAmountUsd":{"type":"number"},"reasons":{"type":"array","items":{"type":"string"}},"portfolioChecks":{"type":"array","items":{"$ref":"#/components/schemas/RiskCheck"}},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/CandidateDecision"}},"execution":{"type":"object","description":"Always all-false: this service never touches money or venues.","properties":{"performed":{"const":false},"custody":{"const":false},"brokerage":{"const":false},"orderPlacement":{"const":false},"walletControl":{"const":false},"note":{"type":"string"}}},"alpha":{"type":"object","properties":{"independentReturnForecast":{"const":false},"proprietaryAlphaClaim":{"const":false},"expectedEdgeSource":{"const":"caller_supplied"},"maximumLossSource":{"const":"caller_supplied"}}},"audit":{"type":"object","required":["requestHash","decisionHash","policyVersion","generatedAt"],"properties":{"engine":{"const":"pe-governor"},"deterministic":{"const":true},"llmUsed":{"const":false},"policyVersion":{"type":"string"},"requestHash":{"type":"string","description":"SHA-256 of canonical request JSON."},"decisionHash":{"type":"string","description":"SHA-256 of canonical decision JSON."},"generatedAt":{"type":"string","format":"date-time"}}}}},"PaymentRequired":{"type":"object","required":["error","payment"],"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"},"payment":{"type":"object","required":["provider","protocol","currency","network","amount","checkoutId","x402Url"],"properties":{"provider":{"const":"coinbase_business"},"protocol":{"const":"x402"},"scheme":{"const":"auth-capture"},"currency":{"const":"USDC"},"network":{"const":"base"},"amount":{"type":"string","description":"Exact USDC amount, 2 decimals."},"checkoutId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"x402Url":{"type":"string","format":"uri"},"settlementSource":{"const":"CHECKOUT_COMPLETED"}}}}},"Pending":{"type":"object","required":["status","checkoutId"],"properties":{"status":{"enum":["ACTIVE","PROCESSING"]},"checkoutId":{"type":"string","pattern":"^[0-9a-f]{24}$"},"retryAfterSeconds":{"type":"integer"},"message":{"type":"string"}}},"ErrorBody":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}}}}}