{
  "openapi": "3.1.0",
  "info": {"title":"1CLAW Operator API","version":"1.0.0","description":"Integration preview. Server-only bearer keys bind wallet, operator and games. Native seamless-wallet callbacks are documented separately."},
  "servers": [{"url":"https://api.1claw.bet/operator/v1","description":"1CLAW operator API"}],
  "security": [{"OperatorKey":[]}],
  "paths": {
    "/games": {"get":{"operationId":"listGames","description":"Available game catalogue","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"features":{"type":"array","items":{"type":"string"}}},"required":["id","title","features"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},
    "/launches": {"post":{"operationId":"createLaunch","description":"Create an iframe URL containing your short-lived player session key.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false}}}},"400":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Launch"}}}}}},
    "/players/{playerId}/rounds": {"get":{"operationId":"listRounds","description":"Settled rounds including zero wins. Decimal money and UTC timestamps. Cursor pagination.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Round"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"playerId","in":"path","required":true,"schema":{"type":"string","maxLength":255}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"game","in":"query","required":false,"schema":{"type":"string","example":"3-mummy-piggies"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}]}},
    "/players/{playerId}/rounds/{roundId}": {"get":{"operationId":"getRound","description":"One settled round owned by your wallet/operator/player.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Round"}}}},"400":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"playerId","in":"path","required":true,"schema":{"type":"string","maxLength":255}},{"name":"roundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},
    "/free-spins": {"post":{"operationId":"grantFreeSpins","description":"Reference is the durable idempotency key within wallet/operator. Identical retries return current grant progress; changed parameters return 409. Player must have launched once. One active grant per player/game; finish it before a different reference.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Grant"}}}},"400":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreeSpins"}}}}}},
    "/free-spins/{reference}": {"get":{"operationId":"getFreeSpins","description":"Current grant progress; pending rounds may settle after expiry.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Grant"}}}},"400":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed; see error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,80}$"}}]}}
  },
  "components": {
    "securitySchemes": {"OperatorKey":{"type":"http","scheme":"bearer"}},
    "schemas": {
    "Launch": {"type":"object","properties":{"game":{"type":"string","example":"3-mummy-piggies"},"sessionKey":{"type":"string","minLength":1,"maxLength":4096},"language":{"type":"string","default":"en"},"device":{"type":"string","enum":["desktop","mobile"],"default":"desktop"}},"required":["game","sessionKey"],"additionalProperties":false},
    "Round": {"type":"object","properties":{"roundId":{"type":"string","format":"uuid"},"time":{"type":"string","format":"date-time"},"game":{"type":"string","example":"3-mummy-piggies"},"currency":{"type":"string","example":"usd"},"bet":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","example":"0.20"},"win":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","example":"0.20"}},"required":["roundId","time","game","currency","bet","win"],"additionalProperties":false},
    "FreeSpins": {"type":"object","properties":{"reference":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,80}$"},"playerId":{"type":"string","minLength":1,"maxLength":255},"game":{"type":"string","example":"3-mummy-piggies"},"count":{"type":"integer","minimum":1,"maximum":1000},"bet":{"type":"string","pattern":"^\\d{1,8}(\\.\\d{1,8})?$","example":"0.20"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"expiresAt":{"type":"string","format":"date-time"}},"required":["reference","playerId","game","count","bet","currency","expiresAt"],"additionalProperties":false},
    "Grant": {"type":"object","properties":{"reference":{"type":"string"},"game":{"type":"string","example":"3-mummy-piggies"},"count":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"pending":{"type":"integer"},"bet":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","example":"0.20"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"win":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","example":"0.20"},"expiresAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["active","settling","completed","expired"]}},"required":["reference","game","count","used","remaining","pending","bet","currency","win","expiresAt","status"],"additionalProperties":false},
    "Error": {"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}}}}}}
    }
  }
}