Overview

The MMOCircles Gem API is a set of REST endpoints designed to facilitate any game in implementing cash incentivised PvP system. This API have a variety of uses, including gambling, skill-based PvP, rewards system, etc.

1.User PVP 2.User Wager 3.Winner get coins
Figure 1 Infographic picture

The game developers take care tracking transactions (e.g. when a player wins a match in-game). MMOCircles takes care of providing the infrastructure for players to recharge gems with real currency, cash out, and tracking. MMOCircles also takes care of user creation/authentication. Game developers may choose to link their users to MMOCircles users. Alternatively, MMOCircles also offer an Authentication API where game developers may use to allow their users to login to MMOCircles with their own login.

Scenario

Any game which has an element of PvP (player versus player) may choose to implement MMOCircles Gem API. The premise is that all players can put some gems into the pot, the winner of the PvP may take a portion of the gems in the pot, the second place another portion, etc. Amounts are determined by the game developers, but may not exceed the maximum number of gems in the pot.

Figure 2 Infographic picture

GGP are a virtual currency in the platform. They are only obtained by exchanging real currency through MMOCircles platform or it’s partner exchanges. They can also be cashed out through the platform. The game developers do not need to concern themselves with the infrastructure; they only need to take care of the gem transactions based on gaming logic.
For gambling games that has a concept of “house”, they are treated as a regular user by the platform. It is up to the game to implement their rules. For example, the “house” can be a company account, which will play in each game. Winnings go to the “house”, but losses are taken from the “house” account.

Even games that are single player can take advantage of your social platform login + in-app purchase API

Documentation

The detailed API documentation can be found here:

Live site: https://docs.mmocircles.com/mmocapi.html

1. Login with GGP

Credentials

To access all REST endpoints, the game developer must create apps within the platform. A game developer needs to have at least 2 apps :

  1. Server side app (1 or more, some game developers choose to run everything on one server) - ONLY FOR MULTIPLAYER GAMES
  2. Client app (as many as needed for each game you run)

The server side app is a confidential app with both a client ID and client secret.
The client side app are public apps (e.g. for Android/iOS/Javascript games). They have a client ID and a redirect URI to receive the access token.
All authorisation flows follow OAuth2.0 standards.
The server side and client side apps are created for you by your account manager.

Server Authentication (only for multiplayer games)

The game server logs-in via a confidential application credential. An access token and a refresh token is returned to the server. The access token is issued for both the app and the user associated with the app (the app creator).

Example call:
POST /auth/token HTTP/1.1
Host: api.mmocircles.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=client_credentials&client_id=23&client_secret=testsecret

The game server logs-in via a confidential application credential. An access token and a refresh token is returned to the The access token returned must be used to access all other endpoints. It must be present in the Authorization header for each subsequent request.

Example call:
Authorization: Bearer CfDJ8K31xx3uPvNAs   …    RUd0yuT2kM

Client Authentication

All clients are authenticated using the OAuth2.0 authorisation code flow

The main login flow for mobile users works like this:

  1. 1. Create a button that says "Login with GGP" in your app
  2. 2. When user clicks on the button, redirect users to our platform through the following url:

    https://api.mmocircles.com/auth/authorize?client_id=[client_id]&response_type=code&redirect_uri=[redirect_uri]

    * Replace [client_id] and [redirect_uri] with the settings specific to your game

  3. 3. After the user enters their credentials, the browser will redirect back to your app via deeplink. For a tutorial on how deeplinks in Unity Engine works, click here.

The following video shows the deeplink + redirect URI in action:

(https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2)

The below outlines a step by step instructions with sample code on handling the authorization code:

  1. User is presented with a button: “Login with MMOCircles”
  2. This takes the user to the login endpoint on their browser

Example endpoint:

https://api.mmocircles.com/auth/authorize?client_id=22&response_type=code&redirect_uri=https://playdat.com

The staging API endpoint (test API) is http://api.mmocircles.com
The authorize endpoint is: /auth/authorize
The GET parameters (query string) contains

  • client_id: 22
  • response_type: token
  • redirect_uri: https://playdat.com

This will take the users to a login page, where they can register or signup with MMOCircles.

After signing-in or registering, they will be taken to the OAuth consent screen:

If the user denies the request, they will be redirected to the redirect URI you specify, plus a query parameter with the access denied error:

https://playdat.com/?error=access_denied&error_description=The%20authorization%20was%20denied%20by%20the%20resource%20owner.

If the user allows the request, the user agent will be redirected to the redirect URI with the access token as part of the hash string:

https://playdat.com/?code=CfDJ8JP6P...pmQlGO4Zw

Caution

Note : the redirect URI is configurable, e.g. for an Android app, you can set the redirect URI to an internal link within your app

With the authorisation code in hand, you are ready to request an access token from the server :

POST /auth/token HTTP/1.1
Host: api.mmocircles.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=authorization_code&code=CfDJ8JP…dClicbA&client_id=22&redirect_uri=https%3A%2F%2F
playdat.com

The result would be an access token and a refresh token :

{
"resource":"resource_server",
"scope":"openid email profile offline_access",
"token_type":"Bearer",
"access_token":"CfDJ8J…JPUA",
"expires_in":3600,
"refresh_token":"CfDJ8JP6…vIn0."
}

With both access tokens in hand, you are ready to call all the gem related API endpoints.

Call all authorized endpoints with Authorization: Bearer [your access token]

2. GGP In-app Purchase

3. GGP Wagering

Pool

A pool is where all the users’ gems are stored during the game. It’s like the “house” in a casino, it will collect all the users’ wagers before the game starts. As the game progresses, the gems in the pool may be distributed to different users.

Joining a pool

Before the game starts, all users must “join” the pool and deposit an initial wagering number of gems.

Pool Transactions

When each user deposits gems in the pool, it is tracked to the user. The game server can create transactions within the pool, which redistributes the gems to different users depending on the game logic.

Caution

Note : the transactions created during the pool are NOT committed, so the users’ GGP balances outside this game does not change until the game is finished.

Committing a Pool

When the game ends, the pool is “committed”, which means all transactions are applied, and all the users’ gems are unlocked and final amount deposited into the users account.

Flow

The main programming flow of implementing the API are as follows (concepts highlighted in bold are explained later in this document):

  1. The game server logins to the platform
  2. The game server creates a pool
  3. All game clients must login to the platform (the login follows standard OAuth2.0)
  4. All game clients join the pool, putting in an initial number of gems
    1. If there is a “house” (from the game server), it can join the pool from the server side, and must put an initial number of gems in the pool
    2. These gems are locked in the pool. This means until the game ends or the player withdraws, these gems are unusable to the player
  5. The game logic runs normally
    1. The server creates transactions between players in the pool, transferring gems from one player to another (the “house” is treated as a player)
    2. If any player withdraws from the game, the gems they put in the pool are up to the game to redistribute. They can go to the “house” (normal scenario), or distributed evenly amongst the remaining players
    3. Players can add more gems to the pool during the gameplay. This is up to the game logic, e.g. the game logic may dictate that any player running out of gems is forced to quit
  6. When the game ends, the game server commits the pool. This will apply all transactions made and update each player’s account. All the gems become unlocked. The winners will have more gems to spend, the losers less.

Pool : A pool is an abstract concept. It simply means all the gems that are on the table. A pool is always self-contained. Until a pool is committed, all gems put into it are locked.

Pools

POST

/Pool

Parameters

Parameter
Content type:

description for pool

Test this endpoint

Response Type
  • BODY SAMPLE
  • BODY SCHEMA
  • RESPONSE SAMPLE
    {
      "id": 0,
      "description": "string",
      "participants": [
        {
          "pooluserid": 0,
          "poolid": 0,
          "usablegems": 0,
          "userid": 0
        }
      ],
      "completed": "2019-04-17T11:34:56.238Z"
    }
  • RESPONSE SCHEMA

You will get back a PoolModel, with the pool ID present. This will be used for subsequent requests.

GET

/Pool/{poolid}

Parameters

Parameter

Test this endpoint

Response Type
  • RESPONSE SAMPLE
    {
      "id": 0,
      "description": "string",
      "participants": [
        {
          "pooluserid": 0,
          "poolid": 0,
          "usablegems": 0,
          "userid": 0
        }
      ],
      "completed": "2019-04-17T11:34:56.238Z"
    }
  • RESPONSE SCHEMA

You will get back a PoolModel, with the pool ID present. This will be used for subsequent requests.

POST

/Pool/{poolid}/join

This endpoint requires a user access token, this endpoint should be called from the client

Parameters

Parameter
Integer An existing pool ID
initialgems
Content type:

The initial number of gems the user wishes to put in the pool. This will throw an error if there are not enough gems for the user

Test this endpoint

Response Type
  • BODY SAMPLE
  • BODY SCHEMA
  • RESPONSE SAMPLE
    {
      "pooluserid": 0,
      "poolid": 0,
      "usablegems": 0,
      "userid": 0
    }
  • RESPONSE SCHEMA

Joins an existing pool. This endpoint should be called from the client, with the user’s access token. The user will then join the pool.
This endpoint returns a PoolUserModel. This is the same model as the array of participants in the PoolModel. You can keep track of the participants in the pool by adding this to the pool model returned earlier.

POST

/Pool/{poolid}/addgems

The user must have already joined the pool

Parameters

poolid
Integer ID of an existing pool
initialgems
Content type:
AddGemsDTO Number of gems to add, and a description for the operation

Test this endpoint

Response Type
  • BODY SAMPLE
    {
      "amount”: 0,
    “description”: “string”
    }
  • BODY SCHEMA
  • RESPONSE SAMPLE
    {
      "pooluserid": 0,
      "poolid": 0,
      "usablegems": 0,
      "userid": 0
    }
  • RESPONSE SCHEMA

Adds gems for a user. This endpoint should be called from the client, with the user’s access token. This will return an updated PoolUserModel reflecting how many gems the users have in the pool right now.

Transactions

POST

/Pool/{poolid}/transactions

Parameters

poolid
Integer poolid
transactions
Content type:

a list of transaction descriptors to add to the pool

Test this endpoint

Response Type
  • BODY SAMPLE
    [
      {
        "frompooluserid”: 0,
        "topooluserid”: 0,
        "amount”: 0,
        “description”: “string”
      }
    ]
  • BODY SCHEMA
  • RESPONSE SAMPLE
    {
      "id": 0,
      "description": "string",
      "participants": [
        {
          "pooluserid": 0,
          "poolid": 0,
          "usablegems": 0,
          "userid": 0
        }
      ],
      "completed": "2019-04-17T13:26:58.018Z"
    }
  • RESPONSE SCHEMA

Creates a transaction, transferring gems from one user in the pool to another. Note the from-pool-user-ids used here are the unique ids form the PoolUserModel, not the user ids

POST

/Pool/{poolid}/commit

Parameters

Pool ID

poolid
Integer
offset
Integer
range
Integer

Test this endpoint

Response Type
  • RESPONSE SAMPLE
  • RESPONSE SCHEMA

Commits all transactions in the pool and updates the user’s gem count. Call this when the game ends and it’s time to tally up the score. The pool becomes unusable after this endpoint is called.

Buy Gems/Cash out

Users will buy gems from our website. We provide landing pages dedicated for your app. You can put a button in your app which links to the landing page for users to buy gems and cash out. Below is an example of a landing page setup for the app Hero of Vegas: