Partner API

Authentication

Every request must include the following headers. The signature is HMAC-SHA256 of METHOD\nPATH\nTIMESTAMP\nBODY using your api_secret. Timestamps older than 5 minutes are rejected.

• x-api-key — your partner API key
• x-signature — hex-encoded HMAC-SHA256
• x-timestamp — milliseconds since epoch

Idempotency-Key header

Send Idempotency-Key: <opaque-string> on POST requests to make retries safe.

• Format: any opaque string up to 200 chars. Generate one per logical operation (e.g. a UUID v4).
• Scope: unique per partner. Two partners may use the same key without collision.
• Canonical hashing: JSON object key order does not matter — {"a":1,"b":2} and {"b":2,"a":1} hash the same, so retries with reformatted bodies still replay correctly.

Replay behavior

POST /api/public/v1/place-bet

Place a bet for the current betting window.

Request body

{
  "external_user_id": "string (1..120)",
  "amount":            integer (1..1_000_000),
  "auto_cashout":      number | null  // optional, >= 1.01
}

Sample curl

TS=$(date +%s%3N)
BODY='{"external_user_id":"u-42","amount":250,"auto_cashout":2.5}'
SIG=$(printf "POST\n/api/public/v1/place-bet\n$TS\n$BODY" | \
       openssl dgst -sha256 -hmac "$API_SECRET" -hex | awk '{print $2}')

curl -X POST https://your-host/api/public/v1/place-bet \
  -H "content-type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-signature: $SIG" \
  -H "x-timestamp: $TS" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "$BODY"

Success (200)

{
  "bet_id": "uuid",
  "external_user_id": "u-42",
  "round_number": 1234,
  "amount": 250,
  "auto_cashout": 2.5
}

POST /api/public/v1/cashout

Cash out an active bet at the current multiplier.

Request body

{ "bet_id": "uuid" }

Sample curl

TS=$(date +%s%3N)
BODY='{"bet_id":"00000000-0000-0000-0000-000000000000"}'
SIG=$(printf "POST\n/api/public/v1/cashout\n$TS\n$BODY" | \
       openssl dgst -sha256 -hmac "$API_SECRET" -hex | awk '{print $2}')

curl -X POST https://your-host/api/public/v1/cashout \
  -H "content-type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-signature: $SIG" \
  -H "x-timestamp: $TS" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "$BODY"

Success (200)

{ "bet_id": "uuid", "payout": 537, "multiplier": 2.15 }

POST /api/public/v1/verify-signature

Reproduce and verify an outbound webhook signature using your endpoint secret. Use this if your integration receives a delivery you can't verify locally.

{
  "endpoint_secret": "your endpoint secret",
  "body":            "the raw JSON body we delivered",
  "signature":       "the x-coco-signature header we sent"
}