API reference

Place a coinflip bet

POST/v2/coinflips/{id}/bets

Place one bet at an open coinflip table; answers with the table as it stands after the flip.

Authentication: Required: the order’s owner session in X-Session-ID.

#Parameters

Name	In	Type	Required	Description
`id`	path	string (pattern `^[A-Za-z0-9:_-]{1,128}$`)	Yes	Public order identifier. Not a credential: every read still requires the owner session or the destination proof.

#Request body

round · integer · required — The open round this bet answers. A stale round is rejected with 409, never applied later.
side · "cow" · "milk" · required — Which band wins. Selects the winning range only; never feeds the HMAC.
stakeAtomic · string (atomic integer) · required — The bet, in the asset's smallest unit. Proposed, not binding — a refused bet advances the round and names why.
clientSeed · string (max 64, pattern ^[\x20-\x7E]*$) or null — Your half of the provably-fair seed; SHA256(serverSeed) was committed before you chose it.

#Response

200 returns an object with:

verdict · "settled" · "refused" · "closing" · "closed" · "reopened" · required
order · object · required
- orderId · string · required
- product · "coinflip" · required
- status · "awaiting_deposit" · "awaiting_xmr1" · "awaiting_trx1" · "awaiting_zec1" · "processing" · "completed" · "failed" · "expired" · "refunded" · "needs_review" · required
- asset · "xmr" · "btc" · "sol" · "eth" · "zec" · required — Coinflip-table pool asset key, never a display symbol.
- direction · "deposit" · "withdraw" — deposit mints the wrapped asset from a native-coin deposit; withdraw returns the native coin against the wrapped asset.
- chainId · integer or null · required — Non-negative integer chain identifier.
- toAddress · string or null · required
- depositAddress · string · required
- createdAt · string or null · required
- updatedAt · string or null · required
- fromChainId · integer or null — Non-negative integer chain identifier.
- depositChainId · integer or null — Non-negative integer chain identifier.
- fromToken · string
- depositToken · string
- fromTokenSymbol · string
- depositTokenSymbol · string
- fromTokenDecimals · integer (0–36)
- depositTokenDecimals · integer (0–36)
- fromAmount · string
- depositAmount · string
- toChainId · integer or null — Non-negative integer chain identifier.
- toToken · string
- toTokenSymbol · string
- toTokenDecimals · integer (0–36)
- expectedOutput · string
- depositTxHash · string or null
- receivingTxHash · string or null
- sessionId · string or null
- refundAddress · string or null
- refundRequestedAt · string or null
- expiresAt · string
- amountUsd · number
- bonusStage · "none" · "coinflip"
- coinflipRequested · boolean
- fundingProvider · "privy" or null
- integratorFeeUsd · number or null
- customerState · one of the variants below · required — Authoritative customer display/action state. Clients must not infer lifecycle from status or resource presence.
  - Nested fields: see openapi.json.
- confirmations · number
- requiredConfirmations · number
- depositObserved · boolean
- errorMessage · string or null · required
- actualOutput · string — What the customer received, in atomic units of deliveredToken when present, otherwise of toToken. Only on completed orders.
- deliveredToken · object — Present only when the order completed in a different asset than toToken; actualOutput is then denominated in this token.
  - Nested fields: see openapi.json.
- coinflipLost · boolean · required
- hasReview · boolean · required
- refundRecovery · object or null
  - Nested fields: see openapi.json.
- rewards · object
  - Nested fields: see openapi.json.
- maxPayoutUsd · number
- destination · string
- depositAddressForms · array of object
  - Nested fields: see openapi.json.
- coinflip · object or null
  - Nested fields: see openapi.json.

Errors use the standard error envelope: branch on code, never on the message.

#Example

curl

curl -X POST 'https://api-beta.wagyu.xyz/v2/coinflips/<orderId>/bets' \
  -H 'x-session-id: <sessionId>' \
  -H 'content-type: application/json' \
  -d '{
    "round": 1,
    "side": "cow",
    "stakeAtomic": "<atomic-amount>"
  }'

JavaScript

const res = await fetch('https://api-beta.wagyu.xyz/v2/coinflips/<orderId>/bets', {
  method: 'POST',
  headers: {"content-type":"application/json","x-session-id":"<sessionId>"},
  body: JSON.stringify({
    "round": 1,
    "side": "cow",
    "stakeAtomic": "<atomic-amount>"
  }),
});
const data = await res.json();

Python

import requests

res = requests.post('https://api-beta.wagyu.xyz/v2/coinflips/<orderId>/bets', headers={"x-session-id":"<sessionId>"}, json={
        "round": 1,
        "side": "cow",
        "stakeAtomic": "<atomic-amount>"
    }, timeout=30)
data = res.json()

No response is captured for this route: calling it creates or changes a real order. The response fields above come from the live contract.