Skip to main content

​
title: “Partner API Requirements”

description: “API endpoints that partners must implement for Stock Games integration”

​
Overview

This guide outlines the API requirements that partners must implement to integrate with Stock Games. Partners need to provide a service-based API that Stock Games will use to manage user wallet operations during gameplay.
Partners must provide their Base URL and API Key to Stock Games during the onboarding process for secure communication.

​
Authentication

All requests from Stock Games include Bearer token authentication: 
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Ensure your API validates the Bearer token on every request for security.

​
Required Endpoints

Your API service must implement these three endpoints:

​
Get Wallet Balance

Purpose: Retrieve the current wallet balance for a user
GET {BASE_URL}/wallet/balance?userId={USER_ID}&gameName={GAME_NAME}
Authorization: Bearer YOUR_API_KEY
Query Parameters
​
userId
string
required
The external user ID from your system
​
gameName
string
required
The name of the game being accessed
Response
​
data
object
required
{
    "balance": 1250.50,
    "userId": "user_12345",
    "gameName": "aviator"
}

​
Deduct Balance

Purpose: Deduct amount from user’s wallet when placing bets
POST {BASE_URL}/wallet/deduction
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Body Parameters
​
userId
string
required
External user identifier
​
amount
number
required
Amount to deduct from wallet
​
roundId
string
required
Game round identifier
​
gameName
string
required
Game identifier
​
betId
string
required
Unique bet identifier
​
transactionId
string
required
Stock Games transaction ID
​
transactionType
string
required
Transaction type (typically “debit”)
Response
​
success
boolean
required
Transaction success status
​
transactionId
string
required
Your internal transaction ID
​
remainingBalance
number
required
User’s remaining wallet balance
{
  "success": true,
}

​
Deposit Balance

Purpose: Add winnings to user’s wallet
POST {BASE_URL}/wallet/deposit
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Body Parameters
​
userId
string
required
External user identifier
​
amount
number
required
Amount to deposit to wallet
​
roundId
string
required
Game round identifier
​
gameName
string
required
Game identifier
​
transactionId
string
required
Stock Games transaction ID
​
transactionType
string
required
Transaction type (typically “credit”)
Response
​
success
boolean
required
Transaction success status
{
  "success": true,
}

​
Error Handling

Your API should return appropriate HTTP status codes: 
{
  "success": true,
  "data": { ... }
}
HTTP Status Codes
  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid API key)
  • 404 - Not Found (user not found)
  • 422 - Unprocessable Entity (insufficient funds, etc.)
  • 500 - Internal Server Error

​
Integration Flow

1

Game Access

User requests to play a game through your platform
2

Balance Check

Stock Games calls your /wallet/balance endpoint
3

Bet Placement

When user places bet, Stock Games calls /wallet/deduction
4

Game Result

If user wins, Stock Games calls /wallet/deposit
5

Balance Update

User’s wallet reflects the latest balance

​
Security Requirements

HTTPS Only

All API endpoints must use HTTPS encryption

API Key Validation

Validate the Bearer token on every request

Rate Limiting

Implement appropriate rate limiting to prevent abuse

Request Validation

Validate all incoming request parameters
For technical questions about implementing these API requirements or during the integration process, please contact the Stock Games integration team.