Product 1

1# product-1.yaml
2# Product definition for version 1 of an agentic analytics platform on prediction markets.
3# Source: design exploration on 2026-09-20. Update this file as decisions are made.
4
5doc:
6  title: Product 1
7  description: Version 1 product definition for the agentic prediction-market analytics platform
8  icon: compass
9  updated: 2026-09-20
10
11product:
12  name: kalshi-ai            # working name; repo name, not final brand
13  version: 1
14  one_liner: >
15    Agentic research and trade-recommendation platform for prediction markets.
16    Kalshi first, venue-agnostic by design.
17  status: design
18
19scope:
20  in:
21    - Agentic scan of all open markets on a schedule, producing a ranked shortlist
22    - Agentic deep analysis of a single market on demand
23    - Trade recommendation per market: side, size, entry, exit, invalidation, or abstain
24    - Plain-language explanation of every recommendation
25    - Logged recommendations with resolution tracking and public calibration stats
26    - Freemium tiers with credit metering
27    - Stablecoin payments
28    - Clerk authentication
29  out:
30    - Live trading account management of any kind
31    - Placing, modifying, or cancelling orders on behalf of users
32    - Holding user exchange API keys or wallet keys
33    - Portfolio sync from exchange accounts
34  decided:
35    - id: D1
36      decision: Version 1 is analysis and recommendation only. No execution.
37      decided_on: 2026-09-20
38      note: >
39        Users act on recommendations themselves. The app deep-links to the market
40        on the venue. The provider interface excludes execution methods entirely
41        so the boundary is structural, not a config flag.
42
43venues:
44  design_rule: >
45    One MarketProvider interface, one normalized market model, one adapter per venue.
46    Nothing outside the adapter may import venue-specific types.
47  normalized_model:
48    market:
49      - id                  # venue-prefixed, e.g. kalshi:KXBTC-26SEP30-T100000
50      - venue
51      - event_id
52      - title
53      - resolution_rules    # verbatim text from the venue
54      - resolution_source
55      - outcomes[]          # binary markets have exactly two
56      - close_time
57      - resolve_time
58      - status              # open | closed | resolved
59    outcome:
60      - label
61      - price               # probability 0..1, normalized from cents or USDC
62      - bid
63      - ask
64      - volume_24h
65      - open_interest
66      - liquidity_score     # derived, venue-agnostic
67    history_point:
68      - ts
69      - price
70      - volume
71  provider_interface:
72    - listMarkets(filter)
73    - getMarket(id)
74    - getOrderBook(id)
75    - getHistory(id, range)
76    - getEvents(filter)
77    - getResolution(id)
78  adapters:
79    - venue: kalshi
80      priority: 1
81      api: REST v2 plus WebSocket; RSA-signed auth for authenticated endpoints
82      notes: series -> event -> market hierarchy; prices in cents
83    - venue: polymarket
84      priority: 2
85      api: Gamma API for metadata, CLOB API for prices
86      notes: outcome tokens priced in USDC; first target for cross-venue checks
87
88agents:
89  shared_rules:
90    - Every run has hard caps on tool calls, tokens, and wall time
91    - Every run is a background job, never inside a request handler
92    - Every output is structured and stored before any UI renders it
93    - Web research must cite sources; model recall is not evidence
94    - Resolution rules are quoted verbatim in output, with the agent's reading of edge cases
95  scanner:
96    purpose: Find markets worth attention across all open markets
97    cadence: scheduled; delayed for free tier, fresh for paid tiers
98    model_tier: cost-efficient
99    signals:
100      - price vs base rate
101      - thin liquidity or wide spread
102      - mutually exclusive outcomes summing well over 1.0
103      - same event priced differently across venues
104      - high volume near resolution
105    output: ranked shortlist with one-line rationale per market; shared across all users
106  analyst:
107    purpose: Form an independent probability for one market
108    trigger: on demand, or automatically for paid watchlists
109    model_tier: frontier
110    steps:
111      - read resolution rules literally
112      - pull order book and price history
113      - research the underlying question with a search tool
114      - estimate probability with a confidence band
115      - compare to market price and state the edge
116    output: probability, confidence, edge, evidence with citations, rules reading
117  strategist:
118    purpose: Turn an analyst result into a recommendation
119    positions:
120      - YES
121      - NO
122      - ABSTAIN            # fairly priced or too uncertain; a first-class answer
123      - WAIT               # conditional entry with a stated trigger price
124    output:
125      - position
126      - size_guidance      # fraction of stated risk budget, Kelly-derived and capped
127      - entry_price
128      - exit_conditions
129      - invalidation       # what would make the thesis wrong
130      - explanation
131    rules:
132      - ABSTAIN rate is reported, never hidden
133      - never references user account balances (none exist in v1)
134
135track_record:
136  purpose: Credibility and marketing; built before the first user
137  log_per_recommendation:
138    - market_id
139    - venue
140    - ts
141    - market_price_at_rec
142    - model_probability
143    - position
144    - tier_that_produced_it
145    - model_ids_used
146  on_resolution:
147    - outcome
148    - brier_contribution
149    - hypothetical_pnl_at_rec_price
150  public_page:
151    - Brier score over time
152    - abstain rate
153    - hypothetical P&L by position type and venue
154
155tiers:
156  metering: credits           # per-action cost, tuned without changing the product
157  free:
158    price: 0
159    includes:
160      - browse and search all markets
161      - delayed scanner shortlist
162      - small monthly credit grant for deep analyses
163      - public track record
164    cost_note: scanner and track record are shared computation; cheap to serve
165  standard:
166    includes:
167      - daily fresh scanner
168      - meaningful monthly credit grant
169      - watchlists
170      - resolution alerts
171      - private history
172  elite:
173    includes:
174      - real-time scanner
175      - cross-venue arbitrage feed
176      - auto-analysis on watchlist changes
177      - API access
178      - larger credit grant
179  pricing: TBD
180
181payments:
182  method: stablecoins only     # per founder direction; card fallback is an open question
183  constraint: wallets cannot be charged on a schedule
184  candidate_models:
185    - prepaid_periods          # pay 1, 3, or 12 months up front
186    - credit_top_ups           # buy balance; tiers become spend thresholds
187  candidate_processors:
188    - Coinbase Commerce        # hosted USDC checkout, webhooks, no custody
189    - Stripe stablecoin        # same posture, existing subscription tooling
190  rule: no custody of funds or keys on our side in v1
191
192auth:
193  provider: clerk
194  rule: tier and entitlements live in our database keyed by Clerk user id, not Clerk metadata
195  note: Clerk Billing is card-based via Stripe; not used
196
197stack:
198  web: Next.js 16.3.5           # read node_modules/next/dist/docs before writing code
199  language: TypeScript
200  package_manager: pnpm
201  db: DynamoDB                   # single-table design; AWS SDK v3 with DynamoDB Toolbox or ElectroDB
202  jobs: Inngest or Trigger.dev   # scanner schedule, long-running analyses, retries
203  llm: Claude API with tool use  # verify current model ids and pricing from docs at build time
204  layout:
205    - apps/web                   # Next app
206    - packages/providers         # MarketProvider interface and adapters
207    - packages/agents            # scanner, analyst, strategist
208    - packages/db                # table definitions, entity models, access patterns
209
210risks:
211  - id: R1
212    risk: Personalized paid recommendations may look like Commodity Trading Advisor activity
213    mitigation: Fintech counsel before taking payment; research-and-analytics framing; disclaimers
214    status: open
215  - id: R2
216    risk: LLM misreads resolution criteria
217    mitigation: verbatim rules in output; explicit edge-case reading; citations required
218  - id: R3
219    risk: Unbounded agent cost on free users
220    mitigation: hard caps per run; credit check before job start; shared scanner output
221  - id: R4
222    risk: Stablecoin-only checkout limits conversion
223    mitigation: decide on card fallback timing; see D3
224  - id: R5
225    risk: Venue API terms may restrict advisory use
226    mitigation: review Kalshi and Polymarket developer terms during adapter work
227
228open_decisions:
229  - id: D2
230    question: Stablecoin recurrence model
231    options: [prepaid_periods, credit_top_ups, both]
232  - id: D3
233    question: Card fallback ever, later, or never
234  - id: D4
235    question: Legal counsel engaged, or draft the questions to bring to one
236  - id: D5
237    question: Free tier split between shared computation and per-user quota
238    lean: shared scanner output plus a small personal quota
239  - id: D6
240    question: Pricing for standard and elite
241
242milestones:
243  - id: M1
244    name: vertical slice
245    goal: Kalshi adapter, one market analyzed end to end, recommendation logged with tracked outcome
246    excludes: auth, billing, UI polish
247    why: validates the interesting part before any infrastructure that depends on it
248  - id: M2
249    name: scanner and track record
250  - id: M3
251    name: auth, tiers, credit ledger
252  - id: M4
253    name: stablecoin payments
254  - id: M5
255    name: polymarket adapter and cross-venue signals