MegaDice API Documentation

Bitcoin Dice Game Server v0.9 Public Beta.

The MegaDice API makes it possible for anyone to run their own bot and place bets on the MD session based game, automatically withdraw funds in order to control their bankroll, get access to global statistics, verify that the entire site's rolls have been handled in a fair way, or even write their own game client on any kind of platform. Balances, bet and win amounts are denominated in satoshis (one 100 000 000th of a bitcoin), with the exception of withdrawal amounts that are denominated in a regular Bitcoin amount. If you add a callback value, the response will be padded in a javascript compatible statement. See the Global Statistics API call for an example.

Table of Contents

Preferable changes to be made:
*make "prize": return float instead of string with "x" prefix.
*make probability be 0-1 range float instead of string of percent.

Global Statistics API Calls

The global statistics of the games are available as JSON encoded data and are self explanatory. Anyone that wants to post live data from the games can use the data to display whatever key data they want.
https://session.megadice.com/globalstats/
A typical response looks like this:
{
    "offChainGame": {
        "totalRounds": 822842,
        "totalBetsInSatoshis": 618097504509,
        "totalWinsInSatoshis": 611602960617,
        "totalRoundsToday": 6754,
        "totalBetsTodayInSatoshis": 594449746,
        "totalWinsTodayInSatoshis": 575054844,
        "biggestWinInSatoshis": 2180680279
    },
    "blockChainGame": {
        "totalRounds": 6334205,
        "totalBetsInSatoshis": 439347877263746,
        "totalWinsInSatoshis": 430798731932806,
        "totalFeePaidInSatoshis": 558424037500,
        "totalRoundsToday": 30,
        "totalBetsTodayInSatoshis": 721474439,
        "totalWinsTodayInSatoshis": 219703660,
        "totalFeePaidTodayInSatoshis": 330000,
        "totalRounds24H": 145,
        "totalBets24HInSatoshis": 865940119,
        "totalWins24HInSatoshis": 1352723206,
        "totalFeePaid24HInSatoshis": 1810000,
        "biggestWinInSatoshis": 192000000000
    },
    "gamesCombined": {
        "totalRounds": 7157047,
        "totalBetsInSatoshis": 439965974768255,
        "totalWinsInSatoshis": 431410334893423,
        "totalRoundsToday": 6784,
        "totalBetsTodayInSatoshis": 1315924185,
        "totalWinsTodayInSatoshis": 794758504,
        "biggestWinInSatoshis": 192000000000
    },
    "currentLeaderBoardPrizes": {
        "mostWonPrizeInSatoshis": 5000000,
        "mostProfitPrizeInSatoshis": 10000000,
        "unlikliestWinPrizeInSatoshis": 10000000,
        "longesWinStreakPrizeInSatoshis": 10000000,
        "unlikliestWinStreakPrizeInSatoshis": 5000000
    },
    "meta": {
        "maxProfitInSatoshis": 485753429,
        "serverTime": "2014-12-07 04:56:19",
        "queryTimeInSeconds": 0.0093,
        "fromCache": "no"
    }
}
A callback variable can be passed in order get a response that is a function call that can easily be accessed cross-domain.
https://session.megadice.com/globalstats/?callback=jsonpCallback
The response then looks like this:
jsonpCallback({
    "offChainGame": {
        "totalRounds": 822851,
        "totalBetsInSatoshis": 618097669509,
        "totalWinsInSatoshis": 611603235297,
        "totalRoundsToday": 6763,
        "totalBetsTodayInSatoshis": 594614746,
        "totalWinsTodayInSatoshis": 575329524,
        "biggestWinInSatoshis": 2180680279
    },
    "blockChainGame": {
        "totalRounds": 6334206,
        "totalBetsInSatoshis": 439347878263746,
        "totalWinsInSatoshis": 430798731938266,
        "totalFeePaidInSatoshis": 558424047500,
        "totalRoundsToday": 31,
        "totalBetsTodayInSatoshis": 722474439,
        "totalWinsTodayInSatoshis": 219709120,
        "totalFeePaidTodayInSatoshis": 340000,
        "totalRounds24H": 146,
        "totalBets24HInSatoshis": 865945579,
        "totalWins24HInSatoshis": 1353723206,
        "totalFeePaid24HInSatoshis": 1820000,
        "biggestWinInSatoshis": 192000000000
    },
    "gamesCombined": {
        "totalRounds": 7157057,
        "totalBetsInSatoshis": 439965975933255,
        "totalWinsInSatoshis": 431410335173563,
        "totalRoundsToday": 6794,
        "totalBetsTodayInSatoshis": 1317089185,
        "totalWinsTodayInSatoshis": 795038644,
        "biggestWinInSatoshis": 192000000000
    },
    "currentLeaderBoardPrizes": {
        "mostWonPrizeInSatoshis": 5000000,
        "mostProfitPrizeInSatoshis": 10000000,
        "unlikliestWinPrizeInSatoshis": 10000000,
        "longesWinStreakPrizeInSatoshis": 10000000,
        "unlikliestWinStreakPrizeInSatoshis": 5000000
    },
    "meta": {
        "maxProfitInSatoshis": 485753429,
        "serverTime": "2014-12-07 04:56:53",
        "queryTimeInSeconds": 0.0085,
        "fromCache": "no"
    }
});
The callback variable can be used on any API calls.
Back to Table of Contents

Leader Board Winners History

This call will return leader board history:
https://session.megadice.com/globalstats/leaderBoardWinners/
Typical response:
{
     "2014-11-06": {
        "mostWonPrizeInSatoshis": 20000000,
        "mostWonWinnerHash": "73ffa73301d1df899c6c4a8d7ba55219",
        "mostWonNick": "Throne",
        "mostProfitPrizeInSatoshis": 20000000,
        "mostProfitWinnerHash": "73ffa73301d1df899c6c4a8d7ba55219",
        "mostProfitNick": "Throne",
        "unlikliestWinPrizeInSatoshis": 20000000,
        "unlikliestWinWinnerHash": "7ef585ba27ad8eea00d509622570e2d3",
        "unlikliestWinNick": "leen",
        "longesWinStreakPrizeInSatoshis": 20000000,
        "longestWinStreakWinnerHash": "7ef585ba27ad8eea00d509622570e2d3",
        "longestWinNick": "leen",
        "unlikliestWinStreakPrizeInSatoshis": 10000000,
        "unlikliestWinStreakWinnerHash": "a3b6e4c655b06a286c7c18ae111eb145",
        "unlikliestWinStreakNick": "RND03329"
    },
    "2014-11-07": {
        "mostWonPrizeInSatoshis": 20000000,
        "mostWonWinnerHash": "73ffa73301d1df899c6c4a8d7ba55219",
        "mostWonNick": "Throne",
        "mostProfitPrizeInSatoshis": 20000000,
        "mostProfitWinnerHash": "7ef585ba27ad8eea00d509622570e2d3",
        "mostProfitNick": "leen",
        "unlikliestWinPrizeInSatoshis": 20000000,
        "unlikliestWinWinnerHash": "7ef585ba27ad8eea00d509622570e2d3",
        "unlikliestWinNick": "leen",
        "longesWinStreakPrizeInSatoshis": 20000000,
        "longestWinStreakWinnerHash": "7ef585ba27ad8eea00d509622570e2d3",
        "longestWinNick": "leen",
        "unlikliestWinStreakPrizeInSatoshis": 20000000,
        "unlikliestWinStreakWinnerHash": "e939a655ef57d9fd4f9642cfd487daf0",
        "unlikliestWinStreakNick": "justme"
    }
}
Back to Table of Contents

Stats For a Single Player

Request from the user API:
https://megadice.com/user/?userHash=b67fe506bcd022589f10cdc8ce4b1a22&format=json
A typical response, shortened by removing most of the bet history:
{
  "hash": "b67fe506bcd022589f10cdc8ce4b1a22",
  "nick": "User06294",
  "version": "Beta",
  "luck": 0.80150297392751,
  "rounds": 721,
  "winsInSatoshis": 11427413,
  "leastLikelyWin": 0,
  "leastLikelyWinStreak": 0.00046989090299368,
  "taggedToAffiliate": 0,
  "added": "2014-09-01 17:55:50",
  "lastSeen": "2014-09-07 05:46:56",
  "luckToday": 1.1428571428571,
  "roundsToday": 7,
  "winsInSatoshisToday": 784800,
  "leastLikelyWinToday": 0.5,
  "leastLikelyWinStreakToday": 0.125,
  "fiftyMostRecentRounds": [
    {
      "game": "session",
      "betID": 37740,
      "betTX": null,
      "playerNick": "User06294",
      "playerHash": "b67fe506bcd022589f10cdc8ce4b1a22",
      "betType": "lessthan",
      "target": 32768,
      "probability": "50%",
      "streak": 1,
      "streakBetSize": 1000,
      "streakWinSize": 0,
      "streakProfit": -1000,
      "streakProbability": 0.5,
      "roll": 37989,
      "rollInPercent": "57.97",
      "time": "2014-09-07 05:46:56",
      "result": "loss",
      "betInSatoshis": 1000,
      "prize": "x1.962",
      "prizeInSatoshis": 1962,
      "payoutInSatoshis": 0,
      "payoutTX": null,
      "profitInSatoshis": -1000
    },
    {
      "game": "session",
      "betID": 37658,
      "betTX": null,
      "playerNick": "User06294",
      "playerHash": "b67fe506bcd022589f10cdc8ce4b1a22",
      "betType": "lessthan",
      "target": 32768,
      "probability": "50%",
      "streak": 2,
      "streakBetSize": 2000,
      "streakWinSize": 0,
      "streakProfit": -2000,
      "streakProbability": 0.25,
      "roll": 42773,
      "rollInPercent": "65.27",
      "time": "2014-09-04 18:55:16",
      "result": "loss",
      "betInSatoshis": 1000,
      "prize": "x1.962",
      "prizeInSatoshis": 1962,
      "payoutInSatoshis": 0,
      "payoutTX": null,
      "profitInSatoshis": -1000
    }
  ],
  "queryTimeInSeconds": 0.1076
}
Back to Table of Contents

Data For a Single Roll

Request from the user API:
https://megadice.com/roll/?roll=3006&format=json
A typical response:
{
    "serverRoll": 33372,
    "serverSalt": "bad1634019b21d8e0301b9ce7ef823b2bd292ffd790fef78c4d426539e80eb3b",
    "serverHash": "042d01ad413bb95d1c68f78cd68a6ff046fb4b53d75570c10950a4e5366ff0dd",
    "clientRoll": 94,
    "resultingRoll": 33466,
    "created": "2014-09-17 07:25:16",
    "streakId": "2991",
    "bet": {
        "game": "session",
        "betID": 3006,
        "betTX": null,
        "playerNick": "Lolercoaster",
        "playerHash": "b67fe506bcd022589f10cdc8ce4b1a22",
        "betType": "lessthan",
        "target": "3276",
        "probability": 5,
        "streak": 16,
        "streakBetInSatoshis": 1600000,
        "streakWinInSatoshis": 0,
        "streakProbability": 0.44021717067449,
        "roll": 33466,
        "rollInPercent": 51.07,
        "time": "2014-09-24 00:29:10",
        "result": "loss",
        "betInSatoshis": "100000",
        "prize": 1962479,
        "prizeInSatoshis": "1962479",
        "payoutInSatoshis": 0,
        "payoutTX": null,
        "profitInSatoshis": -100000
    },
    "queryTimeInSeconds": 0.0066
}
Back to Table of Contents

Recent Rolls

This returns the 30 last bets from both the session based and block chain based games.
https://session.megadice.com/globalstats/recentrolls/
The recent rolls call shows any recent roll as default but can also filter bets by probability, win amount or bet amount. For example only bets above a certain number of satoshis are requested like this:
https://session.megadice.com/globalstats/recentrolls/?betInSatoshis=40000000000
Only your own rolls can be requested by including your secret as get data in the URL. Please note that this means that only session games will be returned.
https://session.megadice.com/globalstats/recentrolls/?secret=YourSecretAsItAppearsInURL
Only bets that had below a certain probability to happen can be shown by adding the probabilityBelow get data. The response returns both block chain and session game rounds:
https://session.megadice.com/globalstats/recentrolls/?probabilityBelow=30

Big Wins

Win amount by biggest win: (This is what's seen under the tab BIG WINS, default option ALL)
https://session.megadice.com/globalstats/recentrolls/?sortBy=playerWin
You can also specify a time period, one of the following: (This is what's see under the tab BIG WINS, options TODAY, LAST 24H, LAST 7 DAYS, LAST 30 DAYS)
https://session.megadice.com/globalstats/recentrolls/?sortBy=playerWin&period=today
https://session.megadice.com/globalstats/recentrolls/?sortBy=playerWin&period=last24h
https://session.megadice.com/globalstats/recentrolls/?sortBy=playerWin&period=last7d
https://session.megadice.com/globalstats/recentrolls/?sortBy=playerWin&period=month

Rare Wins

Returned bets can also be sorted by unlikliness of the win: (This is what's seen under the tab RARE WINS, options TODAY, LAST 24H, LAST 7 DAYS, LAST 30 DAYS)
https://session.megadice.com/globalstats/recentrolls/?sortBy=unlikliness
https://session.megadice.com/globalstats/recentrolls/?sortBy=unlikliness&period=today
https://session.megadice.com/globalstats/recentrolls/?sortBy=unlikliness&period=last24h
https://session.megadice.com/globalstats/recentrolls/?sortBy=unlikliness&period=last7d
https://session.megadice.com/globalstats/recentrolls/?sortBy=unlikliness&period=month

Winning Streaks

It's possible to sort by streak data by specifying sortBy as see below: (This is what's seen under the tab Winning Streaks, options MOST WON, MOST PROFIT, LONGEST, UNLIKLIEST)
https://session.megadice.com/globalstats/recentrolls/?sortBy=streakWinSize
https://session.megadice.com/globalstats/recentrolls/?sortBy=streakProfit
https://session.megadice.com/globalstats/recentrolls/?sortBy=streakLongest
https://session.megadice.com/globalstats/recentrolls/?sortBy=streakWinUnlikliness

Losing Streaks

Same goes for the losing streaks tab: (MOST BET, LONGEST, UNLIKLIEST)
https://session.megadice.com/globalstats/recentrolls/?sortBy=streakBetSize
https://session.megadice.com/globalstats/recentrolls/?sortBy=streakLongestLoss
https://session.megadice.com/globalstats/recentrolls/?sortBy=streakLoseUnlikliness

Today's Leader Board Standings

If you want to make your bot hunt for Leader Board prizes, it'll be useful to get its current position directly via the API.
https://session.megadice.com/globalstats/recentrolls/?sortBy=playerWin&leaderBoard=yes&period=today
https://session.megadice.com/globalstats/recentrolls/?sortBy=profitInSatoshis&leaderBoard=yes&period=today
https://session.megadice.com/globalstats/recentrolls/?sortBy=unlikliness&leaderBoard=yes&period=today
https://session.megadice.com/globalstats/recentrolls/?sortBy=streakLongest&leaderBoard=yes&period=today
https://session.megadice.com/globalstats/recentrolls/?sortBy=streakWinUnlikliness&leaderBoard=yes&period=today
Back to Table of Contents

Get a user's alias

If you have the user's hash, you can request his or hers alias:
https://session.megadice.com/userapi/getUserAlias/?hash=b67fe506bcd022589f10cdc8ce4b1a22
The responses looks like a minimal JSON string.
"Lolercoaster"
Back to Table of Contents

Retreive your deposit address

You can receive Bitcoin deposit address with the following API call:
https://session.megadice.com/userapi/useraddress/?secret=d64e40e7f88c85d07f172d99e805d345
The responses can look like this:
{
    "nick": "Asicer06413",
    "depositaddress": "182FWgcS3occpfb2Sua8yGYQLU6XCQ2DeK",
    "queryTimeInSeconds": 0.0122
}
As you can see, the response includes the account's current alias and its Bitcoin deposit address.
Back to Table of Contents

Retreive Your Balance

At any time, you can check your balance.
https://session.megadice.com/userapi/userbalance/?secret=YourSecretAsItAppearsInURL
Typical response:
{
    "nick": "ID 09453",
    "balanceInSatoshis": 727310,
    "unconfirmedBalanceInsSatoshis": 0,
    "hash": "eefda28857a97b09f9d570633d1df8dc",
    "maxProfitInSatoshis": 50000000,
    "queryTimeInSeconds": 0.0174
}
Or if the provided secret is invalid, the page simply outputs:
Invalid Account
Back to Table of Contents

Update User Nym (Alias)

You can change your user name with a simple call that looks like this:
https://session.megadice.com/userapi/updateuser/?secret=YourSecretAsItAppearsInURL&nick=Testuser
The responses can look like this:
{
    "result": "success",
    "message": "User Name updated to: Testuser."
}
{
    "result": "failed",
    "message": "Invalid User"
}
Back to Table of Contents

Get Your Affiliate Data

You can get the affiliate earnings and info about your referred players with this call:
https://session.megadice.com/userapi/affiliateInfo/?secret=
The responses can look like this:
{
    "yourAffiliateURL": "https:\/\/www.megadice.com\/?a=34526345",
    "yourAffiliateDomains": null,
    "numDepositingPlayersReferred": 1,
    "DepositingPlayersReferred": [
        {
            "playerNick": "Cyberpunk57348",
            "hash": "b1651e429beb26d6bc4c12eb8f216847",
            "expectedValueInSatoshis": 6128
        }
    ],
    "numNonDepositingPlayersReferred": 2,
    "nonDepositingPlayersReferred": [
        {
            "playerNick": "Genius03642",
            "hash": "0e96c89884aa7fbdd1f0437591710aff"
        },
        {
            "playerNick": "Nerd01673",
            "hash": "0beb95b8d7edc88521a0b1e85aba9cf2"
        }
    ],
    "expectedValueOfDepositorsInSatoshis": 6128,
    "yourCommissionOfEdgeInPercent": 10,
    "yourEarnings": 1541,
    "queryTimeInSeconds": 0.0189
}
Back to Table of Contents

Initiate Game Round

In order to make a roll, the client needs to have a game round.
https://session.megadice.com/userapi/startround.php?secret=YourSecretAsItAppearsInURL
A typical response looks like this:
{
    "id": 13639,
    "hash": "516c951de200cb04d18a49cc6c965cb7795b55f4759bf2ba2fe7c6444232bae9",
    "welcomeMessage": "Welcome to MegaDice!",
    "maxProfitInSatoshis": 50000000
}
The hash can be used to prove that the outcome was a result of a provably fair roll.
Back to Table of Contents

Place a Bet

In order to place a bet, the following URL is called:
https://session.megadice.com/userapi/placebet.php
The following get data needs to be supplied as get data: Example:
https://session.megadice.com/userapi/placebet.php?secret=YourSecretAsItAppearsInURL&betInSatoshis=100&id=10368&serverHash=7a911afab20b1394bf01251df77dbd01c355d3bf6febb68aefeb6956255ed5a0&clientRoll=3245&belowRollToWin=32000
A successful response looks like this:
{
    "newLuck": 0.018068683707609,
    "message": "LOSS! 52.23\/1.68% -0.00001000",
    "serverRoll": 34219,
    "serverSalt": "6d2a45e646c2058131ae56643ebb15ad342cc53963263b380f114032f47e2c74",
    "serverHash": "4f97fdc3fc7314536026a97a17412fde4b9b4a12c6a1a15ae1d36cf2bdbab0d7",
    "clientRoll": 11,
    "resultingRoll": 34230,
    "userBalanceInSatoshis": 286220,
    "nextRound": {
        "id": 20191,
        "hash": "a6dea30b474bf6496d7f7fdbe778d7bfa4d5e63007a52dcdf9e790fe198c58e3",
        "welcomeMessage": "Welcome to MegaDice!",
        "maxProfitInSatoshis": 50000000
    },
    "status": "success",
    "bet": {
        "game": "session",
        "betID": 20190,
        "betTX": null,
        "playerNick": "Testuser",
        "playerHash": "eefda28857a97b09f9d570633d1df8dc",
        "betType": "lessthan",
        "target": 1100,
        "probability": "1.68",
        "streak": 1,
        "streakMessage": "98.32%",
        "roll": 34230,
        "rollInPercent": "52.23",
        "time": "2014-08-14 22:20:18",
        "result": "loss",
        "betInSatoshis": 1000,
        "prize": "x58.446",
        "prizeInSatoshis": 58446,
        "payoutInSatoshis": 0,
        "payoutTX": null,
        "profitInSatoshis": -1000
    },
    "queryTimeInSeconds": 0.4121
}
A failed response looks like this:
{
    "nextround": {
        "id": "31799",
        "serverRoll": "6424",
        "serverHash": "3c90f6f8e5ceb3583c40b7c1583090d0214c730675f1e0db4b27485bab7fe3f8"
    },
    "message": "Insufficient balance, deposit more!",
    "status": "fail",
    "failcode": 19,
    "verbose": "Bet is bigger than balance",
    "processLog": null
}
The following fail codes are available:
  1. secret strlen has to be bigger than 0
  2. belowRollToWin strlen has to be bigger than 0
  3. belowRollToWin has to be numeric
  4. belowRollToWin can't be below 1
  5. belowRollToWin needs to be an integer
  6. belowRollToWin needs to less than 65536
  7. betInSatoshis strlen 1 or more
  8. betInSatoshis needs to be numeric
  9. betInSatoshis needs to be an integer
  10. betInSatoshis is >= $MinBetInSatoshis
  11. Check that bet ID is provided
  12. Check that bet ServerHash is provided
  13. Check that clientRoll is provided
  14. Max allowed chars in clientRoll is 10
  15. provided clientRoll has to be numeric
  16. clientRoll needs to be an integer
  17. The potential profit of your bet is too big
  18. Provided Round ID Not Available
  19. Bet is bigger than balance
Back to Table of Contents

Withdraw Funds

A player's confirmed balance can be withdrawn at any time:
https://session.megadice.com/userapi/withdraw/?secret=YourSecretAsItAppearsInURL&address=YourBitcoinAddress&amount=0.5
Example of successful withdrawal:
{
    "amountWithdrawn": 0.0009,
    "transactionId": "16e6f5d313e26102e7ef534cf891cd15d410b1cd292e3c6cfc87ca69726d5d1c",
    "status": 7,
    "message": "Withdrawal successful. Bitcoins sent: 0.0009. The transaction id is: 16e6f5d313e26102e7ef534cf891cd15d410b1cd292e3c6cfc87ca69726d5d1c",
    "confirmationsRequired": 1,
    "balance": 0.00410557
}
Example of unsuccessful withdrawal:
{
    "amountWithdrawn": 0,
    "transactionId": "none",
    "status": 4,
    "message": "Insufficient balance. The maximum withdrawal you can do is 0.00588157 bitcoins.",
    "balance": 0.00588157
}
The following response codes are available: Back to Table of Contents

Game Mechanics

The possible numbers that can be rolled is 0-65535, meaning that there are 65535 + 1 = 65536 possible outcomes. The bar changes the "roll under number to win", and then % to win and payout are calculated from this. There's also another limiter to the minimum number the slider can have; There's a max profit allowed and this is the maxProfit variable that is returned with the userbalance calls and this number is also returned with each response from bets placed.

Back to Table of Contents

Bitcoin Casino How to Play Affiliates FAQ API Stats Provably Fair Terms Leader Boards Responsible Gaming