POST /betwin

Beexar → Operator

Beexar sends this request to debit and/or credit the player balance during gameplay. All transactions in the request must be processed atomically and in order.

This single endpoint replaces separate bet and win calls — both transaction types are included in the transactions array.

---

Request

POST {betwin_url}

Headers

Header	Value
Content-Type	application/json
X-REQUEST-SIGN	HMAC-SHA256 signature of request body

Body

Field	Type	Required	Description
account_id	string	Yes	Player account identifier
currency	string	Yes	Currency code — standard ("USD", "EUR", "BTC") or custom ("CUSTOM_GOLD")
game_id	string	Yes	Game identifier (slug)
round_id	string	Yes	Game round identifier (generated by Beexar)
finished	boolean	No	If true, the round is complete — no /finish call will follow
transactions	array	Yes	List of bet/win transactions (min 1)
session_id	string	No	Session identifier (UUID) of the session that opened the round — the same in every request of this round_id, also when the player settles it after relaunching the game. Always sent, but operators are not required to use it

Transaction Object

Each item in the transactions array:

Field	Type	Required	Description
id_provider	string	Yes	Unique transaction identifier (generated by Beexar, used for idempotency)
type	string	Yes	"bet" or "win"
amount	string	Yes	Transaction amount as decimal string (must be > 0)

---

Examples

Simple Round (Dice — bet + win, finished)

A player bets 10 USD and wins 19.80 USD. The round is complete in one request:

{
  "account_id": "player_123",
  "currency": "USD",
  "game_id": "dice",
  "round_id": "550e8400-e29b-41d4-a716-446655440000",
  "finished": true,
  "transactions": [
    { "id_provider": "tx_bet_001", "type": "bet", "amount": "10.00" },
    { "id_provider": "tx_win_001", "type": "win", "amount": "19.80" }
  ],
  "session_id": "7b115688-3849-490a-95bd-7c281d81c64c"
}

Bet Only (Candy Cash — the drop starts)

A player places a bet. The round stays open: its win is credited when the round settles:

{
  "account_id": "player_123",
  "currency": "USD",
  "game_id": "candy-cash",
  "round_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "finished": false,
  "transactions": [
    { "id_provider": "tx_bet_002", "type": "bet", "amount": "5.00" }
  ]
}

Win Only (Candy Cash — the drop lands)

The win of the same round, credited when the round settles. It closes the round:

{
  "account_id": "player_123",
  "currency": "USD",
  "game_id": "candy-cash",
  "round_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "finished": true,
  "transactions": [
    { "id_provider": "tx_win_002", "type": "win", "amount": "15.00" }
  ]
}

Losing Round (Plinko — bet only, finished)

A player bets and loses. No win transaction:

{
  "account_id": "player_123",
  "currency": "EUR",
  "game_id": "plinko",
  "round_id": "deadbeef-cafe-1234-5678-abcdef012345",
  "finished": true,
  "transactions": [
    { "id_provider": "tx_bet_003", "type": "bet", "amount": "2.50" }
  ]
}

---

Response

Success (200 OK)

Field	Type	Required	Description
round_id	string	Yes	Round identifier on operator side
balance	string	Yes	Player balance after all transactions
transactions	array	Yes	Results for each transaction (same order as request)

Each transaction result:

Field	Type	Required	Description
id_provider	string	Yes	Transaction identifier from request (echo back)
id	string	Yes	Transaction identifier assigned by operator

{
  "round_id": "697962ac-fd0d-4dc2-b52c-e850e40825dc",
  "balance": "509.80",
  "transactions": [
    { "id_provider": "tx_bet_001", "id": "op_tx_101" },
    { "id_provider": "tx_win_001", "id": "op_tx_102" }
  ]
}

Error Responses

Errors use the Twirp format with an api_code in the meta field:

HTTP Status	Twirp Code	api_code	Description
400	invalid_argument	100	Insufficient funds
400	invalid_argument	105	Bet limit exceeded
400	invalid_argument	106	Win limit exceeded
400	invalid_argument	155	Action was already rolled back (tombstoned)
400	invalid_argument	403	Invalid or missing signature
500	internal	500	Internal server error

Insufficient funds error:

{
  "code": "invalid_argument",
  "msg": "Player has not enough funds to process an action.",
  "meta": {
    "api_code": "100",
    "api_message": "Player has not enough funds to process an action.",
    "balance": "5.00"
  }
}

Caution

When returning api_code 100, 105, or 106, you must include the current balance in the meta field.

---

curl Example

curl -X POST https://casino.example.com/wallet/betwin \
  -H "Content-Type: application/json" \
  -H "X-REQUEST-SIGN: abc123def456..." \
  -d '{
    "account_id": "player_123",
    "currency": "USD",
    "game_id": "dice",
    "round_id": "550e8400-e29b-41d4-a716-446655440000",
    "finished": true,
    "transactions": [
      { "id_provider": "tx_bet_001", "type": "bet", "amount": "10.00" },
      { "id_provider": "tx_win_001", "type": "win", "amount": "19.80" }
    ]
  }'

---

Behavioral Rules

• Atomicity: All transactions in the request must be processed atomically — either all succeed or none are applied
• Order: Transactions are processed in the order they appear in the array
• Idempotency: If an id_provider has already been processed, return the original response — do NOT process the transaction again
• Tombstone check: If an id_provider was already rolled back (tombstone exists), respond with HTTP 400 and api_code 155
• Amounts: Always positive, never zero
• finished flag: When true, the round is complete. No /finish call will be sent. When false or absent, more BetWin requests may follow, and a /finish call will close the round
• Multiple requests per round: In Candy Cash, a single round_id may span multiple BetWin requests with different id_provider values
• Win before bet: In rare timing scenarios, a win request may arrive before the corresponding bet. The win must still be processed

The finished Flag

The finished flag optimizes the round lifecycle by eliminating the separate /finish call:

stateDiagram-v2
    direction LR
    [*] --> Active: BetWin finished=false
    Active --> Active: BetWin finished=false
    Active --> [*]: BetWin finished=true
    Active --> [*]: /finish

• Simple games (dice, plinko): finished: true in the first (and only) BetWin request
• Crash: finished: true in the final BetWin (cashout or loss)
• Candy Cash: finished: true on the bet of a drop that wins nothing; otherwise finished: false on the bet and finished: true on the win when the drop lands

Sequence Diagram

sequenceDiagram
    participant Beexar
    participant Wallet as Operator Wallet

    Note over Beexar,Wallet: Player places bet (dice)
    Beexar->>Beexar: Calculate result
    Beexar->>Wallet: POST /betwin (bet + win, finished=true)
    alt Sufficient funds
        Wallet->>Wallet: Debit bet, credit win (atomic)
        Wallet-->>Beexar: 200 { balance, transactions }
        Note over Beexar: Show result to player
    else Insufficient funds
        Wallet-->>Beexar: 400 { api_code: "100", balance }
        Note over Beexar: Show error to player
    end