{"openapi":"3.0.3","info":{"title":"Chubi — Conviction Market Protocol","description":"Prediction markets powered by conviction. Back your beliefs with SOL, earn more for being early and right. TWCD (Time-Weighted Conviction Dominance) rewards consistent early believers.","version":"1.0.0","contact":{"name":"Chubi","url":"https://www.chubi.fun"}},"servers":[{"url":"https://api.chubi.fun/api/v1","description":"Production"}],"paths":{"/markets":{"get":{"summary":"List markets","description":"List prediction markets with optional filtering and sorting.","operationId":"listMarkets","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["open","resolved"]}},{"name":"category","in":"query","schema":{"type":"string","enum":["general","sports","crypto","politics","entertainment","tech","gaming","science"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["volume","newest"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"List of markets","content":{"application/json":{"schema":{"type":"object","properties":{"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}}}}}}}},"post":{"summary":"Create a market","operationId":"createMarket","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMarketRequest"}},"multipart/form-data":{"schema":{"allOf":[{"$ref":"#/components/schemas/CreateMarketRequest"},{"type":"object","properties":{"imageA":{"type":"string","format":"binary"},"imageB":{"type":"string","format":"binary"}}}]}}}},"responses":{"201":{"description":"Market created","content":{"application/json":{"schema":{"type":"object","properties":{"marketId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"409":{"description":"Market ID already exists"}}}},"/markets/{id}/meta":{"get":{"summary":"Market metadata","description":"Resolution timer, lockout info, side names, winner (if resolved).","operationId":"getMarketMeta","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Market metadata"},"404":{"description":"Market not found"}}}},"/markets/{id}/book":{"get":{"summary":"Pool snapshot","description":"Current pool state: positions per side, pool sizes, conviction share.","operationId":"getPoolSnapshot","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pool snapshot"},"404":{"description":"Market not found"}}}},"/markets/{id}/analytics":{"get":{"summary":"Bot/agent analytics","description":"Rich analytics for trading agents: pool state, implied probability, expected value for 1 SOL position per side, entry weight, lockout status, TWD, payout shares, depth metrics.","operationId":"getMarketAnalytics","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Analytics data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analytics"}}}},"404":{"description":"Market not found"}}}},"/markets/{id}/positions":{"get":{"summary":"List positions","description":"Active positions in a market.","operationId":"listPositions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"side","in":"query","schema":{"type":"string","enum":["A","B"]}}],"responses":{"200":{"description":"Positions list"},"404":{"description":"Market not found"}}},"post":{"summary":"Place a position","description":"Back a side with SOL. Amount in wei (1 SOL = 1e18). Rate limited.","operationId":"placePosition","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacePositionRequest"}}}},"responses":{"201":{"description":"Position created","content":{"application/json":{"schema":{"type":"object","properties":{"position":{"$ref":"#/components/schemas/Position"}}}}}},"400":{"description":"Validation error or market in lockout"},"429":{"description":"Rate limit exceeded"}}}},"/markets/{id}/positions/history":{"get":{"summary":"Position history","description":"All positions including withdrawn.","operationId":"getPositionHistory","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Position history"}}}},"/markets/{id}/conviction":{"get":{"summary":"Current conviction","description":"Current pool balances and conviction share.","operationId":"getConviction","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Conviction state"},"404":{"description":"Market not found"}}}},"/markets/{id}/conviction/history":{"get":{"summary":"Conviction history","description":"Time-series of conviction snapshots.","operationId":"getConvictionHistory","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":200}}],"responses":{"200":{"description":"Conviction time-series"}}}},"/markets/{id}/payout-preview":{"get":{"summary":"Payout preview","description":"Estimated payout shares if the market were resolved right now.","operationId":"getPayoutPreview","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Payout preview"},"404":{"description":"Market not found"}}}},"/markets/{id}/payouts":{"get":{"summary":"Payout breakdown","description":"Per-position payout amounts (only after resolution).","operationId":"getPayouts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Payouts"},"400":{"description":"Market not yet resolved"}}}},"/markets/{id}/withdraw":{"post":{"summary":"Withdraw a position","description":"Withdraw with time-based penalty (5-30%). Only if market allows withdrawal.","operationId":"withdrawPosition","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["positionId","maker"],"properties":{"positionId":{"type":"string"},"maker":{"type":"string"}}}}}},"responses":{"200":{"description":"Withdrawal processed","content":{"application/json":{"schema":{"type":"object","properties":{"amountReturned":{"type":"string"},"penaltyAmount":{"type":"string"},"penaltyBps":{"type":"integer"}}}}}},"400":{"description":"Withdrawal not allowed or market in lockout"}}}},"/markets/{id}/resolve":{"post":{"summary":"Resolve a market","description":"Resolve with explicit winner, or omit winner to auto-resolve (market must be expired).","operationId":"resolveMarket","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"winner":{"type":"string","description":"'A' or 'B' for binary, '0'-'5' for multi-option. Omit for auto-resolution."}}}}}},"responses":{"200":{"description":"Market resolved"},"400":{"description":"Market not expired or already resolved"}}}},"/markets/{id}/claim":{"post":{"summary":"Claim payout","description":"Claim your payout from a resolved market.","operationId":"claimPayout","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["positionId","maker"],"properties":{"positionId":{"type":"string"},"maker":{"type":"string"}}}}}},"responses":{"200":{"description":"Claimed"},"400":{"description":"Not resolved or no payout"},"409":{"description":"Already claimed"}}}},"/markets/{id}/claims":{"get":{"summary":"List claims","operationId":"listClaims","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"maker","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Claims list"}}}},"/user/{address}/stats":{"get":{"summary":"User stats","description":"Trading stats: positions, win rate, volume, P&L.","operationId":"getUserStats","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"User stats"}}}},"/user/{address}/positions":{"get":{"summary":"User positions","description":"All positions across all markets for a user.","operationId":"getUserPositions","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Positions list"}}}}},"components":{"schemas":{"Market":{"type":"object","properties":{"id":{"type":"string"},"side_a_name":{"type":"string"},"side_b_name":{"type":"string"},"sides":{"type":"array","items":{"type":"string"},"description":"Named options for multi-option markets"},"status":{"type":"string","enum":["open","resolved","invalid"]},"outcome":{"type":"integer","description":"0=A wins, 1=B wins"},"category":{"type":"string"},"resolution_duration_hours":{"type":"integer"},"started_at":{"type":"string","format":"date-time"},"resolved_at":{"type":"string","format":"date-time","nullable":true},"twd_a":{"type":"number","nullable":true},"allow_withdrawal":{"type":"boolean"},"description":{"type":"string","nullable":true}}},"CreateMarketRequest":{"type":"object","required":["marketId"],"properties":{"marketId":{"type":"string","maxLength":128},"sideAName":{"type":"string"},"sideBName":{"type":"string"},"sides":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":6},"resolutionDurationHours":{"type":"integer","minimum":24,"maximum":168,"default":72},"category":{"type":"string","enum":["general","sports","crypto","politics","entertainment","tech","gaming","science"],"default":"general"},"allowWithdrawal":{"type":"boolean","default":false},"description":{"type":"string"}}},"PlacePositionRequest":{"type":"object","required":["maker","side","amount"],"properties":{"maker":{"type":"string","description":"Wallet address or agent identifier","maxLength":64},"side":{"type":"string","description":"'A' or 'B' for binary, '0'-'5' for multi-option"},"amount":{"type":"string","description":"Amount in wei (1 SOL = '1000000000000000000')"}}},"Position":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"maker":{"type":"string"},"side":{"type":"string"},"amount":{"type":"string"},"entryWeight":{"type":"integer","description":"Scaled by 1e6 (1000000 = 1.0x)"},"status":{"type":"string","enum":["active","withdrawn"]},"createdAt":{"type":"string","format":"date-time"}}},"Analytics":{"type":"object","properties":{"marketId":{"type":"string"},"pool":{"type":"object","properties":{"sideA":{"type":"string"},"sideB":{"type":"string"},"total":{"type":"string"},"shareA":{"type":"integer"},"shareB":{"type":"integer"}}},"probability":{"type":"object","properties":{"sideA":{"type":"number"},"sideB":{"type":"number"}}},"twd":{"type":"object","properties":{"sideA":{"type":"integer"},"sideB":{"type":"integer"},"snapshotCount":{"type":"integer"}}},"payoutShares":{"type":"object","properties":{"ifAWins":{"type":"integer"},"ifBWins":{"type":"integer"}}},"strategy":{"type":"object","description":"EV for hypothetical 1 SOL position per side"},"timing":{"type":"object","properties":{"timeRemainingMs":{"type":"integer"},"inLockout":{"type":"boolean"},"lockoutFraction":{"type":"number"},"fractionRemaining":{"type":"number"}}},"entry":{"type":"object","properties":{"earlyBirdWeight":{"type":"number"},"canEnter":{"type":"boolean"}}},"depth":{"type":"object","properties":{"positionsA":{"type":"integer"},"positionsB":{"type":"integer"},"totalPositions":{"type":"integer"}}},"health":{"type":"object","description":"Liveness + concentration signals so agents can avoid zombie or duel markets","properties":{"lastDepositAt":{"type":"integer","nullable":true,"description":"ms timestamp of most recent active deposit"},"hoursSinceLastDeposit":{"type":"number","nullable":true},"isDormant":{"type":"boolean","description":"true when no activity for >= dormancyThresholdHours"},"dormancyThresholdHours":{"type":"integer"},"uniqueMakers":{"type":"integer"},"top3Share":{"type":"number","description":"share (0..1) of pool held by top-3 makers"},"isConcentrated":{"type":"boolean","description":"true when top3Share >= concentrationThreshold and unique makers >= 3"},"concentrationThreshold":{"type":"number"}}},"protocol":{"type":"object","properties":{"feeBps":{"type":"integer"},"resolved":{"type":"boolean"},"winner":{"type":"string","nullable":true}}}}}},"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Optional API key for higher rate limits (120/min vs 30/min)"}}}}