{"openapi":"3.0.0","info":{"version":"0.0.1","title":"0Wallet Game Service API","description":"\n![Version](https://img.shields.io/badge/version-0.0.1-blue)\n![OAS](https://img.shields.io/badge/OAS-3.0-green)\n\nAPI documentation for Game Services, Catalog, Promotions, and Provider Credentials.\n\n---\n\n## Architecture\n\n> Laravel 13 + RoadRunner  \n> The Laravel API layer handles REST requests and communicates with the Go game microservice via gRPC internally.\n\n---\n\n## Authentication\n\nJWT Bearer token via `tymon/jwt-auth`\n\n| Route Type | Guard | Login Endpoint |\n|------------|-------|----------------|\n| User | `auth:api` | `/v1/user/login` |\n| Admin | `auth:admin` | `/v1/admin/login` |\n\n---\n\n## Multi-tenancy\n\nResolved via the `X-Tenant-Id` request header on every request.\n\n---\n\n## Response Envelope\n\nAll responses use a standardised JSON envelope.\n"},"paths":{"/v1/admin/provider-api-logs":{"get":{"summary":"List provider API logs","description":"Returns a paginated list of provider API log records for the current tenant. Supports filtering by provider, username, status, and date range.\n","tags":["Admin / Provider API Logs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","description":"Number of records per page (default 20)","required":false,"schema":{"type":"integer","default":20,"example":20}},{"name":"offset","in":"query","description":"Number of records to skip (used for pagination)","required":false,"schema":{"type":"integer","default":0,"example":0}},{"name":"provider_id","in":"query","description":"Filter by provider ID","required":false,"schema":{"type":"integer","example":3}},{"name":"username","in":"query","description":"Filter by player username","required":false,"schema":{"type":"string","example":"john_doe"}},{"name":"status","in":"query","description":"Filter by request status","required":false,"schema":{"type":"string","example":"success"}},{"name":"start_date","in":"query","description":"Filter logs created on or after this date (ISO 8601)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"end_date","in":"query","description":"Filter logs created on or before this date (ISO 8601)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-31"}}],"responses":{"200":{"description":"Paginated list of provider API logs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProviderApiLogRecord"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"id":"01JCHG2M8S2ABCDE1234567890","provider_id":3,"provider_name":"Mega888","user_id":"01JCHG2M8S2ABCDE0987654321","username":"john_doe","player_name":"John Doe","endpoint":"/api/v1/balance","request":{"action":"getBalance","playerId":"john_doe"},"response":{"balance":100.0,"currency":"MYR"},"status_code":200,"status":"success","created_at":"2025-01-15T10:30:00Z"}],"meta":{"pagination":{"total":22,"per_page":200,"current_page":1,"last_page":1,"from":1,"to":22,"has_more":false}}}}}},"400":{"description":"Failed to fetch provider API logs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"status":"false","message":"Failed to fetch provider API logs","code":null}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v1/admin/dashboard/summary-user-risk":{"get":{"summary":"User risk dashboard summary","description":"Returns an aggregated risk summary for the current period: total/flagged user counts, risk-level buckets (low / medium / high), and a per-type breakdown with period-over-period trend data. Defaults to the current calendar month when no dates are supplied.\n","tags":["Admin / User Risk"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"type","in":"query","description":"Filter to a single risk type (RiskType enum value)","required":false,"schema":{"$ref":"#/components/schemas/RiskType"}},{"name":"start_date","in":"query","description":"Start of the period to analyse (ISO 8601). Defaults to start of current month.","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"end_date","in":"query","description":"End of the period to analyse (ISO 8601). Defaults to today.","required":false,"schema":{"type":"string","format":"date","example":"2025-01-31"}}],"responses":{"200":{"description":"Risk dashboard summary","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserRiskDashboard"}}},"example":{"data":{"summary":{"total_users":5000,"total_flagged_users":120},"risk_levels":[{"level":"low","label":"Low","user_count":80},{"level":"medium","label":"Medium","user_count":30},{"level":"high","label":"High","user_count":10}],"breakdown":[{"type":2,"type_label":"Login IP","user_count":45,"percentage":37.5,"trend":{"current_count":45,"previous_count":30,"change_percent":50.0,"direction":"up"}}]}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v1/admin/dashboard/top-user-risk":{"get":{"summary":"Top users by risk match count","description":"Returns a paginated list of users ranked by matched log count descending. Each record shows the matched users and their similarity scores for the given risk type. Bidirectional duplicates are deduplicated — only the canonical side is returned.\n","tags":["Admin / User Risk"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"type","in":"query","description":"Filter by risk type","required":false,"schema":{"$ref":"#/components/schemas/RiskType"}},{"name":"event","in":"query","description":"Filter by the event that triggered the risk score","required":false,"schema":{"$ref":"#/components/schemas/RiskEvent"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2025-01-31"}},{"name":"per_page","in":"query","description":"Results per page (1–100, default 15)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":15}}],"responses":{"200":{"description":"Paginated top-risk user list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TopUserRiskRecord"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"id":"01JCHG2M8S2ABCDE0987654321","name":"John Doe","type":2,"type_label":"Login IP","matched_count":12,"matched_users":[{"id":"01JCHG2M8S2ABCDE1111111111","name":"Jane Doe","username":"jane_doe","similarity_score":0.95,"event":1,"event_label":"Login"}]}],"meta":{"pagination":{"total":22,"per_page":200,"current_page":1,"last_page":1,"from":1,"to":22,"has_more":false}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v1/admin/dashboard/user-risk-breakdown":{"get":{"summary":"Risk breakdown by shared attribute value","description":"Groups flagged users by the shared risk attribute (e.g. IP, device hash, account number) for a required risk type. Returns one row per unique shared value with the users involved. The value is masked for the Password type (first 2 chars + ***).\n","tags":["Admin / User Risk"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"type","in":"query","description":"Risk type to break down (required)","required":true,"schema":{"$ref":"#/components/schemas/RiskType"}},{"name":"event","in":"query","description":"Filter by the event that triggered the risk score","required":false,"schema":{"$ref":"#/components/schemas/RiskEvent"}},{"name":"min_score","in":"query","description":"Minimum similarity score threshold (0–1)","required":false,"schema":{"type":"number","format":"float","minimum":0,"maximum":1,"example":0.8}},{"name":"per_page","in":"query","description":"Results per page (1–100, default 15)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":15}}],"responses":{"200":{"description":"Paginated risk breakdown list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UserRiskBreakdownRecord"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"value":"192.168.1.1","user_count":3,"id":"01JCHG2M8S2ABCDE0987654321","name":"John Doe","event":1,"event_label":"Login","similarity_score":0.95,"matched_user":[{"id":"01JCHG2M8S2ABCDE1111111111","name":"Jane Doe","event":1,"event_label":"Login","similarity_score":0.93}]}],"meta":{"pagination":{"total":22,"per_page":200,"current_page":1,"last_page":1,"from":1,"to":22,"has_more":false}}}}}},"422":{"description":"Validation error (type is required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v1/admin/users/{userId}/risks":{"get":{"summary":"Get risk profile for a specific user","description":"Returns all active risk entries for the given user, grouped by risk type. Each entry includes the count of distinct matched users and the individual match log records for the current risk run.\n","tags":["Admin / User Risk"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"userId","in":"path","description":"ULID of the target user","required":true,"schema":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"}},{"name":"type","in":"query","description":"Filter to a single risk type","required":false,"schema":{"$ref":"#/components/schemas/RiskType"}},{"name":"event","in":"query","description":"Filter logs by the triggering event","required":false,"schema":{"$ref":"#/components/schemas/RiskEvent"}},{"name":"matched_user","in":"query","description":"Search matched users by name or username (partial, case-insensitive)","required":false,"schema":{"type":"string","maxLength":255,"example":"john"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2025-01-31"}},{"name":"per_page","in":"query","description":"Results per page (1–100, default 15)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":15}}],"responses":{"200":{"description":"User risk profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UserRiskEntry"}}}},"example":{"data":[{"type":2,"type_label":"Login IP","current_run_id":"01JCHG2M8S2ABCDE9999999999","matched_user_count":2,"matched_users":[{"matched_user_id":"01JCHG2M8S2ABCDE1111111111","matched_user_name":"Jane Doe","matched_user_username":"jane_doe","similarity_score":0.95,"event":1,"event_label":"Login"}]}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/admin/users/{userId}/risks/summary":{"get":{"summary":"Get risk summary for a specific user","description":"Returns an aggregated risk summary for the given user across all risk types, including how many distinct matched users were found per type.\n","tags":["Admin / User Risk"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"userId","in":"path","description":"ULID of the target user","required":true,"schema":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"}}],"responses":{"200":{"description":"User risk summary","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserRiskUserSummary"}}},"example":{"data":{"summary":{"total_risk_types":2,"total_matched_users":5},"risks":[{"type":2,"type_label":"Login IP","matched_user_count":3},{"type":4,"type_label":"Device","matched_user_count":2}]}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/admin/dashboard/user-risk-records":{"get":{"summary":"List raw risk log records","description":"Returns a paginated list of individual risk log entries for a required risk type. Each row represents a single matched-user pairing from the most recent risk run. The shared attribute value is masked for the Password type (first 2 chars + ***).\n","tags":["Admin / User Risk"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"type","in":"query","description":"Risk type to filter by (required)","required":true,"schema":{"$ref":"#/components/schemas/RiskType"}},{"name":"value","in":"query","description":"Filter by the shared attribute value (exact match; prefix match for Password type)","required":false,"schema":{"type":"string","maxLength":255,"example":"192.168.1.1"}},{"name":"event","in":"query","description":"Filter by the event that triggered the log entry","required":false,"schema":{"$ref":"#/components/schemas/RiskEvent"}},{"name":"min_score","in":"query","description":"Minimum similarity score threshold (0–1)","required":false,"schema":{"type":"number","format":"float","minimum":0,"maximum":1,"example":0.8}},{"name":"per_page","in":"query","description":"Results per page (1–100, default 10)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}],"responses":{"200":{"description":"Paginated risk log records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UserRiskLogRecord"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"id":"01JCHG2M8S2ABCDE1234567890","value":"192.168.1.1","user_id":"01JCHG2M8S2ABCDE0987654321","user_name":"John Doe","user_username":"john_doe","event":1,"event_label":"Login","similarity_score":0.95,"created_at":"2025-01-15T10:30:00Z"}],"meta":{"pagination":{"total":22,"per_page":200,"current_page":1,"last_page":1,"from":1,"to":22,"has_more":false}}}}}},"422":{"description":"Validation error (type is required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v1/admin/custom-hot-games":{"get":{"tags":["Admin / Custom Hot Games"],"summary":"List Custom Hot Games","parameters":[{"name":"status","in":"query","description":"Filter by status (true / false)","required":false,"schema":{"type":"boolean"}},{"name":"provider_id","in":"query","description":"Filter by provider","required":false,"schema":{"type":"integer"}},{"name":"category_id","in":"query","description":"Filter by category","required":false,"schema":{"type":"integer"}},{"name":"start_date","in":"query","description":"Filter by created_at (>=), format YYYY-MM-DD","required":false,"schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"Filter by created_at (<=), format YYYY-MM-DD","required":false,"schema":{"type":"string","format":"date"}},{"name":"per_page","in":"query","description":"Results per page (default 10)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}],"responses":{"200":{"description":"Paginated list","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomHotGameResource"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}]}}}}}},"post":{"tags":["Admin / Custom Hot Games"],"summary":"Create Custom Hot Games","description":"Bulk create or update custom hot games.\nIf the record exists, it will be updated.\nIf the record does not exist, it will be created.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"items":{"type":"object","required":["id","service_id","sort_order"],"properties":{"id":{"type":"string","format":"uuid","description":"Existing Custom Hot Game ID. Omit or provide a new ULID/UUID for new records depending on implementation.","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"service_id":{"type":"integer","minimum":1,"example":498},"rtp":{"type":"integer","minimum":1,"maximum":100,"example":58},"sort_order":{"type":"integer","minimum":1,"example":3}}}}}},"example":{"items":[{"id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","service_id":498,"sort_order":3,"rtp":59},{"id":"019e8c65-1fcf-7367-b432-9c096c9982a5","service_id":499,"sort_order":10,"rtp":89},{"id":"019e8c65-1fd7-71dd-8771-83dce5e25457","service_id":497,"sort_order":4,"rtp":60}]}}}},"responses":{"200":{"description":"Custom hot games successfully created or updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","nullable":true,"example":null},"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomHotGameResource"}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Admin / Custom Hot Games"],"summary":"Bulk Update Custom Hot Games","description":"Update multiple custom hot games in a single request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"service_id":{"type":"integer","minimum":1,"description":"Must be unique among custom hot games.","example":498},"status":{"type":"boolean","example":true},"sort_order":{"type":"integer","nullable":true,"example":3}}}}}},"example":{"items":[{"id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","service_id":498,"status":true,"sort_order":3},{"id":"019e8c65-1fcf-7367-b432-9c096c9982a5","service_id":499,"status":true,"sort_order":10}]}}}},"responses":{"200":{"description":"Custom hot games updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","nullable":true,"example":null},"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomHotGameResource"}}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/admin/custom-hot-games/reorder":{"post":{"tags":["Admin / Custom Hot Games"],"summary":"Reorder Custom Hot Games","description":"Pass an ordered array of IDs. Missing IDs are appended automatically after the provided ones.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ordered_ids"],"properties":{"ordered_ids":{"type":"array","minItems":1,"items":{"type":"string","format":"uuid","description":"Must be distinct"}}}}}}},"responses":{"200":{"description":"Full reordered list of custom hot games.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomHotGameResource"}}}}}}},"422":{"description":"Validation error (e.g. unknown ID in ordered_ids)."}}}},"/v1/admin/custom-hot-games/{id}":{"get":{"tags":["Admin / Custom Hot Games"],"summary":"Get a Custom Hot Game","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomHotGameResource"}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Admin / Custom Hot Games"],"summary":"Update a Custom Hot Game","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"service_id":{"type":"integer","minimum":1,"example":42},"status":{"type":"boolean","nullable":true,"example":true},"sort_order":{"type":"integer","nullable":true,"example":3},"rtp":{"type":"number","format":"float","minimum":0,"maximum":100,"nullable":true,"example":96.5}}}}}},"responses":{"200":{"description":"Custom hot game updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"service_id":{"type":"integer"},"status":{"type":"boolean"},"sort_order":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"service":{"type":"object","nullable":true,"description":"Enriched service data from the game service","properties":{"id":{"type":"integer"},"name":{"type":"object"},"rtp":{"type":"string","nullable":true,"example":"96.5"},"serviceTag":{"type":"integer","nullable":true},"status":{"type":"boolean"}}}}}}}}}}},"404":{"description":"Custom hot game not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["Admin / Custom Hot Games"],"summary":"Delete a Custom Hot Game","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"message":{"type":"string","example":"Custom hot game deleted."},"data":{"nullable":true}}}]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/admin/categories/unified-order":{"get":{"tags":["Admin / Categories"],"summary":"List unified category order","description":"Returns all active service categories and active custom categories merged into a single list. Items with an explicit sort order in the unified_category_orders table appear first (ascending). Unordered items follow: all service categories before all custom categories, then by id.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Merged and sorted category list","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UnifiedCategoryItem"}}}}]},"example":{"status":true,"message":null,"data":[{"type":"service_category","id":1,"name":"Slots","sort_order":1,"icon_url":"https://example.com/slots.png"},{"type":"custom_category","id":"01JCHG2M8S2ABCDE1234567890","name":"Hot Games","sort_order":2,"icon_url":"https://example.com/hot.png"},{"type":"service_category","id":3,"name":"Live Casino","sort_order":0,"icon_url":null}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Failed to fetch service categories from game service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Admin / Categories"],"summary":"Reorder unified categories","description":"Saves the display order for the unified category list. Pass a complete ordered array of items; the position is derived from the array index (1-based). Items not included in the list are appended after the submitted ones in their existing relative order.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"items":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["service_category","custom_category"],"example":"service_category"},"id":{"type":"integer","minimum":1,"example":1}}}}}},"example":{"items":[{"type":"service_category","id":2},{"type":"custom_category","id":5},{"type":"service_category","id":1}]}}}},"responses":{"200":{"description":"Order saved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"}]},"example":{"status":true,"message":"Order saved.","data":null}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/admin/seo":{"get":{"tags":["Admin / Seo"],"summary":"Get all Seo","parameters":[{"in":"query","name":"per_page","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":200}},{"in":"query","name":"all","required":false,"schema":{"type":"boolean","default":false},"description":"Return all rows without pagination"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SeoPage"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"example":{"data":[{"key":"home","title":"Welcome to 0Wallet","description":"The best digital wallet.","og_title":null,"og_description":null,"og_image":null,"og_image_alt":null,"canonical":null,"keywords":"wallet, deposit, withdraw","robots_index":true,"robots_follow":true,"icon_url":"https://pub-xxx.r2.dev/tenant_abc/seo/01J.png","updated_at":"2026-05-28T08:00:00Z"}],"meta":{"pagination":{"total":22,"per_page":200,"current_page":1,"last_page":1,"from":1,"to":22,"has_more":false}}}}}}}}},"/v1/admin/seo/{key}":{"put":{"tags":["Admin / Seo"],"summary":"Update specific SEO page (upsert)","parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]+$"},"example":"home"}],"requestBody":{"required":false,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":300,"nullable":true,"example":"Welcome to 0Wallet"},"description":{"type":"string","maxLength":1000,"nullable":true,"example":"The best digital wallet."},"og_title":{"type":"string","maxLength":300,"nullable":true},"og_description":{"type":"string","maxLength":1000,"nullable":true},"og_image":{"type":"string","maxLength":1000,"nullable":true,"description":"URL to the OG image"},"og_image_alt":{"type":"string","maxLength":300,"nullable":true},"canonical":{"type":"string","maxLength":1000,"nullable":true},"keywords":{"type":"string","maxLength":1000,"nullable":true,"example":"wallet, deposit, withdraw"},"robots_index":{"type":"boolean","nullable":true,"example":true},"robots_follow":{"type":"boolean","nullable":true,"example":true},"icon":{"type":"string","format":"binary","nullable":true,"description":"Favicon/icon file. Accepted: jpg, jpeg, png, webp, gif, svg, ico. Max 5MB."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SeoPage"}}},"example":{"data":{"key":"home","title":"Welcome to 0Wallet","description":"The best digital wallet.","og_title":null,"og_description":null,"og_image":null,"og_image_alt":null,"canonical":null,"keywords":"wallet, deposit, withdraw","robots_index":true,"robots_follow":true,"icon_url":"https://pub-xxx.r2.dev/tenant_abc/seo/01J.png","updated_at":"2026-05-28T08:00:00Z"}}}}},"404":{"description":"SEO page not found","content":{"application/json":{"example":{"message":"SEO page not found."}}}}}},"get":{"tags":["Admin / Seo"],"summary":"Get specific SEO page","parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]+$"},"example":"home"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SeoPage"}}},"example":{"data":{"key":"home","title":"Welcome to 0Wallet","description":"The best digital wallet.","og_title":null,"og_description":null,"og_image":null,"og_image_alt":null,"canonical":null,"keywords":"wallet, deposit, withdraw","robots_index":true,"robots_follow":true,"icon_url":"https://pub-xxx.r2.dev/tenant_abc/seo/01J.png","updated_at":"2026-05-28T08:00:00Z"}}}}},"404":{"description":"SEO page not found","content":{"application/json":{"example":{"message":"SEO page not found."}}}}}},"delete":{"tags":["Admin / Seo"],"summary":"Delete specific Seo","parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]+$"},"example":"home"}],"responses":{"200":{"description":"SEO page deleted","content":{"application/json":{"example":{"data":null,"message":"SEO page deleted."}}}},"404":{"description":"SEO page not found","content":{"application/json":{"example":{"message":"SEO page not found."}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v1/user/seo":{"get":{"tags":["User / Seo"],"summary":"Get all SEO pages keyed by route","description":"Unauthenticated endpoint. Returns all SEO rows as an object keyed by route key (e.g. `home`, `deposit`). No pagination — frontend SSR fetches this once and caches it in a Pinia store.\n","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SeoPage"}}}},"example":{"data":{"home":{"key":"home","title":"Welcome to 0Wallet","description":"The best digital wallet.","og_title":null,"og_description":null,"og_image":null,"og_image_alt":null,"canonical":null,"keywords":"wallet, deposit, withdraw","robots_index":true,"robots_follow":true,"icon_url":"https://pub-xxx.r2.dev/tenant_abc/seo/01J.png","updated_at":"2026-05-28T08:00:00Z"},"deposit":{"key":"deposit","title":"Deposit Funds","description":"Top up your wallet easily.","og_title":null,"og_description":null,"og_image":null,"og_image_alt":null,"canonical":null,"keywords":null,"robots_index":true,"robots_follow":true,"icon_url":null,"updated_at":"2026-05-28T08:00:00Z"}}}}}}}}},"/v1/user/seo/{key}":{"get":{"tags":["User / Seo"],"summary":"Get specific SEO page by route key","description":"Unauthenticated endpoint. Returns 404 if the key has not been seeded.","parameters":[{"in":"path","name":"key","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._-]+$"},"example":"home"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SeoPage"}}},"example":{"data":{"key":"home","title":"Welcome to 0Wallet","description":"The best digital wallet.","og_title":null,"og_description":null,"og_image":null,"og_image_alt":null,"canonical":null,"keywords":"wallet, deposit, withdraw","robots_index":true,"robots_follow":true,"icon_url":"https://pub-xxx.r2.dev/tenant_abc/seo/01J.png","updated_at":"2026-05-28T08:00:00Z"}}}}},"404":{"description":"SEO page not found","content":{"application/json":{"example":{"status":false,"message":"SEO page not found.","code":"NOT_FOUND"}}}}}}},"/v1/admin/external/operators":{"get":{"tags":["Admin / External Operators"],"summary":"List external operators","description":"Returns a paginated list of external operators for the current tenant, ordered by name. Supports filtering by name search and active status. Each record includes a `has_token` flag.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"search","in":"query","description":"Partial, case-insensitive match on operator name","required":false,"schema":{"type":"string","example":"acme"}},{"name":"is_active","in":"query","description":"Filter by active status","required":false,"schema":{"type":"boolean","example":true}},{"name":"per_page","in":"query","description":"Results per page (1–100, default 15)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":15}}],"responses":{"200":{"description":"Paginated list of external operators","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExternalOperator"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}},"post":{"tags":["Admin / External Operators"],"summary":"Create an external operator","description":"Creates a new external operator. Uses `multipart/form-data` because the operator's own `icon_url` and each metadata (mini-game) entry's `image_url` may carry an uploaded file. Uploaded images are stored in R2 and persisted as object keys.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":255,"example":"Acme Games"},"icon_url":{"oneOf":[{"type":"string","format":"binary","description":"Uploaded icon/logo file (jpg, jpeg, png, webp, gif, svg; max 5MB)."},{"type":"string","description":"Existing R2 object key or absolute URL to keep the current icon."}],"nullable":true},"is_active":{"type":"boolean","example":true},"allowed_ips":{"type":"array","description":"Whitelist of IPs allowed to call the operator API","items":{"type":"string","format":"ipv4","example":"203.0.113.10"}},"metadata":{"type":"array","description":"Mini-game entries exposed under this operator","items":{"$ref":"#/components/schemas/ExternalOperatorMetadataInput"}}}}}}},"responses":{"201":{"description":"Operator created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ExternalOperator"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/admin/external/operators/{id}":{"get":{"tags":["Admin / External Operators"],"summary":"Get an external operator","description":"Returns a single operator with its token and webhook endpoints loaded.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"}}],"responses":{"200":{"description":"Operator detail","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ExternalOperator"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"description":"Operator not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Admin / External Operators"],"summary":"Update an external operator","description":"Updates an operator. Uses `multipart/form-data` so the operator's own `icon_url` and metadata entries may carry uploaded `image_url` files. Images that are replaced or removed and are no longer referenced are deleted from R2.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"example":"Acme Games"},"icon_url":{"oneOf":[{"type":"string","format":"binary","description":"Uploaded icon/logo file (jpg, jpeg, png, webp, gif, svg; max 5MB)."},{"type":"string","description":"Existing R2 object key or absolute URL to keep the current icon."}],"nullable":true},"is_active":{"type":"boolean","example":true},"allowed_ips":{"type":"array","items":{"type":"string","format":"ipv4","example":"203.0.113.10"}},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/ExternalOperatorMetadataInput"}}}}}}},"responses":{"200":{"description":"Operator updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ExternalOperator"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"description":"Operator not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Admin / External Operators"],"summary":"Delete an external operator","description":"Deletes the operator, its tokens, and discards its stored images.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"message":{"type":"string","example":"Deleted"},"data":{"nullable":true}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"description":"Operator not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/admin/external/operators/{id}/tokens":{"post":{"tags":["Admin / External Operators"],"summary":"Issue an API token","description":"Issues a Sanctum API token for the operator. Each operator holds a single token — any existing token is revoked first. The plain-text token is returned only once in this response.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"}}],"responses":{"201":{"description":"Token issued","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssuedToken"}}}]},"example":{"status":true,"message":null,"data":{"token_id":"01JCHG2M8S2ABCDE1234567890","token_name":"Acme Games","plain_text_token":"1|abcDEF123456ghiJKL789..."}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"description":"Operator not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/admin/external/operators/{id}/tokens/{tid}":{"post":{"tags":["Admin / External Operators"],"summary":"Revoke API token(s)","description":"Revokes all tokens for the operator.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"}},{"name":"tid","in":"path","required":true,"description":"Token ID (path placeholder; all operator tokens are revoked)","schema":{"type":"string","example":"01JCHG2M8S2ABCDE1234567890"}}],"responses":{"200":{"description":"Token revoked","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"message":{"type":"string","example":"Token revoked"},"data":{"nullable":true}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"description":"Operator not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/admin/external/logs":{"get":{"tags":["Admin / External Operators"],"summary":"List external operator API logs","description":"Returns a paginated list of inbound/outbound external operator API logs for the current tenant. Heavy fields (`request`, `response`, `meta_options`) are omitted from the list response.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"operator_id","in":"query","description":"Filter by operator ID","required":false,"schema":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"}},{"name":"direction","in":"query","description":"Filter by traffic direction","required":false,"schema":{"type":"string","enum":["in","out"]}},{"name":"method","in":"query","description":"Filter by HTTP method (case-insensitive)","required":false,"schema":{"type":"string","maxLength":20,"example":"POST"}},{"name":"module","in":"query","description":"Partial, case-insensitive match on module","required":false,"schema":{"type":"string","maxLength":255,"example":"balance"}},{"name":"date_from","in":"query","description":"Filter logs created on or after this date (ISO 8601)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-01"}},{"name":"date_to","in":"query","description":"Filter logs created on or before this date (ISO 8601)","required":false,"schema":{"type":"string","format":"date","example":"2025-01-31"}},{"name":"sort_by","in":"query","description":"Sort field: created_at, method, status_code, direction","required":false,"schema":{"type":"string","example":"created_at"}},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Results per page (1–100, default 20)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Paginated list of external API logs","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExternalApiLogListItem"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v1/admin/withdrawal-approval-levels":{"get":{"tags":["Admin / Withdrawal Approval Levels"],"summary":"List withdrawal approval levels","description":"Returns all withdrawal approval levels ordered by `sort_order`.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of withdrawal approval levels","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WithdrawalApprovalLevel"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Admin / Withdrawal Approval Levels"],"summary":"Create a withdrawal approval level","description":"Creates a new withdrawal approval level. The `permission` column is never admin-supplied — it's derived from `name` as `withdrawal.{name}` and a matching Permission row is created (or updated) automatically.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawalApprovalLevelCreateInput"},"example":{"name":"settlement","label":"Settlement","sort_order":4,"is_active":true,"auto_approve":false,"final_override":false}}}},"responses":{"201":{"description":"Withdrawal approval level created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WithdrawalApprovalLevel"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error (e.g. `name` or `sort_order` already taken)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/admin/withdrawal-approval-levels/{id}":{"put":{"tags":["Admin / Withdrawal Approval Levels"],"summary":"Update a withdrawal approval level","description":"Partially updates a withdrawal approval level. Renaming `name` renames the existing Permission row in place (rather than creating a new one) so existing role assignments survive.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"UUID of the withdrawal approval level","schema":{"type":"string","format":"uuid","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawalApprovalLevelUpdateInput"},"example":{"label":"Settlement (Final)","final_override":true}}}},"responses":{"200":{"description":"Withdrawal approval level updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WithdrawalApprovalLevel"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Withdrawal approval level not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error (e.g. `name` or `sort_order` already taken)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/user/mini-games":{"get":{"tags":["User / Mini Games"],"summary":"List active mini-games","description":"Public endpoint. Returns active external operators, grouped by operator, with their enabled mini-game entries. If a valid user bearer token is supplied, the `{player_id}` placeholder in redirect URLs is substituted with the authenticated user's ID. Only metadata entries with `status: true` are returned, a redirect URL is omitted when not configured, and operators with no enabled entries are omitted from the response.\n","parameters":[{"name":"code","in":"query","description":"Filter to a single external operator by its `code` (exact match, trimmed). Returns only that operator's group (still subject to the same active-entry filtering), or an empty list if the code does not match any active operator.\n","required":false,"schema":{"type":"string","example":"ls_mini_game"}}],"responses":{"200":{"description":"List of mini-games, grouped by operator","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MiniGame"}}}}]},"example":{"status":true,"message":null,"data":[{"operator_id":"01JCHG2M8S2ABCDE0987654321","operator_name":"LS Mini Game","operator_icon_url":"https://pub-xxx.r2.dev/tenant_abc/external-operators/01J-icon.png","games":[{"name":"Lucky Spin","code":"lucky_spin","image_url":"https://pub-xxx.r2.dev/tenant_abc/external-operators/01J.png","redirect_url_web":"https://games.example.com/spin?player=01JCHG2M8S2ABCDE0987654321","status":true}]}]}}}}}}},"/v1/service/list/{providerId}/{providerCategorySlug}/{serviceCategorySlug}":{"get":{"tags":["User / Game Catalog"],"summary":"List services by provider + slugs (game list)","description":"Public endpoint. Returns the active service list for a provider category, resolved via `provider_id` plus the slug pair (`provider_categories.slug` and `service_categories.slug`) instead of query-string filters — used for the \"game list\" drill-down UI reached from a `game_list` tile in `/v1/service/categories`. Only `status: true` services are returned (no `include_inactive` cascade opt-out on this route). If a valid user bearer token is supplied, `is_favourite` is computed per-service and, unless overridden by the `is_favourite` query param, favourited services are sorted first (newest favourite first); guests receive no special sort.\n","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"providerId","in":"path","required":true,"description":"Provider ID (`providers.id`)","schema":{"type":"integer","example":3}},{"name":"providerCategorySlug","in":"path","required":true,"description":"Slug of the provider category (`provider_categories.slug`)","schema":{"type":"string","example":"mega888-slot"}},{"name":"serviceCategorySlug","in":"path","required":true,"description":"Slug of the service category (`service_categories.slug`)","schema":{"type":"string","example":"slot"}},{"name":"is_favourite","in":"query","description":"Override the default favourite-first sort. When omitted, defaults to `true` for authenticated users and `false` for guests.\n","required":false,"schema":{"type":"boolean","example":true}}],"responses":{"200":{"description":"Service list for the resolved provider category","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer","example":2},"services":{"type":"array","items":{"$ref":"#/components/schemas/GameServiceItem"}}}}}}]},"example":{"status":true,"message":null,"data":{"total":2,"services":[{"id":10245,"provider_id":3,"provider_name":"Mega888","name":{"en":"Fortune Tiger","ms":"Harimau Bertuah"},"service_code":"fortune_tiger","category_id":2,"category_name":"Slot","rtp":"96.50","icon_url":"https://pub-xxx.r2.dev/tenant_abc/services/fortune-tiger.png","status":true,"service_tag":1,"maintenance":false,"provider_category_id":55,"provider_category_name":"Mega888 Slot","wallet_type":1,"sort_order":1,"icon_badge_url":"","is_favourite":true},{"id":10246,"provider_id":3,"provider_name":"Mega888","name":{"en":"Golden Dragon","ms":"Naga Emas"},"service_code":"golden_dragon","category_id":2,"category_name":"Slot","rtp":"95.80","icon_url":"https://pub-xxx.r2.dev/tenant_abc/services/golden-dragon.png","status":true,"service_tag":0,"maintenance":false,"provider_category_id":55,"provider_category_name":"Mega888 Slot","wallet_type":1,"sort_order":2,"icon_badge_url":"","is_favourite":false}]}}}}},"400":{"description":"Failed to fetch services (e.g. provider/slug combination not found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"status":"false","message":"Failed to fetch services","code":null}}}}}}},"/v1/service/categories":{"get":{"tags":["User / Game Catalog"],"summary":"List game categories (unified custom + default)","description":"Public endpoint. Returns the tenant's category shelves for the game home/lobby screen: admin-curated custom categories (including the system `recent` and `favourite` shelves) merged with the catalog's default `service_category` shelves, ordered per `UnifiedCategoryOrder` when configured (custom categories first, defaults appended, otherwise). Each category's `items` are polymorphic tiles — see `GameCategoryItem` — pre-resolved to either a directly-launchable `service` tile (`action: launch`) or a drill-down `provider_category` / `service_category` tile (`action: game_list`). Empty `recent` / `favourite` shelves are omitted entirely. If a valid user bearer token is supplied, the `recent` shelf is populated from play history, the `favourite` shelf from the user's favourites, and every service tile's `is_favourite` is computed; guests see neither system shelf and `is_favourite` is always `false`.\n","security":[{"bearerAuth":[]},{}],"responses":{"200":{"description":"Ordered list of category shelves","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiSuccess"},{"type":"object","properties":{"data":{"type":"object","properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/GameCategory"}}}}}}]},"example":{"status":true,"message":null,"data":{"categories":[{"id":"01JCHG2M8S2ABCDE1111111111","name":"Recent","slug":"recent","type":"recent","icon_url":"https://pub-xxx.r2.dev/tenant_abc/categories/recent.png","active_icon_url":"https://pub-xxx.r2.dev/tenant_abc/categories/recent-active.png","sort_order":1,"is_custom":true,"items":[{"type":"service","id":10245,"name":"Fortune Tiger","icon_url":"https://pub-xxx.r2.dev/tenant_abc/services/fortune-tiger.png","icon_badge_url":"","provider_category_id":55,"wallet_type":1,"provider_id":3,"sort_order":0,"action":"launch","is_favourite":true}]},{"id":2,"name":"Slot","slug":"slot","status":true,"icon_url":"https://pub-xxx.r2.dev/tenant_abc/categories/slot.png","active_icon_url":"https://pub-xxx.r2.dev/tenant_abc/categories/slot-active.png","sort_order":2,"items":[{"type":"provider_category","id":55,"name":"Mega888 Slot","icon_url":"https://pub-xxx.r2.dev/tenant_abc/provider-categories/mega888-slot.png","wallet_type":1,"provider_id":3,"provider_category_id":55,"service_category_id":2,"provider_category_slug":"mega888-slot","sort_order":1,"action":"game_list"}]}]}}}}}}}},"/v1/user/vip":{"get":{"tags":["User / Vip"],"summary":"Get current VIP status and progress","description":"Returns the authenticated user's current VIP level, the next level to reach, the full active level ladder, progress toward the next level's upgrade requirements, and the user's VIP rewards. If the user has no VIP record yet, one is created on the fly (unassigned / Regular floor). `sort_order = 0` is reserved for the Regular floor level and is excluded from `all_levels`; \"next level\" always means the first tier above Regular. `rewards` is the same list returned by `/v1/user/vip/rewards`.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"lang","in":"query","description":"Locale for level privileges and T&Cs. Defaults to `en`.","required":false,"schema":{"$ref":"#/components/schemas/LanguageCode"}}],"responses":{"200":{"description":"VIP status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"current_level":{"$ref":"#/components/schemas/VipLevel"},"next_level":{"allOf":[{"$ref":"#/components/schemas/VipLevel"}],"nullable":true,"description":"Null when the user is already at the highest active level."},"all_levels":{"type":"array","items":{"$ref":"#/components/schemas/VipLevel"}},"progress":{"type":"array","nullable":true,"description":"Null when `next_level` is null.","items":{"$ref":"#/components/schemas/VipLevelProgressItem"}},"level_reached_at":{"type":"string","format":"date-time","nullable":true},"last_evaluated_at":{"type":"string","format":"date-time","nullable":true},"rewards":{"type":"array","items":{"$ref":"#/components/schemas/UserVipLevelReward"}}}}}},"example":{"data":{"current_level":{"id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","name":"Silver","image_path":"https://pub-xxx.r2.dev/tenant_abc/vip/silver-badge.png","sort_order":1,"upgrade_match_mode":"Match ALL requirements","maintain_match_mode":"Match ALL requirements","is_active":true,"privileges":[{"id":"019e8c65-1fcf-7367-b432-9c096c9982a5","vip_level_id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","locale":"en","title":"Priority Support","description":"<p>Access to dedicated support line.</p>","sort_order":1,"is_active":true}],"tncs":[{"id":"019e8c65-1fd7-71dd-8771-83dce5e25457","vip_level_id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","locale":"en","terms_conditions":"<p>Terms apply to Silver tier rewards.</p>"}],"rewards":[{"id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","vip_level_id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","name":"Silver Upgrade Bonus","reward_type":"Bonus","amount":"50.00","unlock_match_mode":"Match ALL requirements","unlock_trigger":"Claimable immediately on level upgrade","withdrawal_match_mode":"Match ALL requirements","is_active":true,"sort_order":1}]},"next_level":{"id":"019e8c65-2011-70a1-9c1a-1c2d3e4f5a6b","name":"Gold","image_path":"https://pub-xxx.r2.dev/tenant_abc/vip/gold-badge.png","sort_order":2,"upgrade_match_mode":"Match ALL requirements","maintain_match_mode":"Match ALL requirements","is_active":true,"privileges":[],"tncs":[],"rewards":[]},"all_levels":[],"progress":[{"condition_key":"total_deposit_amount","condition_name":"Total Deposit Amount","value_type":2,"current_value":1500.0,"threshold":5000.0,"completed":false}],"level_reached_at":"2026-06-01T08:00:00Z","last_evaluated_at":"2026-07-21T02:00:00Z","rewards":[{"id":"019e8c65-2100-71ea-934b-9703ef41cd5e","user_id":"01JCHG2M8S2ABCDE0987654321","vip_level_reward_id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","user_vip_level_log_id":"019e8c65-1fc2-71ea-934b-9703ef41cd60","status":"Claimable","granted_amount":"50.00","metadata":null,"granted_at":"2026-07-01T08:00:00Z","unlocked_at":"2026-07-01T08:00:00Z","claimed_at":null,"reward":{"id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","vip_level_id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","name":"Silver Upgrade Bonus","reward_type":"Bonus","amount":"50.00","unlock_match_mode":"Match ALL requirements","unlock_trigger":"Claimable immediately on level upgrade","withdrawal_match_mode":"Match ALL requirements","is_active":true,"sort_order":1},"can_claim":true,"progress":[{"condition_key":"total_turnover","condition_name":"Total Turnover","current_value":200.0,"target_value":500.0,"completed":false}]}]}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"422":{"description":"Validation error (invalid `lang`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/user/vip/rewards/{id}/claim":{"post":{"tags":["User / Vip"],"summary":"Claim a VIP reward","description":"Claims a claimable VIP reward for the authenticated user. If the reward has a non-zero amount, it is credited to the user's main wallet as a bonus transaction. Only rewards in the `Claimable` status can be claimed.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"UUID of the `UserVipLevelReward` record","schema":{"type":"string","format":"uuid","example":"019e8c65-2100-71ea-934b-9703ef41cd5e"}}],"responses":{"200":{"description":"Reward claimed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","example":"Reward claimed successfully."},"data":{"$ref":"#/components/schemas/UserVipLevelReward"}}},"example":{"status":true,"message":"Reward claimed successfully.","data":{"id":"019e8c65-2100-71ea-934b-9703ef41cd5e","user_id":"01JCHG2M8S2ABCDE0987654321","vip_level_reward_id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","user_vip_level_log_id":"019e8c65-1fc2-71ea-934b-9703ef41cd60","status":"Claimed","granted_amount":"50.00","metadata":null,"granted_at":"2026-07-01T08:00:00Z","unlocked_at":"2026-07-01T08:00:00Z","claimed_at":"2026-07-22T09:00:00Z","reward":{"id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","vip_level_id":"019e8c65-1fc2-71ea-934b-9703ef41cd5e","name":"Silver Upgrade Bonus","reward_type":"Bonus","amount":"50.00","unlock_match_mode":"Match ALL requirements","unlock_trigger":"Claimable immediately on level upgrade","withdrawal_match_mode":"Match ALL requirements","is_active":true,"sort_order":1}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"description":"Reward not found (does not exist or does not belong to the user)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"status":"false","message":"Reward not found.","error_code":null}}}},"422":{"description":"Reward is not in a claimable state (e.g. already claimed, still locked, or voided)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"status":"false","message":"Reward is not claimable.","error_code":null}}}}}}}},"components":{"schemas":{"ApiSuccess":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","nullable":true,"example":null}}},"GameServiceItem":{"type":"object","description":"A single service (game) row from the catalog, as returned by the game list endpoints.","properties":{"id":{"type":"integer","example":10245},"provider_id":{"type":"integer","example":3},"provider_name":{"type":"string","example":"Mega888"},"name":{"type":"object","description":"Localized service name, keyed by locale code.","additionalProperties":{"type":"string"},"example":{"en":"Fortune Tiger","ms":"Harimau Bertuah"}},"service_code":{"type":"string","example":"fortune_tiger"},"category_id":{"type":"integer","example":2},"category_name":{"type":"string","example":"Slot"},"rtp":{"type":"string","nullable":true,"description":"Return-to-player percentage as a decimal string; absent when not configured.","example":"96.50"},"icon_url":{"type":"string","example":"https://pub-xxx.r2.dev/tenant_abc/services/fortune-tiger.png"},"status":{"type":"boolean","example":true},"service_tag":{"type":"integer","nullable":true,"description":"0=none, 1=hot, 2=new","example":1},"maintenance":{"type":"boolean","example":false},"provider_category_id":{"type":"integer","nullable":true,"example":55},"provider_category_name":{"type":"string","example":"Mega888 Slot"},"wallet_type":{"type":"integer","description":"1=seamless, 2=transfer, 3=app — inherited from the parent provider","example":1},"sort_order":{"type":"integer","example":1},"icon_badge_url":{"type":"string","example":""},"is_favourite":{"type":"boolean","description":"Whether the authenticated user has favourited this service. Always `false` for guests.","example":true}}},"GameCategoryItem":{"type":"object","description":"A polymorphic tile within a `GameCategory.items` list. `type` and `action` determine which of the remaining fields are meaningful — `action: launch` tiles carry a `service` id ready for `POST /v1/user/service/launch`; `action: game_list` tiles carry a `provider_category` or `service_category` id to drill into via `/v1/service/list/{providerId}/{providerCategorySlug}/{serviceCategorySlug}`.\n","properties":{"type":{"type":"string","enum":["service","provider_category","service_category"],"example":"service"},"id":{"type":"integer","description":"ID of the entity named by `type`.","example":10245},"name":{"type":"string","example":"Fortune Tiger"},"icon_url":{"type":"string","example":"https://pub-xxx.r2.dev/tenant_abc/services/fortune-tiger.png"},"icon_badge_url":{"type":"string","description":"Only present on `type: service` tiles.","example":""},"provider_category_id":{"type":"integer","nullable":true,"example":55},"service_category_id":{"type":"integer","nullable":true,"description":"Only present on default (non-custom) category tiles.","example":2},"provider_category_slug":{"type":"string","nullable":true,"description":"Only present on default `game_list` tiles; pairs with the category's own slug to build the game-list drill-down URL.","example":"mega888-slot"},"wallet_type":{"type":"integer","description":"1=seamless, 2=transfer, 3=app","example":1},"provider_id":{"type":"integer","nullable":true,"example":3},"sort_order":{"type":"integer","example":1},"action":{"type":"string","enum":["launch","game_list"],"example":"launch"},"is_favourite":{"type":"boolean","description":"Only present on `type: service` tiles.","example":true}}},"GameCategory":{"type":"object","description":"A single category shelf. Custom categories (`is_custom: true`, includes the system `recent` / `favourite` shelves) and default catalog categories (no `is_custom` key, carries `status`) are merged into the same list and share this shape.\n","properties":{"id":{"oneOf":[{"type":"string","description":"ULID, for custom categories (including `recent` / `favourite`)."},{"type":"integer","description":"Catalog `service_categories.id`, for default categories."}],"example":2},"name":{"type":"string","example":"Slot"},"slug":{"type":"string","example":"slot"},"type":{"type":"string","description":"Only present on custom categories, e.g. `standard`, `recent`, `favourite`.","example":"standard"},"status":{"type":"boolean","description":"Only present on default (non-custom) categories.","example":true},"icon_url":{"type":"string","example":"https://pub-xxx.r2.dev/tenant_abc/categories/slot.png"},"active_icon_url":{"type":"string","example":"https://pub-xxx.r2.dev/tenant_abc/categories/slot-active.png"},"sort_order":{"type":"integer","example":2},"is_custom":{"type":"boolean","description":"Only present (and `true`) on custom categories.","example":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/GameCategoryItem"}}}},"ProviderApiLogRecord":{"type":"object","properties":{"id":{"type":"string","description":"Log record ID (ULID)","example":"01JCHG2M8S2ABCDE1234567890"},"provider_id":{"type":"integer","description":"Game provider ID","example":3},"provider_name":{"type":"string","description":"Game provider display name","example":"Mega888"},"user_id":{"type":"string","description":"Internal user ID (ULID); empty string if user not found","example":"01JCHG2M8S2ABCDE0987654321"},"username":{"type":"string","description":"Player's username at the provider","example":"john_doe"},"player_name":{"type":"string","description":"Player's display name; empty string if user not found","example":"John Doe"},"endpoint":{"type":"string","description":"Provider API endpoint that was called","example":"/api/v1/balance"},"request":{"description":"Request payload sent to the provider (parsed JSON object, or raw string if not valid JSON)","oneOf":[{"type":"object"},{"type":"string"}],"example":{"action":"getBalance","playerId":"john_doe"}},"response":{"description":"Response payload received from the provider (parsed JSON object, or raw string if not valid JSON)","oneOf":[{"type":"object"},{"type":"string"}],"example":{"balance":100.0,"currency":"MYR"}},"status_code":{"type":"integer","description":"HTTP status code from the provider API call","example":200},"status":{"type":"string","description":"Log status label (e.g. success, failed)","example":"success"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the log was recorded","example":"2025-01-15T10:30:00Z"}}},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer","example":22},"per_page":{"type":"integer","example":200},"current_page":{"type":"integer","example":1},"last_page":{"type":"integer","example":1},"from":{"type":"integer","example":1},"to":{"type":"integer","example":22},"has_more":{"type":"boolean","example":false}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","example":"False"},"message":{"type":"string","example":"Error Description"},"error_code":{"type":"string","example":"Error Code"}}},"RiskType":{"type":"integer","description":"- `1` Register IP\n- `2` Login IP\n- `3` Password\n- `4` Device\n- `5` User Name\n- `6` Account Holder Name\n- `7` Account Number\n","enum":[1,2,3,4,5,6,7],"example":2},"RiskEvent":{"type":"integer","description":"- `1` Login\n- `2` Register\n- `3` Password Change\n- `4` Password Reset\n- `5` Bank Account Create\n","enum":[1,2,3,4,5],"example":1},"UserRiskDashboard":{"type":"object","properties":{"summary":{"type":"object","properties":{"total_users":{"type":"integer","example":5000},"total_flagged_users":{"type":"integer","example":120}}},"risk_levels":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["low","medium","high"]},"label":{"type":"string"},"user_count":{"type":"integer"}}}},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/UserRiskTypeBreakdown"}}}},"UserRiskTypeBreakdown":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/RiskType"},"type_label":{"type":"string","example":"Login IP"},"user_count":{"type":"integer","example":45},"percentage":{"type":"number","format":"float","description":"Share of total flagged users for this type","example":37.5},"trend":{"type":"object","properties":{"current_count":{"type":"integer","example":45},"previous_count":{"type":"integer","example":30},"change_percent":{"type":"number","format":"float","example":50.0},"direction":{"type":"string","enum":["up","down","stable"],"example":"up"}}}}},"TopUserRiskRecord":{"type":"object","properties":{"id":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"},"name":{"type":"string","example":"John Doe"},"type":{"$ref":"#/components/schemas/RiskType"},"type_label":{"type":"string","example":"Login IP"},"matched_count":{"type":"integer","example":12},"matched_users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"01JCHG2M8S2ABCDE1111111111"},"name":{"type":"string","example":"Jane Doe"},"username":{"type":"string","example":"jane_doe"},"similarity_score":{"type":"number","format":"float","example":0.95},"event":{"$ref":"#/components/schemas/RiskEvent"},"event_label":{"type":"string","example":"Login"}}}}}},"UserRiskBreakdownRecord":{"type":"object","properties":{"value":{"type":"string","nullable":true,"description":"Shared attribute value. Masked for Password type (first 2 chars + ***).","example":"192.168.1.1"},"user_count":{"type":"integer","example":3},"id":{"type":"string","nullable":true,"description":"ULID of the primary (canonical) user in this group","example":"01JCHG2M8S2ABCDE0987654321"},"name":{"type":"string","nullable":true,"example":"John Doe"},"event":{"allOf":[{"$ref":"#/components/schemas/RiskEvent"}],"nullable":true},"event_label":{"type":"string","nullable":true,"example":"Login"},"similarity_score":{"type":"number","format":"float","nullable":true,"example":0.95},"matched_user":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"event":{"$ref":"#/components/schemas/RiskEvent"},"event_label":{"type":"string"},"similarity_score":{"type":"number","format":"float"}}}}}},"UserRiskEntry":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/RiskType"},"type_label":{"type":"string","example":"Login IP"},"current_run_id":{"type":"string","nullable":true,"description":"ULID of the most recent risk analysis run for this type","example":"01JCHG2M8S2ABCDE9999999999"},"matched_user_count":{"type":"integer","example":2},"matched_users":{"type":"array","items":{"type":"object","properties":{"matched_user_id":{"type":"string","nullable":true},"matched_user_name":{"type":"string","nullable":true},"matched_user_username":{"type":"string","nullable":true},"similarity_score":{"type":"number","format":"float","nullable":true,"example":0.95},"event":{"$ref":"#/components/schemas/RiskEvent"},"event_label":{"type":"string"}}}}}},"UserRiskUserSummary":{"type":"object","properties":{"summary":{"type":"object","properties":{"total_risk_types":{"type":"integer","description":"Number of risk types where at least one matched user was found","example":2},"total_matched_users":{"type":"integer","description":"Total matched user count across all risk types (may include duplicates across types)","example":5}}},"risks":{"type":"array","items":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/RiskType"},"type_label":{"type":"string","example":"Login IP"},"matched_user_count":{"type":"integer","example":3}}}}}},"UserRiskLogRecord":{"type":"object","properties":{"id":{"type":"string","description":"Log entry ID (ULID)","example":"01JCHG2M8S2ABCDE1234567890"},"value":{"type":"string","nullable":true,"description":"Shared attribute value. Masked for Password type (first 2 chars + ***).","example":"192.168.1.1"},"user_id":{"type":"string","nullable":true,"description":"ULID of the user who owns this log entry","example":"01JCHG2M8S2ABCDE0987654321"},"user_name":{"type":"string","nullable":true,"example":"John Doe"},"user_username":{"type":"string","nullable":true,"example":"john_doe"},"event":{"$ref":"#/components/schemas/RiskEvent"},"event_label":{"type":"string","example":"Login"},"similarity_score":{"type":"number","format":"float","nullable":true,"example":0.95},"created_at":{"type":"string","format":"date-time","example":"2025-01-15T10:30:00Z"}}},"ServiceObject":{"type":"object","description":"Game service data from the gRPC catalog","properties":{"id":{"type":"integer","example":509},"provider_id":{"type":"integer","example":500005},"provider_name":{"type":"string","example":"MegaH5"},"name":{"type":"object","properties":{"en":{"type":"string","example":"Halloween Fortune"},"zh":{"type":"string","example":""}}},"service_code":{"type":"string","example":50122},"category_id":{"type":"integer","example":3},"category_name":{"type":"string","example":"Slots"},"rtp":{"type":"string","example":"98"},"icon_url":{"type":"string","nullable":true,"example":"https://example.com/icon.png"},"status":{"type":"boolean","example":true},"service_tag":{"type":"integer","example":0},"provider_category_id":{"type":"integer","example":4},"wallet_type":{"type":"integer","example":2}}},"CustomHotGameResource":{"type":"object","properties":{"id":{"type":"string","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"service_id":{"type":"integer","example":498},"status":{"type":"boolean","example":true},"sort_order":{"type":"integer","example":3},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"service":{"$ref":"#/components/schemas/ServiceObject","nullable":true,"description":"null if the gRPC catalog cannot resolve the service_id"}}},"UnifiedCategoryItem":{"type":"object","properties":{"type":{"type":"string","enum":["service_category","custom_category"],"example":"service_category"},"id":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Integer for service_category; ULID string for custom_category","example":1},"name":{"type":"string","example":"Slots"},"sort_order":{"type":"integer","description":"Explicit position (1-based). 0 means unordered — these appear after ordered items.","example":1},"icon_url":{"type":"string","nullable":true,"example":"https://example.com/slots.png"}}},"SeoPage":{"type":"object","properties":{"key":{"type":"string","example":"home"},"title":{"type":"string","nullable":true,"example":"Welcome to 0Wallet"},"description":{"type":"string","nullable":true,"example":"The best digital wallet."},"og_title":{"type":"string","nullable":true},"og_description":{"type":"string","nullable":true},"og_image":{"type":"string","nullable":true},"og_image_alt":{"type":"string","nullable":true},"canonical":{"type":"string","nullable":true},"keywords":{"type":"string","nullable":true,"example":"wallet, deposit, withdraw"},"robots_index":{"type":"boolean","example":true},"robots_follow":{"type":"boolean","example":true},"icon_url":{"type":"string","nullable":true,"example":"https://pub-xxx.r2.dev/tenant_abc/seo/01J.png"},"updated_at":{"type":"string","format":"date-time","example":"2026-05-28T08:00:00Z"}}},"ExternalOperatorMetadataInput":{"type":"object","description":"A single mini-game entry within an operator's metadata array.","required":["name","code"],"properties":{"name":{"type":"string","maxLength":255,"example":"Lucky Spin"},"code":{"type":"string","maxLength":255,"example":"lucky_spin"},"redirect_url_web":{"type":"string","maxLength":2048,"nullable":true,"description":"Web redirect URL. May contain a `{player_id}` placeholder.","example":"https://games.example.com/spin?player={player_id}"},"redirect_url_telegram":{"type":"string","maxLength":2048,"nullable":true,"description":"Telegram redirect URL. May contain a `{player_id}` placeholder."},"status":{"type":"boolean","description":"Whether this mini-game is enabled (shown to users).","example":true},"image_url":{"oneOf":[{"type":"string","format":"binary","description":"Uploaded image file (jpg, jpeg, png, webp, gif, svg; max 5MB)."},{"type":"string","description":"Existing R2 object key or absolute URL to keep the current image."}],"nullable":true}}},"ExternalOperatorMetadataItem":{"type":"object","description":"A mini-game entry as returned by the admin API (image_url resolved to a public URL).","properties":{"name":{"type":"string","example":"Lucky Spin"},"code":{"type":"string","example":"lucky_spin"},"redirect_url_web":{"type":"string","nullable":true,"example":"https://games.example.com/spin?player={player_id}"},"redirect_url_telegram":{"type":"string","nullable":true},"status":{"type":"boolean","example":true},"image_url":{"type":"string","nullable":true,"example":"https://pub-xxx.r2.dev/tenant_abc/external-operators/01J.png"}}},"ExternalOperator":{"type":"object","properties":{"id":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"},"name":{"type":"string","example":"Acme Games"},"icon_url":{"type":"string","nullable":true,"description":"The operator's own icon/logo, resolved to a public URL.","example":"https://pub-xxx.r2.dev/tenant_abc/external-operators/01J-icon.png"},"is_active":{"type":"boolean","example":true},"allowed_ips":{"type":"array","nullable":true,"items":{"type":"string","example":"203.0.113.10"}},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/ExternalOperatorMetadataItem"}},"has_token":{"type":"boolean","description":"Present on list responses (withCount). True when the operator has a token.","example":true},"token":{"type":"object","nullable":true,"description":"Present on the show response when tokens are loaded.","properties":{"id":{"type":"string","example":"01JCHG2M8S2ABCDE1234567890"},"name":{"type":"string","example":"Acme Games"},"last_used":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","example":"2026-05-28 08:00:00"}}},"webhooks":{"type":"array","description":"Present on the show response when webhook endpoints are loaded.","items":{"type":"object","properties":{"id":{"type":"string","example":"01JCHG2M8S2ABCDE2222222222"},"event":{"type":"string","example":"deposit.completed"},"url":{"type":"string","example":"https://operator.example.com/webhooks/0wallet"},"is_active":{"type":"boolean","example":true},"updated_at":{"type":"string","example":"2026-05-28 08:00:00"}}}},"created_at":{"type":"string","example":"2026-05-28 08:00:00"},"updated_at":{"type":"string","example":"2026-05-28 08:00:00"}}},"IssuedToken":{"type":"object","properties":{"token_id":{"type":"string","example":"01JCHG2M8S2ABCDE1234567890"},"token_name":{"type":"string","example":"Acme Games"},"plain_text_token":{"type":"string","description":"The plain-text token, returned only once at issue time.","example":"1|abcDEF123456ghiJKL789..."}}},"ExternalApiLogListItem":{"type":"object","description":"External API log entry as returned in list responses (heavy fields omitted).","properties":{"id":{"type":"string","example":"01JCHG2M8S2ABCDE1234567890"},"operator":{"type":"object","nullable":true,"properties":{"id":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"},"name":{"type":"string","example":"Acme Games"}}},"direction":{"type":"string","enum":["in","out"],"example":"in"},"module":{"type":"string","nullable":true,"example":"balance"},"method":{"type":"string","example":"POST"},"status_code":{"type":"integer","nullable":true,"example":200},"ip":{"type":"string","nullable":true,"example":"203.0.113.10"},"user":{"type":"object","nullable":true,"properties":{"id":{"type":"string","example":"01JCHG2M8S2ABCDE5555555555"},"name":{"type":"string","example":"John Doe"},"username":{"type":"string","example":"john_doe"}}},"created_at":{"type":"string","format":"date-time","example":"2025-01-15T10:30:00Z"}}},"WithdrawalApprovalLevel":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"name":{"type":"string","description":"Lowercase, snake_case identifier","example":"verification"},"label":{"type":"string","example":"Verification"},"permission":{"type":"string","description":"Derived as `withdrawal.{name}`; not admin-supplied","example":"withdrawal.verification"},"sort_order":{"type":"integer","description":"Determines approval order; must be unique","example":1},"auto_approve":{"type":"boolean","example":false},"final_override":{"type":"boolean","description":"When true, approval at this level bypasses remaining levels","example":false},"is_active":{"type":"boolean","example":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WithdrawalApprovalLevelCreateInput":{"type":"object","required":["name","label","sort_order"],"properties":{"name":{"type":"string","maxLength":100,"pattern":"^[a-z][a-z0-9_]*$","description":"Must be unique","example":"settlement"},"label":{"type":"string","maxLength":100,"example":"Settlement"},"sort_order":{"type":"integer","description":"Must be unique","example":4},"is_active":{"type":"boolean","example":true},"auto_approve":{"type":"boolean","example":false},"final_override":{"type":"boolean","example":false}}},"WithdrawalApprovalLevelUpdateInput":{"type":"object","description":"All fields optional; only provided fields are updated.","properties":{"name":{"type":"string","maxLength":100,"pattern":"^[a-z][a-z0-9_]*$","description":"Must be unique","example":"settlement"},"label":{"type":"string","maxLength":100,"example":"Settlement (Final)"},"sort_order":{"type":"integer","description":"Must be unique","example":4},"is_active":{"type":"boolean","example":true},"auto_approve":{"type":"boolean","example":false},"final_override":{"type":"boolean","example":true}}},"MiniGame":{"type":"object","description":"A single operator's mini-games, grouped under that operator. Operators with no enabled mini-game entries are omitted from the list response.\n","properties":{"operator_id":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"},"operator_name":{"type":"string","example":"Acme Games"},"operator_icon_url":{"type":"string","nullable":true,"description":"The operator's own icon/logo, resolved to a public URL.","example":"https://pub-xxx.r2.dev/tenant_abc/external-operators/01J-icon.png"},"games":{"type":"array","description":"Enabled mini-game entries (status = true only).","items":{"type":"object","properties":{"name":{"type":"string","nullable":true,"example":"Lucky Spin"},"code":{"type":"string","nullable":true,"example":"lucky_spin"},"image_url":{"type":"string","nullable":true,"example":"https://pub-xxx.r2.dev/tenant_abc/external-operators/01J.png"},"redirect_url_web":{"type":"string","nullable":true,"description":"Omitted when not configured. `{player_id}` is substituted when authenticated.","example":"https://games.example.com/spin?player=01JCHG2M8S2ABCDE0987654321"},"redirect_url_telegram":{"type":"string","nullable":true,"description":"Omitted when not configured."},"status":{"type":"boolean","example":true}}}}}},"LanguageCode":{"type":"string","enum":["en","ms","zh"],"default":"en","example":"en"},"VipLevelPrivilege":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"019e8c65-1fcf-7367-b432-9c096c9982a5"},"vip_level_id":{"type":"string","format":"uuid","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"locale":{"$ref":"#/components/schemas/LanguageCode"},"title":{"type":"string","example":"Priority Support"},"description":{"type":"string","nullable":true,"description":"HTML content, rendered as-is by the frontend (e.g. sanitized `v-html`).","example":"<p>Access to dedicated support line.</p>"},"sort_order":{"type":"integer","example":1},"is_active":{"type":"boolean","example":true}}},"VipLevelTnc":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"019e8c65-1fd7-71dd-8771-83dce5e25457"},"vip_level_id":{"type":"string","format":"uuid","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"locale":{"$ref":"#/components/schemas/LanguageCode"},"terms_conditions":{"type":"string","description":"HTML content, rendered as-is by the frontend (e.g. sanitized `v-html`).","example":"<p>Terms apply to Silver tier rewards.</p>"}}},"VipLevel":{"type":"object","description":"`sort_order = 0` is reserved for the Regular floor and is excluded from the `/v1/user/vip` `all_levels` list. `privileges`, `tncs`, and `rewards` are pre-filtered to active only (`privileges` and `tncs` also to the resolved `lang` locale). `rewards` here is the level's configured reward catalog (`VipLevelReward`), not the user's granted instances -- see the top-level `rewards` key (`UserVipLevelReward`) for that.\n","properties":{"id":{"type":"string","format":"uuid","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"name":{"type":"string","example":"Silver"},"image_path":{"type":"string","format":"uri","nullable":true,"description":"Public URL of the level's badge image, or null if unset.","example":"https://pub-xxx.r2.dev/tenant_abc/vip/silver-badge.png"},"sort_order":{"type":"integer","example":1},"upgrade_match_mode":{"type":"string","description":"Human-readable match rule for upgrade requirements.","example":"Match ALL requirements"},"maintain_match_mode":{"type":"string","description":"Human-readable match rule for maintenance requirements.","example":"Match ALL requirements"},"is_active":{"type":"boolean","example":true},"privileges":{"type":"array","items":{"$ref":"#/components/schemas/VipLevelPrivilege"}},"tncs":{"type":"array","items":{"$ref":"#/components/schemas/VipLevelTnc"}},"rewards":{"type":"array","description":"The level's configured reward catalog (active only), not the user's granted instances.","items":{"$ref":"#/components/schemas/VipLevelReward"}},"upgrade_requirements":{"type":"array","description":"Only present on `all_levels` entries (not `current_level`/`next_level`).","items":{"$ref":"#/components/schemas/VipLevelUpgradeRequirement"}}}},"VipLevelUpgradeRequirement":{"type":"object","description":"A raw requirement row (not user-progress-aware; see `VipLevelProgressItem` for that).","properties":{"id":{"type":"string","format":"uuid","example":"019e8c65-2200-71ea-934b-9703ef41cd5e"},"vip_level_id":{"type":"string","format":"uuid","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"vip_condition_type_id":{"type":"string","format":"uuid","example":"019e8c65-2300-71ea-934b-9703ef41cd5e"},"requirement_type":{"type":"integer","description":"`1` = Upgrade, `2` = Maintain","enum":[1,2],"example":1},"threshold_value":{"type":"string","example":"100.00"},"is_active":{"type":"boolean","example":true},"condition_type":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid","example":"019e8c65-2300-71ea-934b-9703ef41cd5e"},"key":{"type":"string","example":"total_deposit_amount"},"name":{"type":"string","example":"Total Deposit Amount"},"is_active":{"type":"boolean","example":true}}}}},"VipLevelProgressItem":{"type":"object","description":"Progress of the authenticated user toward one of `next_level`'s active upgrade requirements.","properties":{"condition_key":{"type":"string","example":"total_deposit_amount"},"condition_name":{"type":"string","example":"Total Deposit Amount"},"value_type":{"type":"integer","description":"`1` = Count, `2` = Currency Amount","enum":[1,2],"example":2},"current_value":{"type":"number","format":"float","example":1500.0},"threshold":{"type":"number","format":"float","example":5000.0},"completed":{"type":"boolean","example":false}}},"VipLevelReward":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"vip_level_id":{"type":"string","format":"uuid","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"name":{"type":"string","example":"Silver Upgrade Bonus"},"reward_type":{"type":"string","description":"Human-readable reward type.","example":"Bonus"},"amount":{"type":"string","example":"50.00"},"unlock_match_mode":{"type":"string","description":"Human-readable match rule for unlock conditions.","example":"Match ALL requirements"},"unlock_trigger":{"type":"string","description":"Human-readable unlock trigger.","example":"Claimable immediately on level upgrade"},"withdrawal_match_mode":{"type":"string","description":"Human-readable match rule for withdrawal conditions.","example":"Match ALL requirements"},"is_active":{"type":"boolean","example":true},"sort_order":{"type":"integer","example":1}}},"UserVipLevelRewardProgressItem":{"type":"object","description":"Progress toward one of the reward's unlock/withdrawal conditions.","properties":{"condition_key":{"type":"string","example":"total_turnover"},"condition_name":{"type":"string","example":"Total Turnover"},"current_value":{"type":"number","format":"float","example":200.0},"target_value":{"type":"number","format":"float","example":500.0},"completed":{"type":"boolean","example":false}}},"UserVipLevelReward":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"019e8c65-2100-71ea-934b-9703ef41cd5e"},"user_id":{"type":"string","example":"01JCHG2M8S2ABCDE0987654321"},"vip_level_reward_id":{"type":"string","format":"uuid","example":"019e8c65-1fc2-71ea-934b-9703ef41cd5e"},"user_vip_level_log_id":{"type":"string","format":"uuid","nullable":true,"example":"019e8c65-1fc2-71ea-934b-9703ef41cd60"},"status":{"type":"string","description":"Human-readable status (\"Locked\", \"Claimable\", \"Claimed\", or \"Voided\").","example":"Claimable"},"granted_amount":{"type":"string","example":"50.00"},"metadata":{"type":"object","nullable":true},"granted_at":{"type":"string","format":"date-time","nullable":true},"unlocked_at":{"type":"string","format":"date-time","nullable":true},"claimed_at":{"type":"string","format":"date-time","nullable":true},"reward":{"$ref":"#/components/schemas/VipLevelReward"},"can_claim":{"type":"boolean","description":"True when `status` is \"Claimable\".","example":true},"progress":{"type":"array","items":{"$ref":"#/components/schemas/UserVipLevelRewardProgressItem"}}}}},"responses":{"Unauthenticated":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"status":"false","message":"Unauthenticated","error_code":null}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/aaa-84a/0WalletApiResponse/0.0.1"}]}