{
  "openapi": "3.1.0",
  "info": {
    "title": "HuayEngine Provider API",
    "version": "0.2.0",
    "description": "HMAC-signed Provider API for partners integrating with HuayEngine.\nEvery request carries `X-Api-Key`, `X-Request-Id`, `X-Timestamp` and `X-Signature`.\nHMAC v2 binds method, path with query, timestamp, request ID, idempotency key and body digest.\nEndpoints that move money or change state also require `Idempotency-Key`\n(retry with the SAME key; responses are replayed for 24h).\nMoney is integer satang (100 = 1 THB). Envelope: {data, error:{code,message}, request_id}.\nFull guide: docs/20_PROVIDER_INTEGRATION.md · step-by-step: docs/22_PARTNER_INTEGRATION_GUIDE.md.\nOperations marked x-internal are platform-only and are stripped from the studio copy.\n"
  },
  "servers": [
    {
      "url": "https://huayapi-staging.huaysanook.online",
      "description": "Staging"
    },
    {
      "url": "https://huayapi.huaysanook.online",
      "description": "Production"
    },
    {
      "url": "http://localhost:9080",
      "description": "Local"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": [],
      "SignatureAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      },
      "SignatureAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Signature"
      }
    },
    "parameters": {
      "RequestId": {
        "name": "X-Request-Id",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "properties": {
          "data": {},
          "error": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "description": "Optional structured details (validation errors)."
              }
            }
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "PlaceBetRequest": {
        "type": "object",
        "required": [
          "round_id",
          "items"
        ],
        "properties": {
          "member_code": {
            "type": "string",
            "example": "AB000123",
            "description": "Preferred. Send member_code, not member_id — an unknown member_id silently gets an empty wallet."
          },
          "member_id": {
            "type": "integer",
            "format": "int64",
            "description": "Legacy alternative to member_code (wins when both are sent)."
          },
          "session_token": {
            "type": "string",
            "description": "Optional — token from POST /session/launch. A seamless session is authoritative for the member; an invalid/expired token is rejected (401 session_invalid), never downgraded to transfer."
          },
          "round_id": {
            "type": "integer",
            "format": "int64",
            "example": 4567
          },
          "reference": {
            "type": "string",
            "maxLength": 64,
            "example": "AB-1001",
            "description": "Your bill id — used to find the ticket again via /bet/history."
          },
          "currency": {
            "type": "string",
            "example": "THB",
            "description": "Seamless (external_member) keys only."
          },
          "wallet_owner_id": {
            "type": "integer",
            "description": "Seamless (external_member) keys only — must match the key binding."
          },
          "wallet_tenant_id": {
            "type": "integer",
            "description": "Seamless (external_member) keys only — must match the key binding."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "bet_type_code",
                "number",
                "stake_satang"
              ],
              "properties": {
                "bet_type_code": {
                  "type": "string",
                  "enum": [
                    "3_top",
                    "3_toad",
                    "2_top",
                    "2_bottom",
                    "run_top",
                    "run_bottom",
                    "3_front",
                    "3_bottom"
                  ]
                },
                "number": {
                  "type": "string",
                  "example": "123",
                  "description": "Always a string (keeps leading zeros)."
                },
                "stake_satang": {
                  "type": "integer",
                  "format": "int64",
                  "description": "stake in satang (100 = 1 baht)"
                }
              }
            }
          }
        }
      },
      "WalletMoveRequest": {
        "type": "object",
        "required": [
          "member_id",
          "amount_satang",
          "reference"
        ],
        "properties": {
          "member_id": {
            "type": "integer",
            "format": "int64",
            "description": "Numeric member_id from POST /members (wallet uses member_id, bet/place uses member_code)."
          },
          "amount_satang": {
            "type": "integer",
            "format": "int64",
            "example": 50000
          },
          "reference": {
            "type": "string",
            "example": "AB-D-981",
            "description": "Your transaction id."
          }
        }
      },
      "ResultSubmitRequest": {
        "type": "object",
        "required": [
          "round_id",
          "top3",
          "bottom2"
        ],
        "properties": {
          "round_id": {
            "type": "integer",
            "format": "int64"
          },
          "top3": {
            "type": "string",
            "example": "123"
          },
          "bottom2": {
            "type": "string",
            "example": "45"
          }
        }
      },
      "YeekeeIdentity": {
        "type": "object",
        "description": "Signed JSON body required even on personalized GET. Transfer uses member_ref/member_code; seamless additionally requires all agent fields. Session token must belong to this provider client and cannot carry agent_tenant_id.",
        "properties": {
          "member_ref": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,64}$"
          },
          "member_code": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,64}$",
            "description": "Alias; must match member_ref if both supplied"
          },
          "session_token": {
            "type": "string"
          },
          "agent_owner_id": {
            "type": "integer",
            "minimum": 1
          },
          "agent_tenant_id": {
            "type": "integer",
            "minimum": 1
          },
          "agent_node_path": {
            "type": "string"
          }
        }
      },
      "YeekeeProviderShot": {
        "allOf": [
          {
            "$ref": "#/components/schemas/YeekeeIdentity"
          },
          {
            "type": "object",
            "required": [
              "number"
            ],
            "properties": {
              "number": {
                "type": "string",
                "pattern": "^[0-9]{5}$",
                "example": "00001"
              }
            }
          }
        ],
        "unevaluatedProperties": false
      },
      "YeekeeState": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "round_id",
          "lottery_type_id",
          "lottery_code",
          "algorithm",
          "shooting_enabled",
          "accepts_shots",
          "open_at",
          "close_at",
          "server_time",
          "shot_count",
          "shot_sum",
          "cadence_ms",
          "member_round_cap",
          "my_count",
          "seed_hash"
        ],
        "properties": {
          "round_id": {
            "type": "integer",
            "minimum": 1
          },
          "lottery_type_id": {
            "type": "integer",
            "minimum": 1
          },
          "lottery_code": {
            "type": "string"
          },
          "algorithm": {
            "type": "string",
            "enum": [
              "yeekee:v2",
              "yeekee:v3"
            ]
          },
          "shooting_enabled": {
            "type": "boolean"
          },
          "accepts_shots": {
            "type": "boolean"
          },
          "open_at": {
            "type": "string",
            "format": "date-time"
          },
          "close_at": {
            "type": "string",
            "format": "date-time"
          },
          "server_time": {
            "type": "string",
            "format": "date-time"
          },
          "shot_count": {
            "type": "integer",
            "minimum": 0
          },
          "shot_sum": {
            "type": "integer",
            "minimum": 0
          },
          "cadence_ms": {
            "type": "integer"
          },
          "member_round_cap": {
            "type": "integer"
          },
          "my_count": {
            "type": "integer",
            "minimum": 0
          },
          "next_shot_at": {
            "type": "string",
            "format": "date-time"
          },
          "seed_hash": {
            "type": "string"
          }
        }
      },
      "YeekeeReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "round_id",
          "shot_id",
          "sequence",
          "number",
          "accepted_at"
        ],
        "properties": {
          "round_id": {
            "type": "integer",
            "minimum": 1
          },
          "shot_id": {
            "type": "integer",
            "minimum": 1
          },
          "sequence": {
            "type": "integer",
            "minimum": 1
          },
          "number": {
            "type": "string",
            "pattern": "^[0-9]{5}$"
          },
          "accepted_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "YeekeePage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items",
          "next_sequence",
          "has_more"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "sequence",
                "number",
                "accepted_at",
                "is_mine"
              ],
              "properties": {
                "sequence": {
                  "type": "integer",
                  "minimum": 1
                },
                "number": {
                  "type": "string",
                  "pattern": "^[0-9]{5}$"
                },
                "accepted_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "is_mine": {
                  "type": "boolean"
                }
              }
            }
          },
          "next_sequence": {
            "type": "integer",
            "minimum": 0,
            "maximum": 18446744073709551615
          },
          "has_more": {
            "type": "boolean"
          }
        }
      },
      "YeekeeProof": {
        "type": "object",
        "additionalProperties": false,
        "description": "No seed or seed_enc before close/reveal. Revealed v3 proof is validated against the complete frozen transcript; result is computed without writing.",
        "required": [
          "tenant_id",
          "round_id",
          "version",
          "algorithm",
          "seed_hash",
          "committed_at"
        ],
        "properties": {
          "tenant_id": {
            "type": "integer",
            "minimum": 1,
            "description": "Canonical transcript scope"
          },
          "round_id": {
            "type": "integer",
            "minimum": 1
          },
          "version": {
            "type": "integer",
            "enum": [
              2,
              3
            ]
          },
          "algorithm": {
            "type": "string",
            "enum": [
              "yeekee:v2",
              "yeekee:v3"
            ]
          },
          "seed_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "committed_at": {
            "type": "string",
            "format": "date-time"
          },
          "revealed_at": {
            "type": "string",
            "format": "date-time"
          },
          "seed": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "bet_total": {
            "type": "integer",
            "format": "int64"
          },
          "frozen_count": {
            "type": "integer",
            "minimum": 0
          },
          "frozen_sum": {
            "type": "integer",
            "minimum": 0
          },
          "frozen_digest": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "subtracted_sequence": {
            "type": "integer",
            "minimum": 0
          },
          "subtracted_number": {
            "type": "string",
            "pattern": "^[0-9]{5}$"
          },
          "frozen_at": {
            "type": "string",
            "format": "date-time"
          },
          "top3": {
            "type": "string",
            "pattern": "^[0-9]{3}$"
          },
          "bottom2": {
            "type": "string",
            "pattern": "^[0-9]{2}$"
          }
        }
      },
      "YeekeeConfig": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "enabled",
          "cadence_ms",
          "member_round_cap",
          "round_shot_cap"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "minimum": 0
          },
          "enabled": {
            "type": "boolean",
            "default": false
          },
          "cadence_ms": {
            "type": "integer",
            "minimum": 1000,
            "maximum": 60000,
            "default": 1000
          },
          "member_round_cap": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000,
            "default": 100
          },
          "round_shot_cap": {
            "type": "integer",
            "minimum": 16,
            "maximum": 1000000,
            "default": 100000
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/provider/session/launch": {
      "post": {
        "summary": "Launch a member game session (transfer keys also get a one-time play launch_url)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lottery_round_id": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Optional exact selected round. Mutually exclusive with lottery_type_id. Must belong to this tenant, be currently open, and be permitted by this provider client."
                  },
                  "lottery_type_id": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Optional market selection. Server resolves the earliest closing actually accepting persisted round of this type and persists that exact target. Mutually exclusive with lottery_round_id."
                  },
                  "member_code": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{1,64}$",
                    "example": "HP000123"
                  },
                  "member_ref": {
                    "type": "string",
                    "description": "Legacy alias of member_code"
                  },
                  "return_url": {
                    "type": "string",
                    "maxLength": 512,
                    "example": "https://partner.example/lobby",
                    "description": "Absolute https URL (checked only when a launch link is issued)."
                  },
                  "lang": {
                    "type": "string",
                    "enum": [
                      "th",
                      "en",
                      "lo"
                    ]
                  },
                  "agent_owner_id": {
                    "type": "integer",
                    "description": "Seamless keys only — per-request agent identity. Required together with agent_tenant_id, agent_node_path and member_code for a seamless launch link; ignored for transfer keys."
                  },
                  "agent_tenant_id": {
                    "type": "integer",
                    "description": "Seamless keys only (see agent_owner_id)."
                  },
                  "agent_node_path": {
                    "type": "string",
                    "example": "/15/26/",
                    "description": "Seamless keys only (see agent_owner_id)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "{session_token, member_ref, expires_at}; optional launch_round_id identifies the resolved target; launch_url/launch_expires_at/member_id appear only when the engine enables launch links (MEMBER_LAUNCH_ENABLED) — always for transfer keys, for seamless keys only when the agent_* identity is sent (code is single-use, 120s).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (invalid member_code / return_url / lang",
            "or member_code and member_ref disagree)": null
          },
          "403": {
            "description": "member_inactive | tenant_suspended | launch_target_unavailable | backend_only (external_member keys cannot launch)"
          },
          "422": {
            "description": "seamless_identity_missing (seamless key without a complete agent identity)"
          },
          "500": {
            "description": "session_failed | launch_failed (retryable)"
          },
          "503": {
            "description": "seamless_not_wired (seamless launch links not enabled on this engine)"
          }
        }
      }
    },
    "/api/v1/provider/session/validate": {
      "post": {
        "summary": "Validate a session token",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "session_token"
                ],
                "properties": {
                  "session_token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{valid, member_ref, expires_at}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (session_token missing)"
          },
          "401": {
            "description": "session_invalid"
          }
        }
      }
    },
    "/api/v1/provider/members": {
      "post": {
        "summary": "Ensure a member by member_code (idempotent — no Idempotency-Key needed)",
        "description": "Transfer keys and external_member keys only — a seamless key without external_member gets 403 wallet_mode_not_allowed. Returns the same member_id on repeat. Send no personal data. Keep member_id — transfer wallet calls need it.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "member_code"
                ],
                "properties": {
                  "member_code": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{1,64}$",
                    "example": "AB000123"
                  },
                  "member_id": {
                    "type": "integer",
                    "description": "external_member keys only — optional existing member_id to bind."
                  },
                  "wallet_owner_id": {
                    "type": "integer",
                    "description": "external_member keys only — must match the key binding."
                  },
                  "wallet_tenant_id": {
                    "type": "integer",
                    "description": "external_member keys only — must match the key binding."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created — {member_id, member_code, status, created:true}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "200": {
            "description": "Already existed — created:false",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (member_code not 1-64 of A-Z a-z 0-9 _ -)"
          },
          "403": {
            "description": "wallet_mode_not_allowed | binding_mismatch (wallet_* sent by a non-external key",
            "or not matching the binding)": null
          },
          "500": {
            "description": "member_provision_failed (retryable)"
          }
        }
      }
    },
    "/api/v1/provider/wallet/balance": {
      "post": {
        "summary": "Get member wallet balance (transfer mode)",
        "description": "external_member keys send member_code + wallet_owner_id + wallet_tenant_id instead; the engine asks the key's seamless callback live and returns {member_id, member_code, balance_satang, currency}.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "member_id"
                ],
                "properties": {
                  "member_id": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{member_id, balance_satang, balance (decimal string), currency}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (member_id missing)"
          },
          "403": {
            "description": "binding_mismatch (external_member keys)"
          },
          "500": {
            "description": "wallet_error (retryable)"
          },
          "503": {
            "description": "wallet_error (external_member keys — callback unavailable)"
          }
        }
      }
    },
    "/api/v1/provider/wallet/deposit": {
      "post": {
        "summary": "Deposit into a member wallet (transfer mode)",
        "description": "422 payment_failed does not guarantee no money moved — compare balance before/after before concluding.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WalletMoveRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Payment transaction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (member_id missing) | idempotency_required"
          },
          "409": {
            "description": "idempotency_in_progress | replay_detected"
          },
          "422": {
            "description": "payment_failed"
          }
        }
      }
    },
    "/api/v1/provider/wallet/withdraw": {
      "post": {
        "summary": "Withdraw from a member wallet (transfer mode)",
        "description": "Debit the engine wallet BEFORE paying the player out; on payout failure deposit back with your own -R reference.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WalletMoveRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Payment transaction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (member_id missing) | idempotency_required"
          },
          "409": {
            "description": "idempotency_in_progress | replay_detected"
          },
          "422": {
            "description": "payment_failed"
          }
        }
      }
    },
    "/api/v1/provider/bet/place": {
      "post": {
        "summary": "Place a bet (atomic, idempotent)",
        "description": "Store the Idempotency-Key and request bytes before sending; retry with the same key and bytes (new X-Request-Id). Response has no items — read them with GET /bet/{ticket_id}.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlaceBetRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Ticket {id, lottery_round_id, reference, total_stake, potential_win, status, idempotency_key, ...}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request | idempotency_required | amount_overflow (external_member keys)"
          },
          "401": {
            "description": "session_invalid (session_token sent but invalid/expired)"
          },
          "403": {
            "description": "lottery_not_allowed | tenant_suspended | binding_mismatch"
          },
          "409": {
            "description": "idempotency_in_progress | replay_detected | idempotency_conflict"
          },
          "422": {
            "description": "round_closed | number_held | duplicate_bet | stake_out_of_range | unknown_bet_type | no_items | rate_exceeds_ceiling | wallet_rejected | seamless_not_wired | unknown_member | seamless_identity_missing | seamless_member_mismatch | placement_rejected | placement_compensated | place_bet_failed"
          },
          "500": {
            "description": "member_lookup_failed (retryable)"
          },
          "503": {
            "description": "placement_pending (seamless external — retry same key or ask /bet/attempt)"
          }
        }
      }
    },
    "/api/v1/provider/bet/attempt": {
      "post": {
        "summary": "Look up a placement by Idempotency-Key (seamless external_member keys only)",
        "description": "accepted → use the returned ticket · 404 attempt_not_found → resend bet/place with the same key · other states → still unknown.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "member_id",
                  "idempotency_key",
                  "wallet_owner_id",
                  "wallet_tenant_id"
                ],
                "properties": {
                  "member_id": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "idempotency_key": {
                    "type": "string",
                    "maxLength": 80
                  },
                  "wallet_owner_id": {
                    "type": "integer"
                  },
                  "wallet_tenant_id": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Placement state (+ ticket when accepted)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (member_id / idempotency_key missing or key longer than 80)"
          },
          "403": {
            "description": "forbidden (not an external_member key) | binding_mismatch"
          },
          "404": {
            "description": "attempt_not_found"
          },
          "503": {
            "description": "placement_pending"
          }
        }
      }
    },
    "/api/v1/provider/bet/settlement-proof": {
      "post": {
        "summary": "Engine-side proof of a ticket's settlement (seamless external_member keys only)",
        "description": "Send generation and item_ref together to ask about one winning item — they match settlement_generation / settlement_item_ref in the settle callback.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ticket_id",
                  "member_id",
                  "wallet_owner_id",
                  "wallet_tenant_id"
                ],
                "properties": {
                  "ticket_id": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "member_id": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Engine member_id from POST /members."
                  },
                  "wallet_owner_id": {
                    "type": "integer"
                  },
                  "wallet_tenant_id": {
                    "type": "integer"
                  },
                  "generation": {
                    "type": "integer",
                    "description": "Optional — required together with item_ref."
                  },
                  "item_ref": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "Optional — required together with generation."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ticket, item?, generation_status?, credit_status?, reversal_status?}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (ticket_id / member_id missing",
            "or only one of generation / item_ref)": null
          },
          "403": {
            "description": "forbidden (not an external_member key) | binding_mismatch"
          },
          "404": {
            "description": "proof_not_found"
          },
          "503": {
            "description": "proof_unavailable"
          }
        }
      }
    },
    "/api/v1/provider/bet/cancel": {
      "post": {
        "summary": "Cancel a ticket",
        "description": "Only while the round still accepts bets. The Idempotency-Key is bound to this API key and the exact request body — the same key with a different body is 409 idempotency_conflict. Seamless keys: the engine does NOT refund on cancel — confirm refunds from your own callback receipts.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ticket_id"
                ],
                "properties": {
                  "ticket_id": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ticket_id, status, cancellation_action, refund_status, refund_reference}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (ticket_id missing) | idempotency_required"
          },
          "403": {
            "description": "lottery_not_allowed (ticket's market is outside this key's scope)"
          },
          "409": {
            "description": "idempotency_conflict (same key",
            "different body) | idempotency_in_progress | replay_detected": null
          },
          "422": {
            "description": "round_closed | cancel_failed"
          },
          "503": {
            "description": "refund_status_unavailable (cancel committed; read the ticket again)"
          }
        }
      }
    },
    "/api/v1/provider/bet/{ticket_id}": {
      "get": {
        "summary": "Get a ticket with items (stake, rate_num/rate_den, potential_payout, payout, settlement_status)",
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ticket, items}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (ticket_id not numeric)"
          },
          "404": {
            "description": "not_found"
          }
        }
      }
    },
    "/api/v1/provider/bets/detail": {
      "get": {
        "summary": "Items of many tickets in one call (max 200)",
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated ticket ids, max 200",
            "example": "789,790"
          }
        ],
        "responses": {
          "200": {
            "description": "{bills: [{ticket_id, items}]} — one entry per requested id; unknown/foreign ids get items: [] and non-numeric ids are skipped",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "500": {
            "description": "batch_failed (retryable)"
          }
        }
      }
    },
    "/api/v1/provider/bet/history": {
      "get": {
        "summary": "Last 100 tickets of a member",
        "parameters": [
          {
            "name": "member_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tickets (newest first, max 100)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (member_id missing)"
          }
        }
      }
    },
    "/api/v1/provider/games": {
      "get": {
        "summary": "List lottery types open to this key",
        "responses": {
          "200": {
            "description": "[{id, code, name_th, name_en, category_id, sort_order, active}]",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/provider/rounds": {
      "get": {
        "summary": "List rounds",
        "description": "Omit lottery_type_id → one representative round per active market (soonest-closing open, else latest) for the member lobby. lottery_type_id=N → that type's rounds (up to 300).",
        "parameters": [
          {
            "name": "lottery_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Filter to a single lottery type (returns all its rounds); omitted returns one representative round per market."
          }
        ],
        "responses": {
          "200": {
            "description": "[{id, lottery_type_id, lottery_code, name, round_date, open_at, close_at, draw_at, status}]",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "lottery_not_allowed"
          }
        }
      }
    },
    "/api/v1/provider/rounds/{roundID}/betconfig": {
      "get": {
        "summary": "Frozen bet config of a round (odds, min/max stake, accepts_bets)",
        "description": "bet_types[code] = {rate:{num,den}, min_stake, max_stake, number_limit, member_limit, payout_risk_limit, ladder}. Do not show number_limit / member_limit / payout_risk_limit / ladder to players.",
        "parameters": [
          {
            "name": "roundID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (roundID not numeric)"
          },
          "403": {
            "description": "lottery_not_allowed"
          },
          "404": {
            "description": "not_found (round or snapshot)"
          }
        }
      }
    },
    "/api/v1/provider/rounds/{roundID}/yeekee-commitment": {
      "get": {
        "summary": "Yeekee commit-reveal — seed_hash before draw, seed after",
        "parameters": [
          {
            "name": "roundID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{round_id, algorithm, seed_hash, committed_at, seed?, bet_total?, revealed_at?, frozen_*?}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (roundID not numeric)"
          },
          "403": {
            "description": "lottery_not_allowed"
          },
          "404": {
            "description": "not_found (no commitment for this round)"
          },
          "500": {
            "description": "read_failed (retryable)"
          }
        }
      }
    },
    "/api/v1/provider/rounds/{roundID}/close": {
      "post": {
        "summary": "Stop accepting bets on an open round of your tenant (irreversible)",
        "description": "No body — sign the SHA-256 of an empty body (HMAC v2). Accepted tickets stay accepted.",
        "parameters": [
          {
            "name": "roundID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "{round_id, status: closed}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "description": "lottery_not_allowed"
          },
          "404": {
            "description": "round_not_found (also another tenant's round)"
          },
          "422": {
            "description": "not_closable"
          },
          "500": {
            "description": "lookup_failed | close_failed (retryable)"
          }
        }
      }
    },
    "/api/v1/provider/rounds/{roundID}/void": {
      "post": {
        "summary": "Cancel a whole round and refund every ticket",
        "description": "Retry only with the same Idempotency-Key — 422 not_voidable after a timeout may mean the first call succeeded. Seamless keys get a rollback callback per ticket.",
        "parameters": [
          {
            "name": "roundID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "1–200 code points, no control characters",
                    "example": "ตลาดต้นทางงดออกผล"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{round_id, status: cancelled, refunded}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (reason)"
          },
          "403": {
            "description": "lottery_not_allowed"
          },
          "404": {
            "description": "round_not_found"
          },
          "422": {
            "description": "not_voidable | refund_failed"
          },
          "500": {
            "description": "lookup_failed | void_failed (nothing refunded — retry with the same key)"
          },
          "503": {
            "description": "void_unavailable"
          }
        }
      }
    },
    "/api/v1/provider/results": {
      "get": {
        "summary": "List results",
        "parameters": [
          {
            "name": "lottery_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "th_gov"
          },
          {
            "name": "draw_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 400
            }
          }
        ],
        "responses": {
          "200": {
            "description": "[{lottery_id, lottery_name, round_id, draw_date, numbers}]",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/provider/results/status": {
      "get": {
        "summary": "Result status for a round",
        "parameters": [
          {
            "name": "round_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{round_id, published, top3, top2, bottom2}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "description": "bad_request (round_id missing)"
          },
          "500": {
            "description": "status_failed (retryable)"
          }
        }
      }
    },
    "/api/v1/provider/rounds/{roundID}/yeekee/state": {
      "parameters": [
        {
          "name": "roundID",
          "in": "path",
          "required": true,
          "schema": {
            "type": "integer",
            "minimum": 1
          }
        }
      ],
      "get": {
        "summary": "Read personalized yeekee state (signed identity JSON body)",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/YeekeeIdentity"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK; Cache-Control private, no-store",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/YeekeeState"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_shot_request"
          },
          "403": {
            "description": "lottery_not_allowed or member_not_allowed"
          },
          "422": {
            "description": "not_yeekee",
            "round_not_open": null,
            "commitment_unavailable": null,
            "or shooting_integrity_error": null
          },
          "500": {
            "description": "shooting_failed or scope/lookup failure; fixed safe message"
          }
        }
      }
    },
    "/api/v1/provider/rounds/{roundID}/yeekee/shots": {
      "parameters": [
        {
          "name": "roundID",
          "in": "path",
          "required": true,
          "schema": {
            "type": "integer",
            "minimum": 1
          }
        }
      ],
      "get": {
        "summary": "Read personalized yeekee shots (signed identity JSON body)",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestId"
          },
          {
            "name": "after_sequence",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 18446744073709551615,
              "default": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "mine",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Only literal true/false; caller identity is never a query selector"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/YeekeeIdentity"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK; Cache-Control private, no-store",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/YeekeePage"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_shot_request"
          },
          "403": {
            "description": "lottery_not_allowed or member_not_allowed"
          },
          "422": {
            "description": "not_yeekee",
            "round_not_open": null,
            "commitment_unavailable": null,
            "or shooting_integrity_error": null
          },
          "500": {
            "description": "shooting_failed or scope/lookup failure; fixed safe message"
          }
        }
      },
      "post": {
        "summary": "Accept a five-digit shot (DB-authoritative replay; no wallet movement)",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/YeekeeProviderShot"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Accepted or identical receipt replay, including after close",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/YeekeeReceipt"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_shot_number",
            "invalid_shot_request": null,
            "or idempotency_required; key is 1-128 visible ASCII bytes": null
          },
          "403": {
            "description": "lottery_not_allowed or member_not_allowed"
          },
          "409": {
            "description": "idempotency_conflict or replay_detected"
          },
          "422": {
            "description": "shooting_disabled",
            "not_yeekee": null,
            "round_not_open": null,
            "round_closed": null,
            "shot_limit_reached": null,
            "commitment_unavailable": null,
            "or shooting_integrity_error": null
          },
          "429": {
            "description": "shot_rate_limited or provider rate_limited"
          },
          "500": {
            "description": "shooting_failed; fixed safe message"
          }
        }
      }
    },
    "/api/v1/provider/rounds/{roundID}/yeekee/proof": {
      "parameters": [
        {
          "name": "roundID",
          "in": "path",
          "required": true,
          "schema": {
            "type": "integer",
            "minimum": 1
          }
        }
      ],
      "get": {
        "summary": "Read personalized yeekee proof (signed identity JSON body)",
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/YeekeeIdentity"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK; Cache-Control private, no-store",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/YeekeeProof"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "invalid_shot_request"
          },
          "403": {
            "description": "lottery_not_allowed or member_not_allowed"
          },
          "422": {
            "description": "not_yeekee",
            "round_not_open": null,
            "commitment_unavailable": null,
            "or shooting_integrity_error": null
          },
          "500": {
            "description": "shooting_failed or scope/lookup failure; fixed safe message"
          }
        }
      }
    }
  }
}
