Introduction

We provide a REST web API which has a consistent request and response system to make it easier to interact with the blockchain and our services.

NOTICE

Please keep in mind that we cannot guarantee 100% uptime. Our API only interacts with the WAX blockchain and listens for new blocks and actions. If you want to be on the safe side, please setup an own node and fetch / send your data locally. Read our dapp documentation on github to learn more about the direct interaction with our WAX application.

SDKs

JavaScript

NPM

The NPM module is an abstraction of our API and makes it easier to interact with our service in a javascript application or in the browser.

npm install pinknetworkjs
Browser
<!-- socket.io >= 2.0.0 -->
<script type="text/javascript" src="socket.io.min.js" />
<!-- jquery >= 3.0.0 -->
<script type="text/javascript" src="jquery.min.js" />
<!-- api wrapper for browser -->
<script type="text/javascript" src="/node_modules/pinknetworkjs/pinknetwork.min.js" />
Documentation

REST API

Request

All endpoints are reachable under the following url without any authorization, so please be kind with our servers. A rate limiter will block your requests if you send too much from one IP address. The API is designed outsource all data polling tasks to a websocket endpoint so you will receive everything automated and don't need to spam the API.

GET|POST https://api.pink.network/<Namespace>/<Application>/v<Version>/<REST>
Namespace The namespace of the application
Application Currently available applications: bankroll, chat
Version If we make any major changes to a endpoint we will release a new version to ensure backwards compatibility
REST The REST API part of the application is appended to the request

Response

Every request returns a JSON object which has always the following format

{
    "success": true, // simple boolean whether the request was successful
    "data": null, // this field contains the result of your request
    "code": 200, // status code of the request (referred as JSON code later)
    "message": "" // error message if there was a problem
}

The HTTP Status code can be one of those:

200 Request was successful and no error has occurred. The JSON code will be 200 as well.
404 Endpoint was not found. The JSON code will be 404 as well.
500 The API request returned an error. Please check the JSON code for more detailed information

The JSON response code can be one of the following or 200 / 404 like mentioned above if there was no error related to a specific API request.

1xxx - User Errors
1000 BAD_INPUT The input to your request was malformed or otherwise bad.
1001 BAD_REQUEST Your request was missing some data, or it was otherwise bad.
1002 RATE_LIMIT_EXCEEDED You have been doing that action too frequently, and you must wait.
2xxx - Server Errors
2000 GENERIC_INTERNAL_ERROR The operation failed due to a problem on our end. Further details are unavailable.
2001 DATABASE_ERROR The operation failed due to a problem with our database. Please try again in a few moments.
2002 DATABASE_ERROR The operation failed due to a problem with our database. Please try again in a few moments.

Socket API

Connect

We use the library socket.io for the websocket connection which handles heartbeats and browser backwards compatibility. This makes it possible to create frontend only apps with our API that provide real-time data about the WAX blockchain and our services.

const io = require('socket.io-client');
const socket = io('https://api.pink.network/<SOCKET ENDPOINT>');

Events

The socket.io connection will fire events which are documented in the specific endpoint section. It is also possible to subscribe to actions which will be forwarded to your socket connection afterwards. There are a couple of standard events the server will send you if specific not API related incidents happen.

internal_server_error There was a critical error on our server and the connection may have broken, but was not necessarily closed
subscribe_limit There is a limit of 100 subscribed actions at the same time with the same connection

Bankroll

INFO

The complete bankroll API only listens to the WAX blockchain and waits for specific actions, so if uptime is extremely important to you, an own node will do everything we provide as well.

Our Bankroll accepts two different types of transactions. The first one is just a simple dice roll that will send one player a specific amount on a certain percentage which can be defined in the transaction memo. The second type is a "cycle roll" which will generate a result every x seconds and each user can bet on the same result in the time between. This can for example be used to provide a community dice where every player can bet on a specific range and after 30 seconds the same roll is shown to all of them.

You can interact with the bankroll from your dapp directly as well.

Read dapp Documentation

Create cycle roll

The cycle roll needs to be created before it can be used. Each roll needs to be ended by a transaction after the timer ran out which will be sent by our backend automatically

Sending Transactions

You have to send the WAX tokens to the pinkgambling account and specify the parameters in the transaction memo which is different for the two roll types the dapp provides. Keep in mind that these are not the only functions that the smart contract offers, but they are the ones most commonly used.

Roll
#bet [multiplier] [lower_bound] [upper_bound] [rake_recipient] [identifier] [client_seed]
lower_bound - upper_bound Your bet wins if lowerbound <= result <= upperbound. The result is an integer between 1 and 10000.
multiplier int; 1000 = 1x - If your bet wins, the dapp will send deposit * multiplier back. The multiplier indirectly specifies the rake that you will receive
rake_recipient The rake recipient is the WAX account which will receive the rake
identifier The identifier is a 64 bit hex encoded string which is used to track the exact roll result after it was processed on the blockchain.
client_seed The client seed is a 64 bit hex encoded string which is used to generate the randomness on the blockchain.
Cycle Roll
#join [roll_id] [multiplier] [lower_bound] [upper_bound] [client_seed]
roll_id The roll_id of the cycle roll the bet will join.
lower_bound - upper_bound Your bet wins if lowerbound <= result <= upperbound. The result is an integer between 1 and max_bet
multiplier int; 1000 = 1x - If your bet wins, the dapp will send deposit * multiplier back. The multiplier indirectly specifies the rake that you will receive
client_seed The client seed is a 64 bit hex encoded string which is used to generate the randomness on the blockchain.

Max bet size

The bankroll uses a custom bankroll management method to ensure security for bankroll investors while simultaneously offering big bet sizes for players. If you want to read more about how exactly it works, you can check out our Medium article covering this topic. If you are using our npm module, there already is an inbuilt function .getMaxBet() that gives you simple access to the maximum amount that can be bet on a certain outcome.
We have also published an example python script that you can use to get a better grasp of how the bankroll management functions.

Standard Objects

The bankroll API will return predefined standard objects for your queries

ROLL_RESULT
{
    "roll_id": int, // unique roll id which counts up
    "identifier": string // the identifier which was sent when the roll was created
    "max_roll": <int>, // roll result can be in range 0 - max_roll
    "bets": [
        <BET_OBJECT>, <BET_OBJECT>, ...
    ],
    "rake_recipient": string<WAX_NAME>, // the wax name who receives the rake
    "roll_result": <int>, // result of the roll
    "finished": <int> // the timestamp the result was generated (usually equal with created)
}
CYCLE_ROLL_RESULT
{
    "roll_id": int, // unique roll id which counts up
    "cycle_number": int, // cycle number which counts up and is unique in combination with the roll_id. Starts at 1
    "max_roll": <int>, // roll result can be in range 0 - max_roll
    "bets": [
        <BET_OBJECT>, <BET_OBJECT>, ...
    ],
    "rake_recipient": string<WAX_NAME>, // the wax name who receives the rake
    "roll_result": <int>, // result of the roll
    "finished": <int> // the timestamp the result was generated
}
CYCLE_ROLL_OBJECT
{
    "roll_id": int, // unique roll id which counts up
    "current_cycle_number": int, // the current cycle_number which counts up
    "last_cycle_time": int, // the timestamp when the last cycle was
    "cycle_time": int, // the time in seconds until the roll result is generated
    "max_roll": <int>, // roll result can be in range 0 - max_roll
    "rake_recipient": string<WAX_NAME>, // the wax name who will receive the rake
}
BET_OBJECT
{
    "bet_id": int, // unique in combination with the roll_id
    "bettor": string<WAX_NAME>, // the account which has sent the WAX
    "amount": string<WAX_NUMBER>, // amount which the user has sent
    "lower_bound": int, // the lower bound of the range the user deposited
    "upper_bound": int, // the upper bound of the range the user deposited
    "multiplier": string, // the multiplier the user will receive when he wins (example 2.001)
    "client_seed": string, // the seed the client provided in the transaction memo
    "joined": int, // when the bet was created
}
RANKING_USER_OBJECT
{
    "account": string<WAX_NAME>, // WAX account name
    "bet_count": int, // how many bets the user placed
    "wagered": string<WAX_NUMBER>, // the amount the user wagered
    "won": string<WAX_NUMBER>, // the amount the user won
    "profit": string<WAX_NUMBER>, // won - wagered = profit
}

Chat

The chat can be used to provide users a social feature with scatter login.

Standard Objects

The chat API will return predefined objects

CHAT_MESSAGE_OBJECT
{
    "info": <CHAT_ACCOUNT_OBJECT>, // unique roll id which counts up
    "message": string // chat message
}
CHAT_ACCOUNT_OBJECT
{
    "account": string, // WAX account name
    "avatar": string, // https://api.pink.network/<avatar> image of the user
}

REST Endpoints

wax/bankroll/v1/rolls

Gets the past non cycle rolls

HTTP Request
GET https://api.pink.network/wax/bankroll/v1/rolls
Parameter Type Default Description
limit int 50 Number of items per page to return. (maximum: 100)
page int 1 Page number to request
rake_recipient string Filter by the rake recipient of the roll
bettor string Filter by the bettor
Output
{
...
"data": [<ROLL_RESULT>, <ROLL_RESULT>, ...]
...
}

wax/bankroll/v1/rolls/[:roll_id]

Gets data about one specific non cycle roll

HTTP Request
GET https://api.pink.network/wax/bankroll/v1/rolls/[:roll_id]
Output
{
...
"data": <ROLL_RESULT>
...
}

wax/bankroll/v1/rolls/ranking

Returns a ranking statistics about the players of all rolls filtered by the rake_participant

HTTP Request
GET https://api.pink.network/wax/bankroll/v1/rolls/ranking
Parameter Type Default Description
rake_participant string<WAX_NAME> the rake recipient of the rolls which should be included in the ranking
limit int 50 Number of items per page to return. (maximum: 100)
page int 1 Page number to request
sort string wagered sort by this column. Available: bet_count, wagered, won, profit
time int 0 only for rolls which finished after the time timestamp
Output
{
...
"data": [<RANKING_USER_OBJECT>, <RANKING_USER_OBJECT>, ...]
...
}

wax/bankroll/v1/rolls/ranking/[:address]

Returns statistics about a specific player for all non cycle rolls filtered by th rake recipient

HTTP Request
GET https://api.pink.network/wax/bankroll/v1/rolls/ranking/[:account]
Parameter Type Default Description
rake_participant string<WAX_NAME> the rake recipient of the rolls which should be included in the ranking
time int 0 only for rolls which finished after the time timestamp
Output
{
...
"data": <RANKING_USER_OBJECT>
...
}

wax/bankroll/cycles/[:roll_id]

Gets the past roll results of a cycle roll

HTTP Request
GET https://api.pink.network/wax/bankroll/v1/cycles/[:roll_id]
Parameter Type Default Description
limit int 50 Number of items per page to return. (maximum: 100)
page int 1 Page number to request
bettor string Filter by the bettor
Output
{
...
"data": [<CYCLE_ROLL_RESULT>, <CYCLE_ROLL_RESULT>, ...]
...
}

wax/bankroll/v1/cycles/[:roll_id]/[:cycle_number]

Gets data about one specific cycle roll

HTTP Request
GET https://api.pink.network/wax/bankroll/v1/cycles/[:roll_id]/[:cycle_number]
Output
{
...
"data": <CYCLE_ROLL_RESULT>
...
}

wax/bankroll/v1/cycles/info/[:roll_id]

Get generic data about one specific cycle roll and the current state it is in

HTTP Request
GET https://api.pink.network/wax/bankroll/v1/cycles/info/[:roll_id]
Output
{
...
"data": <CYCLE_ROLL_OBJECT>
...
}

wax/bankroll/v1/cycles/ranking/[:roll_id]

Returns a ranking statistics about the players of a specific cycle

HTTP Request
GET https://api.pink.network/wax/bankroll/v1/cycles/ranking/[:roll_id]
Parameter Type Default Description
limit int 50 Number of items per page to return. (maximum: 100)
page int 1 Page number to request
sort string wagered sort by this column. Available: bet_count, wagered, won, profit
time int 0 only for rolls which finished after the time timestamp
Output
{
...
"data": [<RANKING_USER_OBJECT>, <RANKING_USER_OBJECT>, ...]
...
}

wax/bankroll/v1/cycles/ranking/[:roll_id]/[:account]

Returns statistics about a specific player for a cycle roll

HTTP Request
GET https://api.pink.network/wax/bankroll/v1/cycles/ranking/[:roll_id]/[:account]
Parameter Type Default Description
time int 0 only for rolls which finished after the time timestamp
Output
{
...
"data": <RANKING_USER_OBJECT>
...
}

Socket Endpoints

wax/bankroll/v1/rolls

Creates a connection to listen and subscribe to non cycle rolls

Connection
const socket = io("https://api.pink.network/wax/bankroll/v1/rolls", {
    "path": "/wax/bankroll/socket"
});
Request Events
Event Name Data Type Description
subscribe_rake_recipient string<WAX_NAME> Subscribe to all rolls which send the rake to a specific account
subscribe_identifier 64 bit hex encoded string Subscribe to a rolls with a specific identifier
subscribe_all Subscribe to every roll which is handled by our smart contract. This will delete all other subscribed events and will be disabled as soon as you fire another subscribe event
Response Events
Event Name Data Type Description
bankroll_update string<WAX_NUMBER> This event is fired whenever the bankroll changes (needed to calculate the max bet)
new_roll <ROLL_RESULT> A roll has been completed and the result is available now

wax/bankroll/v1/cycles/[:roll_id]

Creates a connection to listen for live bets and roll result for a specific roll_id

Connection
const socket = io("https://api.pink.network/wax/bankroll/v1/cycles/:roll_id", {
    "path": "/wax/bankroll/socket"
});
Response Events
Event Name Data Type Description
bankroll_update string<WAX_NUMBER> The bankroll has changed (needed to calculate the max bet)
new_roll <ROLL_RESULT> A new roll has been completed and the result is available
new_bet <BET_OBJECT> A new transaction came in

wax/chat/v1/rooms/[:room_name]

Creates a connection to listens for new chat messages in the room room_name

Connection
const socket = io("https://api.pink.network/wax/chat/v1/rooms/:room_name", {
    "path": "/wax/chat/socket"
});
Request Events
Event Name Data Type Description
login {"sig": string, "pub": string, "account": string, "avatar": string} Using scatter authenticate signature of the word "login" and the nonce which is sent with the authenticate event to login the user to the chat service
logout logout the user
chat_message string sends the message as the authenticated user to the room chat
Response Events
Event Name Data Type Description
error_message string If any error occurs or invalid data is entered, this event is fired
authenticate string When the connection is established a nonce is sent which is needed to login
chat_load Array of <CHAT_MESSAGE_OBJECT> Overwrites all current messages to this array. Usually sent on page load
chat_message <CHAT_MESSAGE_OBJECT> New chat message came in
login <CHAT_ACCOUNT_OBJECT> Authentication was successful
logout <BET_OBJECT> Logout was successful