Credit

curl --request POST \
  --url https://wallet.luckystar.example/kinematic/credit \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Kinematic-Signature: <x-kinematic-signature>' \
  --header 'X-Kinematic-Timestamp: <x-kinematic-timestamp>' \
  --data '
{
  "id": "payout_091aaed882b1fb6a076c877ff78bb307",
  "player": "player_48213",
  "currency": "USD",
  "amount": "9900",
  "kind": "credit",
  "rounds": [
    "1eff8f3759107f88d5d63eaf980a9459"
  ],
  "settlements": [
    {
      "round": "1eff8f3759107f88d5d63eaf980a9459",
      "amount": "9900",
      "bet": {
        "type": "bet",
        "id": "1eff8f3759107f88d5d63eaf980a9459",
        "wager": {
          "stake": "5000",
          "bet": {
            "game": "dice",
            "target": 5000,
            "over": true
          }
        },
        "seedHash": "e28489e5d5c71d154a9def37a5369339f566e62267ac3222f28c0fc35ac7c0c8",
        "authorization": {
          "payload": {
            "format": "og.proof.v3",
            "kind": "authorization",
            "wallet": "[\"lucky-star\",\"player_48213\",\"USD\"]",
            "math": "dbc64afcb07c0d1c029c9cea07118f495f5a6e350a090ddf4ae6f804079ae132",
            "command": {
              "type": "bet",
              "id": "1eff8f3759107f88d5d63eaf980a9459",
              "wager": {
                "stake": "5000",
                "bet": {
                  "game": "dice",
                  "target": 5000,
                  "over": true
                }
              },
              "seedHash": "e28489e5d5c71d154a9def37a5369339f566e62267ac3222f28c0fc35ac7c0c8"
            }
          },
          "publicKey": "XfuCuSvxdGBmTC2mYSZ8WLJ0PiuBOD1_k3hs4YK02v0",
          "signature": "2_1mtd2ESweqUBgTojF56idR7mGnU-CA6mSSu--xrt9SV9qskbyyM8bQ1cSKfH-6Xwyp9rrR7iG6YYbG5YhRzA"
        }
      },
      "vrf": {
        "keyId": "62516d82119a9f4eb688da80f3f41548",
        "seed": "e9ca18e3c557e52e3e6b2feb062e7ab68a8a822114c4de4eabeb0ee1db79214c",
        "proof": "20864c99b79c5037ce8be2768b475757253c431f46d8165b73ed189c4831adec",
        "output": "bafc2f548ebacb0be2767181ac9824cd917b5c3f387c1edaf1ecb4bd8082fa4c"
      },
      "steps": []
    }
  ]
}
'

{
  "id": "payout_091aaed882b1fb6a076c877ff78bb307",
  "status": "applied",
  "balance": "102400",
  "revision": "42",
  "currency": "USD"
}

{
  "error": "credit_unverified",
  "reason": "proof"
}

curl --request POST \
  --url https://wallet.luckystar.example/kinematic/credit \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Kinematic-Signature: <x-kinematic-signature>' \
  --header 'X-Kinematic-Timestamp: <x-kinematic-timestamp>' \
  --data '
{
  "id": "payout_091aaed882b1fb6a076c877ff78bb307",
  "player": "player_48213",
  "currency": "USD",
  "amount": "9900",
  "kind": "credit",
  "rounds": [
    "1eff8f3759107f88d5d63eaf980a9459"
  ],
  "settlements": [
    {
      "round": "1eff8f3759107f88d5d63eaf980a9459",
      "amount": "9900",
      "bet": {
        "type": "bet",
        "id": "1eff8f3759107f88d5d63eaf980a9459",
        "wager": {
          "stake": "5000",
          "bet": {
            "game": "dice",
            "target": 5000,
            "over": true
          }
        },
        "seedHash": "e28489e5d5c71d154a9def37a5369339f566e62267ac3222f28c0fc35ac7c0c8",
        "authorization": {
          "payload": {
            "format": "og.proof.v3",
            "kind": "authorization",
            "wallet": "[\"lucky-star\",\"player_48213\",\"USD\"]",
            "math": "dbc64afcb07c0d1c029c9cea07118f495f5a6e350a090ddf4ae6f804079ae132",
            "command": {
              "type": "bet",
              "id": "1eff8f3759107f88d5d63eaf980a9459",
              "wager": {
                "stake": "5000",
                "bet": {
                  "game": "dice",
                  "target": 5000,
                  "over": true
                }
              },
              "seedHash": "e28489e5d5c71d154a9def37a5369339f566e62267ac3222f28c0fc35ac7c0c8"
            }
          },
          "publicKey": "XfuCuSvxdGBmTC2mYSZ8WLJ0PiuBOD1_k3hs4YK02v0",
          "signature": "2_1mtd2ESweqUBgTojF56idR7mGnU-CA6mSSu--xrt9SV9qskbyyM8bQ1cSKfH-6Xwyp9rrR7iG6YYbG5YhRzA"
        }
      },
      "vrf": {
        "keyId": "62516d82119a9f4eb688da80f3f41548",
        "seed": "e9ca18e3c557e52e3e6b2feb062e7ab68a8a822114c4de4eabeb0ee1db79214c",
        "proof": "20864c99b79c5037ce8be2768b475757253c431f46d8165b73ed189c4831adec",
        "output": "bafc2f548ebacb0be2767181ac9824cd917b5c3f387c1edaf1ecb4bd8082fa4c"
      },
      "steps": []
    }
  ]
}
'

{
  "id": "payout_091aaed882b1fb6a076c877ff78bb307",
  "status": "applied",
  "balance": "102400",
  "revision": "42",
  "currency": "USD"
}

{
  "error": "credit_unverified",
  "reason": "proof"
}

A credit can never be declined. Answer 200 with an applied receipt, or 409 with credit_unverified when your own check refuses it. See Credits.

Headers

Idempotency-Key

string

required

Equals the body's id.

Example:

"batch_3a787ce18225e69054f0bfbe34e909d7"

X-Kinematic-Timestamp

string

required

When the game server signed this attempt, in Unix milliseconds. Refuse a call whose timestamp is more than 60 seconds from your clock. A retry carries a fresh timestamp.

Pattern: ^[0-9]{13}$

Example:

"1793629805120"

X-Kinematic-Signature

string

required

Lowercase hex HMAC-SHA256, keyed with your WALLET_SECRET, over the exact UTF-8 bytes of timestamp + "." + body. Compare it in constant time before you parse the body, and refuse the call with a status other than 200 when it does not match.

Pattern: ^[0-9a-f]{64}$

Example:

"0315897c76ddcf819b7603a809501ff9ef1dd518187448e6d41597b6d4b7a021"

Body

application/json

string

required

The idempotency ID. payout_ for a payout, refund_ for a refund.

Pattern: ^(payout|refund)_[0-9a-f]{32}$

player

string

required

Your stable player ID, the sub of the session token.

Pattern: ^[A-Za-z0-9_-]{1,128}$

Example:

"player_48213"

currency

string

required

The currency code. Each currency is a separate account of the player.

Pattern: ^[A-Z0-9]{2,12}$

Example:

"USD"

amount

string

required

A canonical non-negative integer string in the currency's minor units. No decimals, signs or leading zeros.

Pattern: ^(0|[1-9][0-9]{0,18})$

Example:

"9900"

kind

string

required

Allowed value: "credit"

rounds

string[]

required

The rounds this credit settles. Each credit pays one round today.

Minimum array length: 1

A bet ID, chosen by the player's browser. The element uses 32 lowercase hex characters.

Pattern: ^[A-Za-z0-9_-]{16,80}$

settlements

object[]

required

One settlement per round of rounds, in the same order. Their amounts add up to amount.

Minimum array length: 1

Hide child attributes

settlements.round

string

required

A bet ID, chosen by the player's browser. The element uses 32 lowercase hex characters.

Pattern: ^[A-Za-z0-9_-]{16,80}$

Example:

"1eff8f3759107f88d5d63eaf980a9459"

settlements.amount

string

required

What the round pays, gross.

Pattern: ^(0|[1-9][0-9]{0,18})$

Example:

"9900"

settlements.bet

object

required

The player's signed bet command, exactly as the game server accepted it.

Hide child attributes

settlements.bet.type

string

required

Allowed value: "bet"

settlements.bet.id

string

required

A bet ID, chosen by the player's browser. The element uses 32 lowercase hex characters.

Pattern: ^[A-Za-z0-9_-]{16,80}$

Example:

"1eff8f3759107f88d5d63eaf980a9459"

settlements.bet.wager

object

required

Hide child attributes

settlements.bet.wager.stake

string

required

A canonical non-negative integer string in the currency's minor units. No decimals, signs or leading zeros.

Pattern: ^(0|[1-9][0-9]{0,18})$

Example:

"9900"

settlements.bet.wager.bet

object

required

The game and its settings, for example {"game":"dice","target":5000,"over":true}.

Hide child attributes

settlements.bet.wager.bet.game

enum<string>

required

Available options:

mines,

plinko,

dice,

limbo,

crash,

roulette,

keno,

baccarat,

wheel,

pump,

diamonds,

hilo,

blackjack

settlements.bet.seedHash

string

required

Lowercase hex SHA-256 of the domain og.seedhash.v1 and the bet's 32-byte seed.

Pattern: ^[0-9a-f]{64}$

settlements.bet.authorization

object

required

The player's Ed25519 signature over the command, under the device key the session allowed.

Hide child attributes

settlements.bet.authorization.payload

object

required

{format: "og.proof.v3", kind: "authorization", wallet, math, command}. wallet is the JSON text of [casino ID, player, currency]; math is the SHA-256 of the signed game math manifest.

settlements.bet.authorization.publicKey

string

required

The player's raw Ed25519 public key, unpadded base64url (43 characters).

settlements.bet.authorization.signature

string

required

The Ed25519 signature, unpadded base64url (86 characters).

settlements.vrf

object

A payout's proof under the VRF key the acceptance named.

Hide child attributes

settlements.vrf.keyId

string

required

The VRF key's ID, 32 lowercase hex characters.

Pattern: ^[0-9a-f]{32}$

settlements.vrf.seed

string

required

The seed the player's browser revealed, 64 lowercase hex characters.

Pattern: ^[0-9a-f]{64}$

settlements.vrf.proof

string

required

The VRF proof, a compressed BN254 G1 point of 32 bytes as 64 lowercase hex characters.

Pattern: ^[0-9a-f]{64}$

settlements.vrf.output

string

required

SHA-256 of og.vrf.v1/out and the proof, 64 lowercase hex characters.

Pattern: ^[0-9a-f]{64}$

settlements.steps

object[]

A payout's round steps (the player's actions and Crash's server ticks). Empty for instant games.

Hide child attributes

settlements.steps.action

object

required

The player's action, such as {"kind":"reveal","index":7}, or Crash's {"kind":"tick"}.

settlements.steps.elapsed

integer

required

Milliseconds since the round started, on the game server's clock.

settlements.manifest

object

A payout of a bet at a return to player other than 99%, the payload of the signed math manifest the bet was placed under. Its SHA-256 is the math the player's authorization signs, and catalog.formula_edge_bps is the round's house edge. Absent at 99%.

settlements.refund

enum<string>

A refund instead of a payout. abandoned: the bet was accepted and its seed never arrived within 24 hours. engine_failure: the engine could not evaluate the revealed round. key_retired: the debit applied only after the VRF key the bet's manifest names had retired, so the bet was never accepted. stake: a staked action the engine could not apply.

Available options:

abandoned,

engine_failure,

key_retired,

stake

settlements.action

object

The player's signed action whose stake a stake refund returns.

Hide child attributes

settlements.action.type

string

required

Allowed value: "action"

settlements.action.id

string

required

settlements.action.roundId

string

required

A bet ID, chosen by the player's browser. The element uses 32 lowercase hex characters.

Pattern: ^[A-Za-z0-9_-]{16,80}$

Example:

"1eff8f3759107f88d5d63eaf980a9459"

settlements.action.action

object

required

The action, for example {"kind":"double","hand":0,"stake":"2500"}.

settlements.action.authorization

object

required

The player's Ed25519 signature over the command, under the device key the session allowed.

Hide child attributes

settlements.action.authorization.payload

object

required

{format: "og.proof.v3", kind: "authorization", wallet, math, command}. wallet is the JSON text of [casino ID, player, currency]; math is the SHA-256 of the signed game math manifest.

settlements.action.authorization.publicKey

string

required

The player's raw Ed25519 public key, unpadded base64url (43 characters).

settlements.action.authorization.signature

string

required

The Ed25519 signature, unpadded base64url (86 characters).

settlements.action.steps

integer

Response

The credit is applied. Credits are never declined.

string

required

The request's id.

status

enum<string>

required

declined only for a debit the player cannot cover. Credits and balance reads are always applied.

Available options:

applied,

declined

balance

string

required

The player's balance after this operation, in minor units.

Pattern: ^(0|[1-9][0-9]{0,18})$

Example:

"9900"

revision

string

required

Your wallet-wide revision after this operation. It increases with every change to the account, including changes outside kinematic. Two different balances never share a revision.

Pattern: ^(0|[1-9][0-9]{0,18})$

Example:

"9900"

currency

string

required

The request's currency.

Pattern: ^[A-Z0-9]{2,12}$

Example:

"USD"

⌘I

Get started

Dashboard

Integrate

Concepts

Reference

Help

Headers

Body

Response