{"openapi":"3.1.0","info":{"title":"Quesen","description":"**Deterministic Trust and Settlement Layer for Autonomous Agents.**\n\nQuesen is protocol infrastructure — not a SaaS product. Autonomous agents call Quesen *before* taking high-risk actions and receive one explainable answer (`SKIP` / `PROCEED` / `INVESTIGATE`) plus a numeric risk score. When they run out of credits, they negotiate over the **Agent Settlement Protocol (ASP/1.0)** — HTTP 402 → signed quote → provable settlement → signed receipt — rather than through a browser.\n\n**Endpoint tiers**\n- **T0 · Operational** — `/health`, `/version`, `/asp/version`.\n- **T1 · Protocol Plane (constitutional)** — every `/asp/*` endpoint.\n- **T2 · Decision engine** — `/validate`, `/report`.\n- **T3 · Sales / analytics** — `/simulate`, `/stats`.\n- **T4 · Convenience billing rails** — every `/billing/*` endpoint.\n\nSee `enshrine/041-asp-v1-specification.md` for the ASP wire spec and `DOCTRINE.md §17` for the constitutional layer discipline.\n","contact":{"name":"Quesen · S.I.B. Supreme Bureau","url":"https://github.com/Shxnque/Quesen-sib"},"license":{"name":"See repository","url":"https://github.com/Shxnque/Quesen-sib"},"version":"1.10.0"},"paths":{"/mcp":{"post":{"tags":["MCP"],"summary":"MCP JSON-RPC endpoint (Streamable HTTP)","description":"Streamable HTTP MCP transport.\n\nAccepts a JSON-RPC 2.0 request body (or a batch array) and returns\nthe corresponding response object. Notifications (no `id`) return\nHTTP 202 with an empty body.\n\nThis endpoint is intentionally stateless — no `Mcp-Session-Id` is\nrequired. Every request carries the full context it needs.","operationId":"mcp_endpoint_mcp_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/tsc/validate":{"post":{"tags":["TSC v2 (experimental)"],"summary":"Tsc Validate","description":"Evaluate a Typed Security Context (v2). Deterministic PASS/REVIEW/BLOCK/SKIP.","operationId":"tsc_validate_tsc_validate_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tsc/version":{"get":{"tags":["TSC v2 (experimental)"],"summary":"Tsc Version","description":"Public TSC v2 capability metadata (only present when the flag is on).","operationId":"tsc_version_tsc_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Tsc Version Tsc Version Get"}}}}}}},"/health":{"get":{"tags":["Operational"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/version":{"get":{"tags":["Operational"],"summary":"Version","operationId":"version_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Version Version Get"}}}}}}},"/asp/version":{"get":{"tags":["ASP"],"summary":"Asp Version","description":"Public ASP protocol metadata. Deterministic. No auth.","operationId":"asp_version_asp_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Asp Version Asp Version Get"}}}}}}},"/asp/quotes":{"post":{"tags":["ASP"],"summary":"Asp Create Quote","description":"Mint a signed settlement quote (ASP/1.0).\n\n- Stateless: no server-side write; the quote is the state.\n- Deterministic: identical inputs → identical quote_id + signature.\n- Expires: `expires_at = issued_at + ttl_seconds`.","operationId":"asp_create_quote_asp_quotes_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementQuoteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementQuote"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/asp/quotes/verify":{"post":{"tags":["ASP"],"summary":"Asp Verify Quote","description":"Stateless verification of a signed quote.","operationId":"asp_verify_quote_asp_quotes_verify_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementQuote"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteVerificationResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/asp/providers":{"get":{"tags":["ASP"],"summary":"Asp List Providers","description":"List every SettlementProviderAdapter currently registered on this worker.","operationId":"asp_list_providers_asp_providers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Asp List Providers Asp Providers Get"}}}}}}},"/asp/redeem":{"post":{"tags":["ASP"],"summary":"Asp Redeem Endpoint","description":"Redeem a settlement proof against a signed quote (ADR-036).\n\nVerifies: quote signature + expiry, adapter presence, adapter-scoped\nproof, and global replay guard. On success, credits the target api_key\n(identified by sha256 hash) and mints a signed SettlementReceipt.\n\nStateless from ASP's point of view except for:\n  - in-memory replay-guard set (per worker)\n  - in-memory credit ledger (per worker)\nBoth are ADR-033 candidates for future persistence.","operationId":"asp_redeem_endpoint_asp_redeem_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedemptionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementReceipt"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/asp/credits/{api_key_hash}":{"get":{"tags":["ASP"],"summary":"Asp Credits Lookup","description":"Return the current credit balance for a given API key sha256 hash.\n\nThe raw API key never appears in this endpoint. The client hashes their\nown key locally and queries the hash. This preserves the doctrine\nagainst PII (Doctrine §2) at the ASP boundary.","operationId":"asp_credits_lookup_asp_credits__api_key_hash__get","parameters":[{"name":"api_key_hash","in":"path","required":true,"schema":{"type":"string","title":"Api Key Hash"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Asp Credits Lookup Asp Credits  Api Key Hash  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/asp/ledger":{"get":{"tags":["ASP"],"summary":"Asp Ledger Recent","description":"Admin-only view of recent credit events. Provider-neutral.","operationId":"asp_ledger_recent_asp_ledger_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Asp Ledger Recent Asp Ledger Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/sandbox/keys":{"post":{"tags":["Sales / Analytics"],"summary":"Issue Sandbox Key Endpoint","description":"Self-serve a FREE, rate-limited sandbox API key — no signup, no card.\n\nUse the returned key as the `X-API-Key` header against `/validate`,\n`/simulate`, and `/report`. The engine is deterministic (same inputs ->\nsame decision). Sandbox keys are zero-cost and rate-limited; for production\nvolume see `/billing/plans`. The request body is optional — an empty\n`POST /sandbox/keys` works.","operationId":"issue_sandbox_key_endpoint_sandbox_keys_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SandboxKeyRequest"},{"type":"null"}],"title":"Payload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/validate":{"post":{"tags":["Decision Engine"],"summary":"Validate","operationId":"validate_validate_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/simulate":{"post":{"tags":["Sales / Analytics"],"summary":"Simulate","operationId":"simulate_simulate_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/report":{"post":{"tags":["Decision Engine"],"summary":"Report","operationId":"report_report_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stats":{"get":{"tags":["Sales / Analytics"],"summary":"Stats","operationId":"stats_stats_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/telegram/webhook":{"post":{"tags":["Operational"],"summary":"Telegram Webhook","description":"Inbound Telegram webhook. Renders /status | /stats | /reports | /skiprate |\n/version | /keys | /help as S.I.B briefing cards and sends them back to\nthe operator's chat. Security:\n  1. Requires `QUESEN_TELEGRAM_BOT_TOKEN` + `QUESEN_TELEGRAM_CHAT_ID` set.\n  2. Optional `QUESEN_TELEGRAM_WEBHOOK_SECRET` — if set, the incoming\n     `X-Telegram-Bot-Api-Secret-Token` header must match verbatim.\n  3. Only responds to the operator's configured chat_id. All other chats\n     are silently acknowledged (`{\"ok\": true, \"handled\": false}`).\nFail-closed: on unexpected payload structure, returns 200 with\n`handled=false` (never crashes the Telegram bot).","operationId":"telegram_webhook_telegram_webhook_post","parameters":[{"name":"X-Telegram-Bot-Api-Secret-Token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Telegram-Bot-Api-Secret-Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Telegram Webhook Telegram Webhook Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/plans":{"get":{"tags":["Billing (convenience)"],"summary":"Billing Catalog","description":"Public pricing catalog. No auth required. Deterministic output.","operationId":"billing_catalog_billing_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}}}}},"/billing/stripe/checkout":{"post":{"tags":["Billing (convenience)"],"summary":"Create Stripe Checkout","operationId":"create_stripe_checkout_billing_stripe_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/stripe/status/{session_id}":{"get":{"tags":["Billing (convenience)"],"summary":"Stripe Status","operationId":"stripe_status_billing_stripe_status__session_id__get","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/stripe/webhook":{"post":{"tags":["Billing (convenience)"],"summary":"Stripe Webhook","operationId":"stripe_webhook_billing_stripe_webhook_post","parameters":[{"name":"Stripe-Signature","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe-Signature"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/crypto/checkout":{"post":{"tags":["Billing (convenience)"],"summary":"Create Crypto Checkout","operationId":"create_crypto_checkout_billing_crypto_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/crypto/status/{charge_id}":{"get":{"tags":["Billing (convenience)"],"summary":"Crypto Status","operationId":"crypto_status_billing_crypto_status__charge_id__get","parameters":[{"name":"charge_id","in":"path","required":true,"schema":{"type":"string","title":"Charge Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/crypto/webhook":{"post":{"tags":["Billing (convenience)"],"summary":"Crypto Webhook","operationId":"crypto_webhook_billing_crypto_webhook_post","parameters":[{"name":"X-CC-Webhook-Signature","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Cc-Webhook-Signature"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CatalogResponse":{"properties":{"plans":{"items":{"$ref":"#/components/schemas/PlanPublic"},"type":"array","title":"Plans"},"packs":{"items":{"$ref":"#/components/schemas/PackPublic"},"type":"array","title":"Packs"},"payment_providers":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Payment Providers","description":"Which providers are configured on the server (booleans)."},"currency":{"type":"string","title":"Currency","default":"USD"}},"type":"object","required":["plans","packs"],"title":"CatalogResponse"},"CheckoutCreateRequest":{"properties":{"target":{"type":"string","enum":["plan","pack"],"title":"Target"},"target_id":{"type":"string","title":"Target Id"},"origin_url":{"type":"string","maxLength":512,"minLength":8,"title":"Origin Url"},"email":{"anyOf":[{"type":"string","maxLength":254},{"type":"null"}],"title":"Email"},"client_reference_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Client Reference Id"}},"type":"object","required":["target","target_id","origin_url"],"title":"CheckoutCreateRequest","description":"Frontend/agent-initiated checkout request. The caller specifies:\n  - target: 'plan' | 'pack'\n  - target_id: 'starter' | 'pack_10k' etc.\n  - origin_url: caller's public origin so we can craft success/cancel URLs\n  - email: optional customer email hint"},"CheckoutCreateResponse":{"properties":{"provider":{"type":"string","title":"Provider"},"session_id":{"type":"string","title":"Session Id"},"checkout_url":{"type":"string","title":"Checkout Url"},"target":{"type":"string","title":"Target"},"target_id":{"type":"string","title":"Target Id"},"amount_usd":{"type":"number","title":"Amount Usd"}},"type":"object","required":["provider","session_id","checkout_url","target","target_id","amount_usd"],"title":"CheckoutCreateResponse"},"CheckoutStatusResponse":{"properties":{"provider":{"type":"string","title":"Provider"},"session_id":{"type":"string","title":"Session Id"},"payment_status":{"type":"string","title":"Payment Status"},"status":{"type":"string","title":"Status"},"amount_total_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount Total Usd"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"metadata":{"additionalProperties":{"type":"string"},"type":"object","title":"Metadata"}},"type":"object","required":["provider","session_id","payment_status","status"],"title":"CheckoutStatusResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","enum":["ok"],"const":"ok","title":"Status"},"engine_version":{"type":"string","title":"Engine Version"}},"type":"object","required":["status","engine_version"],"title":"HealthResponse"},"HolderConcentration":{"properties":{"top1_share":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Top1 Share"},"top5_share":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Top5 Share"},"top10_share":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Top10 Share"},"total_holders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Total Holders"},"unknown_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unknown Reason"}},"additionalProperties":false,"type":"object","title":"HolderConcentration"},"KeyStats":{"properties":{"owner":{"type":"string","title":"Owner"},"price_per_call":{"type":"number","title":"Price Per Call"},"rate_limit_per_min":{"type":"integer","title":"Rate Limit Per Min"},"call_count":{"type":"integer","title":"Call Count"},"earnings":{"type":"number","title":"Earnings"}},"type":"object","required":["owner","price_per_call","rate_limit_per_min","call_count","earnings"],"title":"KeyStats"},"OnchainEnrichment":{"properties":{"chain":{"type":"string","title":"Chain"},"chain_id":{"type":"integer","title":"Chain Id"},"contract_address":{"type":"string","title":"Contract Address"},"has_code":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Code"},"creation_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Creation Block"},"contract_age_days":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Contract Age Days"},"source_verification":{"$ref":"#/components/schemas/SourceVerification"},"proxy":{"$ref":"#/components/schemas/ProxyInfo"},"ownership":{"$ref":"#/components/schemas/OwnershipModel"},"holder_concentration":{"$ref":"#/components/schemas/HolderConcentration"},"probes_run":{"items":{"type":"string"},"type":"array","title":"Probes Run"},"probes_skipped":{"items":{"type":"string"},"type":"array","title":"Probes Skipped"},"errors":{"items":{"type":"string"},"type":"array","title":"Errors"},"status":{"type":"string","enum":["full","partial","disabled","no_config","invalid_input"],"title":"Status","default":"partial"}},"additionalProperties":false,"type":"object","required":["chain","chain_id","contract_address"],"title":"OnchainEnrichment","description":"Full on-chain enrichment envelope. All sub-objects are optional; every\nmissing datum is accompanied by an `unknown_reason`."},"OwnershipModel":{"properties":{"owner_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Address"},"renounced":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Renounced"},"unknown_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unknown Reason"}},"additionalProperties":false,"type":"object","title":"OwnershipModel"},"PackPublic":{"properties":{"id":{"type":"string","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"calls":{"type":"integer","title":"Calls"},"price_usd":{"type":"number","title":"Price Usd"},"unit_cost_usd":{"type":"number","title":"Unit Cost Usd"}},"type":"object","required":["id","display_name","calls","price_usd","unit_cost_usd"],"title":"PackPublic"},"PlanPublic":{"properties":{"id":{"type":"string","title":"Id"},"display_name":{"type":"string","title":"Display Name"},"monthly_usd":{"type":"number","title":"Monthly Usd"},"included_calls":{"type":"integer","title":"Included Calls"},"overage_usd_per_call":{"type":"number","title":"Overage Usd Per Call"},"rate_limit_per_min":{"type":"integer","title":"Rate Limit Per Min"},"features":{"items":{"type":"string"},"type":"array","title":"Features"},"audience":{"type":"string","title":"Audience"}},"type":"object","required":["id","display_name","monthly_usd","included_calls","overage_usd_per_call","rate_limit_per_min","features","audience"],"title":"PlanPublic","description":"Public-safe plan snapshot returned by /billing/plans."},"ProxyInfo":{"properties":{"is_proxy":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Proxy"},"proxy_standard":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Proxy Standard"},"implementation_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Implementation Address"},"admin_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Admin Address"},"unknown_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unknown Reason"}},"additionalProperties":false,"type":"object","title":"ProxyInfo"},"QuoteVerificationResult":{"properties":{"valid":{"type":"boolean","title":"Valid"},"quote_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Id"},"protocol_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocol Version"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"seconds_until_expiry":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seconds Until Expiry"}},"additionalProperties":false,"type":"object","required":["valid"],"title":"QuoteVerificationResult","description":"Response envelope for `POST /asp/quotes/verify`."},"RedemptionRequest":{"properties":{"quote":{"$ref":"#/components/schemas/SettlementQuote"},"proof":{"$ref":"#/components/schemas/SettlementProof"},"reference":{"$ref":"#/components/schemas/SettlementReference"},"api_key_hash":{"type":"string","maxLength":64,"minLength":64,"title":"Api Key Hash","description":"sha256 hex of the API key to credit."}},"additionalProperties":false,"type":"object","required":["quote","proof","reference","api_key_hash"],"title":"RedemptionRequest"},"ReportOutcomeCounters":{"properties":{"total":{"type":"integer","title":"Total"},"by_outcome":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Outcome"},"pnl_reported_count":{"type":"integer","title":"Pnl Reported Count"},"pnl_mean":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pnl Mean"}},"type":"object","required":["total","by_outcome","pnl_reported_count"],"title":"ReportOutcomeCounters","description":"Aggregate counters exposed on /stats + returned in /report response."},"ReportRequest":{"properties":{"request_id":{"type":"string","maxLength":128,"minLength":1,"title":"Request Id"},"outcome":{"type":"string","enum":["RUG","LOSS","OK","WIN","UNKNOWN"],"title":"Outcome"},"notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Notes"},"realized_pnl":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Realized Pnl","description":"Signed realized P&L in the caller's unit. Aggregated as a mean only."},"elapsed_seconds":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Elapsed Seconds","description":"Wall-clock seconds between /validate response and this /report."},"venue":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Venue","description":"Free-text venue tag (chain, DEX, framework). Not persisted; audit-log-only."},"signal_hash":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Signal Hash","description":"Optional caller-side fingerprint linking this outcome to the original signal set."},"client_request_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Client Request Id","description":"Optional client trace id (parallels /validate)."}},"additionalProperties":false,"type":"object","required":["request_id","outcome"],"title":"ReportRequest","description":"Post-decision outcome feedback (v1.3.0+ · report_schema_version=1.1.0).\n\nv1.1.0 additions are ALL optional — backward compatible with the v1.0.0\n`{request_id, outcome, notes}` contract that shipped in Quesen 1.0.0.\nNew callers can attach post-trade metadata for future clustering; old\ncallers keep working with no change."},"ReportResponse":{"properties":{"accepted":{"type":"boolean","title":"Accepted"},"received_at":{"type":"string","title":"Received At"},"request_id":{"type":"string","title":"Request Id"},"report_schema_version":{"type":"string","title":"Report Schema Version"},"engine_version":{"type":"string","title":"Engine Version"},"counters":{"$ref":"#/components/schemas/ReportOutcomeCounters"}},"type":"object","required":["accepted","received_at","request_id","report_schema_version","engine_version","counters"],"title":"ReportResponse"},"SandboxKeyRequest":{"properties":{"label":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Label","description":"Optional label to help you recognise this key."}},"type":"object","title":"SandboxKeyRequest"},"SandboxKeyResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"tier":{"type":"string","title":"Tier"},"price_per_call":{"type":"number","title":"Price Per Call"},"rate_limit_per_min":{"type":"integer","title":"Rate Limit Per Min"},"starter_credits":{"type":"integer","title":"Starter Credits"},"engine_version":{"type":"string","title":"Engine Version"},"quickstart":{"type":"object","title":"Quickstart"},"note":{"type":"string","title":"Note"}},"type":"object","required":["api_key","tier","price_per_call","rate_limit_per_min","starter_credits","engine_version","quickstart","note"],"title":"SandboxKeyResponse"},"SettlementProof":{"properties":{"provider_id":{"type":"string","maxLength":64,"minLength":1,"title":"Provider Id"},"proof_type":{"type":"string","maxLength":64,"minLength":1,"title":"Proof Type","description":"e.g. 'webhook_signed', 'onchain_receipt', 'signed_attestation'."},"payload":{"type":"object","title":"Payload","description":"Provider-defined opaque data. Never interpreted by ASP."},"provider_signature":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Provider Signature"},"issued_at":{"type":"string","title":"Issued At"}},"additionalProperties":false,"type":"object","required":["provider_id","proof_type","issued_at"],"title":"SettlementProof","description":"Provider-issued verifiable evidence of settlement.\n\nThe `payload` is opaque to ASP — the provider adapter interprets it\ninside `SettlementProviderAdapter.verify_proof(...)`. ASP itself never\nparses provider payloads; it only rides on the adapter's decision."},"SettlementQuote":{"properties":{"protocol_version":{"type":"string","title":"Protocol Version","default":"ASP/1.0"},"quote_id":{"type":"string","maxLength":64,"minLength":1,"title":"Quote Id"},"resource":{"type":"string","maxLength":128,"minLength":1,"title":"Resource"},"amount_asserted":{"type":"number","minimum":0.0,"title":"Amount Asserted","description":"Amount denominated in `amount_currency`. Providers convert as needed."},"amount_currency":{"type":"string","maxLength":8,"minLength":3,"title":"Amount Currency","default":"USD"},"credits":{"type":"integer","minimum":0.0,"title":"Credits","description":"Protocol credits granted upon successful settlement."},"issued_at":{"type":"string","maxLength":40,"minLength":20,"title":"Issued At","description":"ISO-8601 UTC (`YYYY-MM-DDTHH:MM:SSZ`)."},"expires_at":{"type":"string","maxLength":40,"minLength":20,"title":"Expires At"},"kid":{"type":"string","maxLength":16,"minLength":1,"title":"Kid","default":"asp1"},"provider_hints":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Provider Hints"},"metadata":{"additionalProperties":{"type":"string"},"type":"object","title":"Metadata"},"signature":{"type":"string","maxLength":256,"minLength":8,"title":"Signature","description":"`<kid>.<b64url_no_pad(HMAC-SHA256(secret, canonical(unsigned_body)))>`."}},"additionalProperties":false,"type":"object","required":["quote_id","resource","amount_asserted","credits","issued_at","expires_at","signature"],"title":"SettlementQuote","description":"A cryptographically signed offer to settle.\n\nThe quote is self-contained. Once minted, the server may forget it.\nAgents present the quote back to any implementing provider adapter, or\nto the ASP verify endpoint, and get the same authoritative answer."},"SettlementQuoteRequest":{"properties":{"resource":{"type":"string","maxLength":128,"minLength":1,"title":"Resource","description":"Opaque resource identifier. Convention: 'plan:<id>' | 'pack:<id>' | 'credits:<N>'."},"ttl_seconds":{"type":"integer","maximum":86400.0,"minimum":30.0,"title":"Ttl Seconds","description":"Quote validity window in seconds. Default 10 min, max 24 h.","default":600},"issued_at_override":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issued At Override","description":"Optional ISO-8601 UTC timestamp for deterministic replay. Requires operator scope in the future."},"provider_hints":{"items":{"type":"string"},"type":"array","maxItems":16,"title":"Provider Hints","description":"Non-authoritative hint list of providers the caller prefers."},"metadata":{"additionalProperties":{"type":"string"},"type":"object","title":"Metadata","description":"Opaque, small (<= 8 keys, values <= 128 chars). Echoed at redemption."},"client_reference_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Client Reference Id"}},"additionalProperties":false,"type":"object","required":["resource"],"title":"SettlementQuoteRequest","description":"Client → server request to mint a settlement quote.\n\nASP is stateless: the server never stores this request. All state that\nmatters (amount, credits, expiry) is baked into the signed quote body."},"SettlementReceipt":{"properties":{"protocol_version":{"type":"string","title":"Protocol Version","default":"ASP/1.0"},"receipt_id":{"type":"string","maxLength":64,"minLength":1,"title":"Receipt Id"},"quote_id":{"type":"string","maxLength":64,"minLength":1,"title":"Quote Id"},"settlement_reference":{"$ref":"#/components/schemas/SettlementReference"},"credits_granted":{"type":"integer","minimum":0.0,"title":"Credits Granted"},"settled_at":{"type":"string","title":"Settled At"},"kid":{"type":"string","title":"Kid","default":"asp1"},"signature":{"type":"string","maxLength":256,"minLength":8,"title":"Signature"}},"additionalProperties":false,"type":"object","required":["receipt_id","quote_id","settlement_reference","credits_granted","settled_at","signature"],"title":"SettlementReceipt","description":"ASP-signed acknowledgement issued to the agent after successful redemption.\n\nThe receipt itself is HMAC-signed with the same ASP secret used for\nquote signing. Agents may present it to Quesen (or any ASP-compliant\nserver) as proof of entitlement."},"SettlementReference":{"properties":{"provider_id":{"type":"string","maxLength":64,"minLength":1,"title":"Provider Id"},"reference_id":{"type":"string","maxLength":256,"minLength":1,"title":"Reference Id"},"reference_type":{"type":"string","maxLength":32,"minLength":1,"title":"Reference Type","description":"Provider-neutral type tag: 'session' | 'charge' | 'invoice' | 'intent'."},"checkout_url":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"title":"Checkout Url"},"issued_at":{"type":"string","title":"Issued At"}},"additionalProperties":false,"type":"object","required":["provider_id","reference_id","reference_type","issued_at"],"title":"SettlementReference","description":"Opaque provider-side handle returned after a provider begins settlement.\n\nNever contains PII. Never mentions the provider brand in a field name."},"SimulateDelta":{"properties":{"risk_score_delta":{"type":"number","title":"Risk Score Delta"},"decision_changed":{"type":"boolean","title":"Decision Changed"}},"type":"object","required":["risk_score_delta","decision_changed"],"title":"SimulateDelta"},"SimulateRequest":{"properties":{"domain_age_days":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Domain Age Days"},"engagement_ratio":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Engagement Ratio"},"scam_keyword_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Scam Keyword Count"},"weights_override":{"anyOf":[{"$ref":"#/components/schemas/WeightsSnapshot"},{"type":"null"}]},"thresholds_override":{"anyOf":[{"$ref":"#/components/schemas/ThresholdsSnapshot"},{"type":"null"}]},"client_request_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Client Request Id"}},"additionalProperties":false,"type":"object","title":"SimulateRequest","description":"Counterfactual scoring — override weights/thresholds without mutating engine state."},"SimulateResponse":{"properties":{"baseline":{"$ref":"#/components/schemas/ValidateResponse"},"simulated":{"$ref":"#/components/schemas/ValidateResponse"},"delta":{"$ref":"#/components/schemas/SimulateDelta"}},"type":"object","required":["baseline","simulated","delta"],"title":"SimulateResponse"},"SourceVerification":{"properties":{"is_verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Verified"},"unknown_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unknown Reason"},"explorer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Explorer"}},"additionalProperties":false,"type":"object","title":"SourceVerification"},"StatsResponse":{"properties":{"engine_version":{"type":"string","title":"Engine Version"},"keys":{"additionalProperties":{"$ref":"#/components/schemas/KeyStats"},"type":"object","title":"Keys"},"total_calls":{"type":"integer","title":"Total Calls"},"total_earnings":{"type":"number","title":"Total Earnings"},"telegram_enabled":{"type":"boolean","title":"Telegram Enabled"},"report_schema_version":{"type":"string","title":"Report Schema Version"},"reports":{"$ref":"#/components/schemas/ReportOutcomeCounters"}},"type":"object","required":["engine_version","keys","total_calls","total_earnings","telegram_enabled","report_schema_version","reports"],"title":"StatsResponse"},"ThresholdsSnapshot":{"properties":{"skip":{"type":"number","title":"Skip"},"review":{"type":"number","title":"Review"}},"type":"object","required":["skip","review"],"title":"ThresholdsSnapshot"},"ValidateRequest":{"properties":{"domain_age_days":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Domain Age Days","description":"Age of the target domain in days."},"engagement_ratio":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Engagement Ratio","description":"Normalized engagement ratio (likes+replies / followers)."},"scam_keyword_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Scam Keyword Count","description":"Count of known scam keywords detected."},"client_request_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Client Request Id","description":"Optional client trace id."},"chain":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Chain","description":"Optional EVM chain slug (ethereum, base, arbitrum, optimism, polygon, bnb, avalanche)."},"contract_address":{"anyOf":[{"type":"string","maxLength":42,"minLength":42},{"type":"null"}],"title":"Contract Address","description":"Optional 0x-prefixed EVM contract address to enrich against."}},"additionalProperties":false,"type":"object","title":"ValidateRequest","description":"Input envelope sent by an agent before acting on an opportunity.\n\nv1.5.0 (Session 04) added OPTIONAL on-chain enrichment inputs:\n    chain, contract_address\nBoth are additive; callers who don't supply them see zero change."},"ValidateResponse":{"properties":{"decision":{"type":"string","enum":["PROCEED","REVIEW","SKIP"],"title":"Decision"},"risk_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Risk Score"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence"},"conflict_triggers":{"items":{"type":"string"},"type":"array","title":"Conflict Triggers"},"latency_ms":{"type":"integer","title":"Latency Ms"},"request_id":{"type":"string","title":"Request Id"},"engine_version":{"type":"string","title":"Engine Version"},"weights":{"$ref":"#/components/schemas/WeightsSnapshot"},"thresholds":{"$ref":"#/components/schemas/ThresholdsSnapshot"},"client_request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Request Id"},"key_owner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Owner"},"onchain_enrichment":{"anyOf":[{"$ref":"#/components/schemas/OnchainEnrichment"},{"type":"null"}]},"input_snapshot_hash":{"type":"string","maxLength":64,"minLength":64,"title":"Input Snapshot Hash","description":"Lowercase hex-encoded SHA-256 over canonical-JSON of the received request payload, excluding client_request_id. Enables self-contained replay of any verdict."},"commit_sha":{"type":"string","title":"Commit Sha","description":"Git commit SHA of Shxnque/quesen HEAD live at decision time (40 lowercase hex chars), or the sentinel 'unknown' when detached HEAD or locally-built artifact. Enables the caller to pin the exact ruleset that produced the verdict."}},"type":"object","required":["decision","risk_score","confidence","conflict_triggers","latency_ms","request_id","engine_version","weights","thresholds","input_snapshot_hash","commit_sha"],"title":"ValidateResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookAckResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"provider":{"type":"string","title":"Provider"},"event_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Type"},"processed":{"type":"boolean","title":"Processed","default":false},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["ok","provider"],"title":"WebhookAckResponse"},"WeightsSnapshot":{"properties":{"domain_age":{"type":"number","title":"Domain Age"},"engagement":{"type":"number","title":"Engagement"},"scam_keywords":{"type":"number","title":"Scam Keywords"}},"type":"object","required":["domain_age","engagement","scam_keywords"],"title":"WeightsSnapshot"}}},"tags":[{"name":"Operational","description":"Health, version, and protocol metadata. Unauthenticated."},{"name":"ASP","description":"Agent Settlement Protocol (ASP/1.0). Stateless, provider-agnostic, cryptographically-signed. Constitutional; see DOCTRINE §17."},{"name":"Decision Engine","description":"Deterministic risk evaluation. Requires API key."},{"name":"Sales / Analytics","description":"Sandbox and aggregate views. Free tier friendly."},{"name":"Billing (convenience)","description":"Human-operated rails (Stripe, Coinbase Commerce). Not required by ASP."}]}