# Neo API Seamless (Single Wallet) guide

# Overview

## What is Neo API?

Neo API is a super API that brings together the API lines of more than **80 game providers**, so you can connect every provider to your system through a single API.

## Integration

Neo API supports two integration types: See the API integration details

#### 1. Seamless (Single Wallet)

In Seamless, the game provider does not hold the player's money (or holds it only briefly). Every bet and win callbacks to you directly through the API. Every callback must be implemented transactionally and idempotently, to guard against double deductions.

Pros:

- Best UX: the player sees one central balance, with no transfers between systems
- Fewer stuck or lost funds

Cons:

- Your system must handle a very high call rate (high QPS) and respond quickly
- Errors need more complex handling (guarding against duplicates and replays)
- You are the source of truth — you need a solid audit log and replay protection

Suited to:

- Operators with a stable, robust system
- You want players to switch games or providers instantly without transferring
- With a complete idempotency key, ledger and audit implementation

#### 2. Transfer (Two Wallet)

In Transfer, the game provider creates one "provider-side wallet" per player. To play, money must be moved into that wallet first (transfer-in), and when the session ends or the player leaves the game it must be moved back (transfer-out). While the player is in a game the provider runs and settles it itself — there is no callback to you on every round as there is with seamless.

Pros:

- Your system only takes API load at transfer time — it does not have to handle per-bet calls while players are in a game
- The provider settles bets internally
- Easier to start with than seamless

Cons:

- UX may be worse — the player sees separate balances, or transfers are slow and can get stuck
- Money can get stuck if a session hangs or errors

Suited to:

- Teams new to building this kind of system
- Systems that do not want to take real-time gameplay API load

## Credit

Neo API uses a credit system to govern usage. Credit is counted from the win/loss total of the players connected under your account.

Careful:

when credit runs out players cannot play. Keep an eye on whether your account still has enough.

Contact your upline if you need more credit.

## Setting RTP

Neo API supports **30+ RTP-adjustable providers** where you can set the RTP (return to player) and control the payout rate as you like. You can set RTP across all providers or per provider from the UI, and set it precisely per player in real time through the API.

The API offers two ways: send the `rtp` field with `init-session` to set it for that session only, or call `set-rtp` to set it persistently for the whole provider so you don't have to send it on every launch (see section 5.2 of the API integration guide).

# Opening a downline

## Create a sub-agent

You can create sub-agent accounts, and your sub-agents can manage their own downline in turn. As the upline you can oversee every sub-agent beneath you.

### What to fill in when creating a sub-agent:

- **Username**: the sub-agent's username
- **Password**: the sub-agent's password
- **Callback Type**: choose the integration type (Seamless or Transfer)
- **Callback URL**: the URL that receives callbacks (for Seamless). You can leave it blank for now.
- **Credit**: the amount of credit to give the sub-agent
- **Provider Rates**: the commission rate for each provider

## See activity under your line

You can see all sub-agent activity on the dashboard to track statistics such as:

- **Sub-agent list**: see every sub-agent you have created
- **Remaining credit**: see each sub-agent's used and remaining credit
- **Transaction totals**: see each sub-agent's bet volume and win/loss
- **Statistics by period**: see usage statistics for a chosen date range
- **Hierarchy Level**: see the sub-agent's level in the hierarchy

You can click into each sub-agent to see more detail and manage them.

# API integration

## Seamless Integration

Seamless integration has six main steps:

1. Setting the callback URL
2. Preparing to receive callbacks
3. Fetching the game list
4. Creating a session for a player
5. Checking a sub-agent's credit
6. Player lottery bet history

**Glossary:**

- **Agent** means the casino site operator — that is, you
- **Agent id** is your ID, which you can find on the [My account](/settings) page
- **Agent's server** means your own server
- **Provider** means each individual game studio — PG Soft, Pragmatic Play, JOKER, Sexy and so on.

### Authentication

Every request between an agent and Neo API must carry the private key in the `Authorization` header for authentication — and callbacks from Neo API carry it the same way.

Go to the [My account](/settings) page to view and copy your private key

**Note:**

- The private key authenticates your requests to Super API
- Callbacks from Neo API carry the private key in the same way. Don't forget to verify it before processing the data.
- Keep your private key secret and never disclose it to anyone
- If your private key is exposed, reset it immediately for safety

### 1. Setting the callback URL

Go to the [My account](/settings) page, scroll to Manage callback URL and enter the server URL you want callback requests sent to

Callback URL requirements

Neo fires a request at this URL on every bet, so it has to be somewhere our servers can actually reach. We check it when you press save; if it fails you get `CALLBACK_URL_NOT_ALLOWED`

- Must start with `http` or `https`
- Must be a public host — `localhost`, `127.0.0.1` and private ranges ( `10.x`, `172.16–31.x`, `192.168.x`, `169.254.x` ) are not allowed, because our servers cannot reach them anyway
- If it is a domain, we resolve it and check where it actually points — a domain resolving back to an internal IP is rejected too
- A domain whose DNS is not live yet **saves normally** , but callbacks will not work until DNS points at your server
- Never put a username or password in the URL — to confirm a request really came from Neo, check the `Authorization` header we attach (it is your private key)

Prepare to receive callbacks from Neo API. You need two endpoints:

- `/check-balance`
- `/update-balance`

### 2. Preparing to receive callbacks

On both callback routes, Neo API attaches your private key in the `Authorization` header for authentication — please use it to verify the caller.

🔒 Recommended for security:

- Please ask your agent for IP whitelisting to protect against impersonation
- Reset your private key regularly for safety

#### 2.1 Check Balance

On the `/check-balance` route, Neo API sends a request whose payload is `agentId` and `username` (the username comes from when the agent called init-session) to ask the agent for the player's details. The agent must answer Neo API in the specified format.

Request (Neo API → Agent):

```json
POST /check-balance
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "username": "player123",
  "agentId": "agent_123"
}
```

Response (Agent → Neo API):

```json
{
  "username": "player123",
  "balance": 1000.00,
  "status_code": 0
}
```

##### Response body:

- `username`: the username
- `balance`: the user's remaining balance
- `status_code` : the status code

##### Status Code:

- `0`: SUCCESS
- `1`: USER_NOT_FOUND
- `2`: INSUFFICIENT_BALANCE
- `3`: INVALID_REQUEST
- `4`: UNAUTHORIZED
- `5`: FORBIDDEN
- `6`: INTERNAL_SERVER_ERROR
- `7`: TRANSACTION_ALREADY_EXISTS
- `8`: TO_CANCEL_TRANSACTION_NOT_FOUND

##### Example code:

```javascript
// Express.js example
const express = require('express');
const app = express();
app.use(express.json());

const PRIVATE_KEY = process.env.YOUR_PRIVATE_KEY;

app.post('/check-balance', async (req, res) => {
  try {
    // Verify Authorization header
    const authHeader = req.headers.authorization || '';
    if (authHeader !== PRIVATE_KEY) {
      return res.status(401).json({
        username: req.body.username || '',
        balance: 0,
        status_code: 4 // UNAUTHORIZED
      });
    }
    
    const { username, agentId } = req.body;
    
    // Get user balance from database
    // Replace this with your actual database query
    const userBalance = await getUserBalance(username, agentId);
    
    if (userBalance === null) {
      return res.json({
        username: username,
        balance: 0,
        status_code: 1 // USER_NOT_FOUND
      });
    }
    
    return res.json({
      username: username,
      balance: userBalance,
      status_code: 0 // SUCCESS
    });
  } catch (error) {
    console.error('Error:', error);
    return res.json({
      username: req.body.username || '',
      balance: 0,
      status_code: 6 // INTERNAL_SERVER_ERROR
    });
  }
});

async function getUserBalance(username, agentId) {
  // Implement your database query here
  // Return balance or null if user not found
}
```

#### 2.2 Update Balance

On the `/update-balance` route, Neo API sends a request whose payload is the player's gameplay and its outcome, so the agent's server can verify and adjust the data. It mainly uses `transferIn` (the player puts money into the system, similar to a bet) and `transferOut` (we pay the player, similar to a settle).

📢 Notice (Sep 2026): the callback now carries isBuyFeature / isFreeSpin for every provider that has them

- Since 23 Sep 2026 this route attaches both isBuyFeature and isFreeSpin for every provider that has the data. Before, it only carried isBuyFeature for some _plus providers, and isFreeSpin was never sent at all
- What the two fields mean, and a table of which provider has which, are in the box further down this section
- **null or a missing field does not mean the player did not buy — it means the provider does not send us this information. Do not count it as false in your reports**

⚠️ Important things to check:

- Don't forget to check that the player has enough balance to transfer in
- Don't forget to check for a duplicate providerTransactionId — if you receive one you have seen before, do not count it again. This happens when the agent answers Neo API slowly and Neo API retries with the same provider transaction id.
- If the `ableNegativeBalance` field is true, the agent must allow the player's balance to go negative
- The `toCancelProviderTransactionId` field lets the provider reference the transaction to cancel; the agent must void that transaction in their system.
- field `isBuyFeature` and `isFreeSpin` (optional) are attached to the request `only when they are true` If the field is absent, either the round was not one of these or the provider never told us — see the table below for which providers send them

How isBuyFeature and isFreeSpin differ

`isBuyFeature` = this round comes from a feature the player paid a lump sum to buy straight into, rather than waiting to trigger it. The buy-in is usually around 100x their normal stake, so the round where they paid carries an unusually high betAmount compared with that same player's other rounds

`isFreeSpin` = a round the player did not pay extra for, carried over from a previous round — in-game free spins, re-spins and continuation rounds all count. That is why these rounds usually have betAmount 0 while still paying out

The two normally come together — the player buys the feature on one round (isBuyFeature) and then gets several free rounds after it (isFreeSpin). When you compute turnover or real stake, take care not to count the free rounds as money the player put in

Some providers (e.g. PG and AMB) also mark the free rounds that follow a purchase with isBuyFeature, so those rounds are true on both fields and have betAmount 0 — to count how many times players bought the feature, count only rounds where isBuyFeature is true and isFreeSpin is not true, or the PG figure comes out roughly 20 times too high

⚠️ null does not mean "did not buy" or "not a free spin"

- null means the provider does not send us this information — so we do not know whether the player bought the feature or whether it was a free spin. Only false means the provider told us "no"
- In the callback we only attach the field when it is true — if it is absent, check the table below: for a ✅ provider it means "no", for a ⚠️ or ❌ provider it means "unknown"
- Do not count null as false in your reports, or the numbers will say almost nobody ever bought the feature — which is not true

Which providers have isBuyFeature / isFreeSpin

| Provider | `isBuyFeature` | `isFreeSpin` |
| --- | --- | --- |
| PG_plus, JILI_plus, JOKER_plus, NOLIMITCITY_plus, EVOPLAY_plus, FACHAI_plus | ✅ | ✅ |
| NEXTSPIN_plusNew provider (Oct 2026), still being confirmed against real transactions | ⚠️ | ⚠️ |
| PG | ✅ | ✅ |
| AMB | ✅ | ✅ |
| 759GAMING, AFB1188_SLOT, AMBGAMING | ✅ | ✅ |
| JILI | ✅ | ❌ |
| PP | ✅ | ❌ |
| OCTOPLAYsent only on rounds where the feature was bought | ⚠️ | ❌ |
| CLOTPLAYsent on roughly half of the records | ⚠️ | ❌ |
| BOOMING, YGR, I8 | ❌ | ✅ |
| JOKERsent only on bonus rounds | ❌ | ⚠️ |
| NEXTSPINsent only on rounds that are free spins | ❌ | ⚠️ |
| BIGPOT, HOTDOG, FUNKYsent on roughly half of the records | ❌ | ⚠️ |
| SA_plus, SEXY_pluslive casino, the feature does not exist here | always false | always false |

✅ sent on every record · ⚠️ sent on some records only, treat a missing value as unknown, not false · ❌ never sent, always null

Every other provider has neither — always null

- Every other _plus provider not in the table, e.g. PRAGMATIC_plus, CQ9_plus, HABANERO_plus, HACKSAW_plus, JDB_plus, KA_plus, PLAYSON_plus, SPRIBE_plus, TADA_plus, 3OAKS_plus — these run on a different upstream system from the _plus providers in the table, even though the names end in _plus the same way
- PNG, HAB, RLX, NE, RTG, WAZ, YGG, PRG, NLC, EVP and FCG
- Other slot providers, e.g. ROYAL, LIVE22, SLOTXO, RICH88, PRETTY, SPADE, KINGMAKER
- Live casino, sports and lottery (SA, SEXY, DG, WM, SBO, BTI, UFAPLUS, HIPPO, HUAYDRAGON, LEKTHONG) — free spin / buy feature does not exist in these products

**Provider names can repeat** — JILI_plus and JILI, PG_plus and PG, NOLIMITCITY_plus and NLC, EVOPLAY_plus and EVP, NEXTSPIN_plus and NEXTSPIN are different providers on different systems, and they do not support these fields the same way. Key your reports on providerId, not the provider name

freeSpinIndex / freeSpinTotal — which free spin this is, and how many are left

⚠️ Only 2 providers: PG_plus and JOKER_plus

- Free spins are counted for these two providers only. Every other provider sends neither field, including PG, JOKER and the other _plus providers such as JILI_plus, NOLIMITCITY_plus, EVOPLAY_plus, FACHAI_plus and NEXTSPIN_plus
- PG_plus: some games never carry the two fields because they have no free spins to count, e.g. Fortune Ox, Fortune Horse (the feature ends in one spin), Ninja Racoon Frenzy, Werewolf's Hunt (hold & win respins with no fixed number of spins), The Great Icescape (examples, not a complete list)
- JOKER_plus: only the 28 games that pay free spins one spin at a time: Aladdin, Alice, Ancient Egypt, Arctic Treasure, Dragon Phoenix, Egypt Queen, Fei Long Zai Tian, Five Tiger Generals, Genie, Golden Dragon, Golden Island, Golden Rooster, Happy Buddha, Hercules, Jungle Island, Lucky Drum, Lucky God Progressive, Lucky Panda, MoneyBangBang, Mulan, Queen, Robin Hood, Safari Heat, Santa Surprise, Water Margin, White Snake, Wild Spirit, Zhao Cai Jin Bao
- Other JOKER_plus games, e.g. Immortals and Horus Eye, pay the whole feature in one transaction, whether it was bought or triggered, so they carry neither field

`freeSpinIndex` = the free spin this transaction pays, counted from 1. 0 is the paid spin that triggered the feature, or the spin that bought it

`freeSpinTotal` = how many free spins the feature holds at that moment. It goes up when the player wins extra free spins along the way, e.g. 1/4 → 2/5 → 3/6

**Free spins left = freeSpinTotal − freeSpinIndex** — we do not send the number left; work it out from these two fields

- The two fields always come together, and only on transactions inside a feature. A normal spin has neither field; a missing field does not mean 0
- The paid spin and the cascades that follow it before the feature starts may already carry isFreeSpin but not these two fields yet. The pair starts at freeSpinIndex 0 when the feature begins
- PG_plus: one free spin can produce several transactions with the same freeSpinIndex (cascades within one spin), so do not count transactions as spins. JOKER_plus sends one transaction per spin, and freeSpinIndex never repeats
- In a feature the player bought, PG_plus transactions carry no isFreeSpin but do carry both fields, and in some rounds freeSpinIndex 0 lands on the 2nd or 3rd transaction because the free spins came from a later cascade. To tell which transactions belong to a feature, use these two fields rather than isFreeSpin
- For display and reporting only, they never affect money: settle balances from transferIn / transferOut as before

Request (Neo API → Agent):

```json
POST /update-balance
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "agent_123",
  "username": "player123",
  "providerTransactionId": "txn_123456",
  "transferIn": 0.00,
  "transferOut": 50.00,
  "ableNegativeBalance": false,
  "toCancelProviderTransactionId": null,
  "isBuyFeature": true,
  "isFreeSpin": true,
  "freeSpinIndex": 3,
  "freeSpinTotal": 10
}
```

Response (Agent → Neo API):

```json
{
  "username": "player123",
  "balanceBefore": 1000.00,
  "balanceAfter": 1050.00,
  "status_code": 0
}
```

##### Response body:

- `username`: the username (same as in the request)
- `balanceBefore` : balance before the transaction
- `balanceAfter` : balance after the transaction
- `status_code` : the status code — Neo API uses this field (it must be named exactly `status_code` ) to decide whether a transaction succeeded

##### Status codes in the response:

- `0`: the transaction succeeded
- `1`: the username was not found
- `2`: the player has insufficient funds for transferIn
- `3`: the request was sent in the wrong format
- `4`: the agent id sent is wrong
- `5`: the private key sent is wrong
- `6`: some other problem on the agent's server
- `7`: duplicate providerTransactionId
- `8`: the providerTransactionId to cancel was not found

##### Example code:

```javascript
// Express.js example
const express = require('express');
const app = express();
app.use(express.json());

const PRIVATE_KEY = process.env.YOUR_PRIVATE_KEY;

app.post('/update-balance', async (req, res) => {
  try {
    // Verify Authorization header
    const authHeader = req.headers.authorization || '';
    if (authHeader !== PRIVATE_KEY) {
      return res.status(401).json({
        username: req.body.username || '',
        balanceBefore: 0,
        balanceAfter: 0,
        status_code: 5 // FORBIDDEN (wrong private key)
      });
    }

    const {
      username,
      agentId,
      providerTransactionId,
      transferIn = 0,
      transferOut = 0,
      ableNegativeBalance = false
    } = req.body;

    // Check if transaction already exists (idempotency check)
    const isProcessed = await isTransactionProcessed(providerTransactionId);
    if (isProcessed) {
      const currentBalance = await getUserBalance(username, agentId);
      return res.json({
        username: username,
        balanceBefore: currentBalance || 0,
        balanceAfter: currentBalance || 0,
        status_code: 7 // TRANSACTION_ALREADY_EXISTS
      });
    }

    // Get current balance
    const currentBalance = await getUserBalance(username, agentId);
    if (currentBalance === null) {
      return res.json({
        username: username,
        balanceBefore: 0,
        balanceAfter: 0,
        status_code: 1 // USER_NOT_FOUND
      });
    }

    // Check if user has enough balance for transfer in
    if (transferIn > 0 && currentBalance < transferIn && !ableNegativeBalance) {
      return res.json({
        username: username,
        balanceBefore: currentBalance,
        balanceAfter: currentBalance,
        status_code: 2 // INSUFFICIENT_BALANCE
      });
    }

    // Calculate new balance
    const newBalance = currentBalance - transferIn + transferOut;

    // Update balance in database
    await updateUserBalance(username, agentId, newBalance);

    // Mark transaction as processed
    await markTransactionProcessed(providerTransactionId);

    return res.json({
      username: username,
      balanceBefore: currentBalance,
      balanceAfter: newBalance,
      status_code: 0 // SUCCESS
    });
  } catch (error) {
    console.error('Error:', error);
    return res.json({
      username: req.body.username || '',
      balanceBefore: 0,
      balanceAfter: 0,
      status_code: 6 // INTERNAL_SERVER_ERROR
    });
  }
});

async function isTransactionProcessed(transactionId) {
  // Check if transaction already processed
  // Implement your idempotency check here
  return false;
}

async function getUserBalance(username, agentId) {
  // Get user balance from database
  // Return balance or null if user not found
  return null;
}

async function updateUserBalance(username, agentId, newBalance) {
  // Update user balance in database
}

async function markTransactionProcessed(transactionId) {
  // Mark transaction as processed
}
```

#### 2.3 Verifying the callback

Neo API has a tool for testing your callback endpoints on the [Callback Test](/callback-test) page, so you can check whether they work correctly.

##### How to use the callback test runner:

1. Go to the [Callback Test](/callback-test) page
2. Fill in what is required:`Callback URL` : the URL of your callback server`Agent ID` : your agent's ID`Private Key` : your private key`Username` : the username of the player to test with
3. Click `Run Tests` to start testing
4. It tests both callback endpoints: `/check-balance` and `/update-balance`
5. Review the test results and check that your callback endpoints answer in the expected format

💡 Tips:

- Make sure your callback server is reachable from the internet
- Check that your callback endpoints support HTTPS (if using production)
- Check that the Authorization header and response format match the specification
- Test the various cases — a username that doesn't exist, insufficient balance, a duplicate transaction id, and so on
- The test runner fires requests straight from the browser, so your callback server must allow CORS for this tool to work — only while testing. In production Neo API calls server-to-server, where CORS does not apply.

### 3. Fetching the game list

The endpoint an agent calls on Neo API to get all games, or the games of a given provider, so the `gameId` can then be used to create a session for a player

📢 Notice (Jul 2026): Plus providers have new providerId / gameId

- JILI_plus, SA_plus, NOLIMITCITY_plus, EVOPLAY_plus and FACHAI_plus have moved to a new system — **the provider names are unchanged, but providerId and gameId are all new** — along with a new provider, SEXY_plus
- Please call get-games to sync the new game list, then update the gameId / providerId stored in your system
- The old gameId set still launches games during the transition only, and will be switched off in the next step — we recommend syncing again now.

Request:

```json
POST /api/external/get-games
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "providerList": ["string"] // optional
}
```

##### Request body:

- `agentId`: the agent's ID
- `providerList` : the provider IDs you want (optional — all of them if omitted)

Response:

```json
{
  "providers": [
    {
      "provider": {
        "id": "string",
        "name": "string",
        "isRedirect": true,
        "logoUrl": "string" // optional
      },
      "games": [
        {
          "id": "string",
          "name": "string",
          "code": "string",
          "imageUrl": "string",
          "type": "slot" | "casino" | "table" | "fishing" | "lottery" | "virtual" | "sports",
          "tag": "string", // optional
          "order": 0, // optional
          "isRecommend": true,
          "isNew": false,
          "providerId": "string",
          "mappedGameCode": "string" // optional
        }
      ]
    }
  ]
}
```

##### Response body:

- `providers`: providers with their related games
- `provider.id`: the provider's ID
- `provider.name` : the provider's name
- `provider.isRedirect` : whether this provider uses a redirect
- `provider.logoUrl` : the provider's logo URL (optional)
- `games`: the games under this provider
- `game.type`: the game type (slot, casino, table, fishing, lottery, virtual, sports)
- `game.isRecommend` : whether the game is featured
- `game.isNew`: whether the game is new

##### Example code:

```bash
curl -X POST https://api.neoapihub.com/api/external/get-games \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "string",
    "providerList": ["string"]
  }'
```

### 4. Creating a session

The endpoint an agent calls on Neo API to get a redirect URL that starts a game for a player

**Note:**

- If you run several sites, we suggest suffixing the username with the site name to avoid duplicates
- The private key must be attached in the Authorization header

Request:

```json
POST /api/external/init-session
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "gameId": "string",
  "username": "string",
  "hrefBackUrl": "string",
  "agentId": "string",
  "language": "en" | "cn" | "jp" | "th" | "vn" | "kr",
  "isDesktop": true, // optional, default: true
  "rtp": number, // optional, 30-99 (default: 97)
  "clientIp": "string", // required for PG games
}
```

##### Request body:

- `gameId`: the ID of the game to play
- `username`: the username
- `hrefBackUrl`: the URL to return to when leaving the game
- `agentId`: the agent's ID
- `language`: the language you want (en, cn, jp, th, vn, kr). Default: th
- `isDesktop`: whether this is desktop (optional, default: true)
- `rtp`: the game's RTP (optional, 30-99, default: 97)
- `clientIp`: The player's IP address (required for PG games — without it init-session answers 400 and the game will not open; every other provider ignores this field)

Response:

```json
{
  "url": "string", // optional
  "html": "string", // optional
  "type": "url" | "html" | "redirect"
}
```

##### Response body:

- `url`: the URL to launch the game (optional, present when type = "url" or "redirect")
- `html`: HTML for launching the game (optional, present when type = "html")
- `type`: the response type ("url", "html" or "redirect")

##### Example code:

```bash
curl -X POST https://api.neoapihub.com/api/external/init-session \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gameId": "string",
    "username": "string",
    "hrefBackUrl": "string",
    "agentId": "string",
    "language": "th",
    "isDesktop": true,
    "rtp": 97,
    "clientIp": "203.0.113.42"
  }'
```

Handling the response:

- When you call `/api/external/init-session` , the response comes back and you must first look at `type` to see whether it is `url` or `html`
- If it is a **URL** (type = "url") or **REDIRECT** (type = "redirect"), use the `url` returned to open the game in a new tab (especially type = "redirect", e.g. HuayDragon, which does not support iframes — it must be a new tab and must never be embedded in an iframe)
- If it is **HTML** (type = "html"), your site must render the HTML from `html` to open the game for the player

### 5. Checking a sub-agent's credit

An endpoint for checking an upline's overall credit and, in one call, the credit of every sub-agent beneath it — useful for a dashboard or credit monitoring page

Request:

```json
POST /api/external/get-sub-agent-quota-summary
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string"
}
```

##### Request body:

- `agentId` (required): the agent ID of the upline whose credit you want to check

Response:

```json
{
  "winningQuota": 100000,
  "winningQuotaUsed": 25000,
  "subagents": [
    {
      "username": "subagent01",
      "winningQuota": 30000,
      "winningQuotaUsed": 5000
    }
  ]
}
```

##### Response:

- `winningQuota` : the upline's total credit
- `winningQuotaUsed` : the credit the upline has already used
- `subagents`: the credit of the sub-agents under this line

### 5.1 Commission and share per provider (Subagent Providers)

An endpoint for viewing the providers of an upline and its direct sub-agents (one level), with each provider's company rate and commission rate — useful for checking and comparing the split across lines

Request:

```json
POST /api/external/get-sub-agent-providers
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string"
}
```

##### Request body:

- `agentId` (required): the agent ID of the upline whose provider list you want

Response:

```json
{
  "agentId": "agent-001",
  "username": "headagent",
  "providers": [
    {
      "providerId": "provider-uuid",
      "providerName": "PG",
      "providerFullName": "PG Soft",
      "isActive": true,
      "commissionRate": 5.00,
      "companyRate": 70.00,
      "canSetRtp": true,
      "canSetPreset": false,
      "gameTypes": ["slot"],
      "rtpMode": "rtp",
      "rtp": 96,
      "presetId": null
    }
  ],
  "subagents": [
    {
      "agentId": "subagent-uuid",
      "username": "subagent01",
      "providers": [
        {
          "providerId": "provider-uuid",
          "providerName": "PG",
          "providerFullName": "PG Soft",
          "isActive": true,
          "commissionRate": 3.00,
          "companyRate": 60.00,
          "canSetRtp": true,
          "canSetPreset": true,
          "gameTypes": ["slot"],
          "rtpMode": "preset",
          "rtp": null,
          "presetId": "preset-uuid"
        }
      ]
    }
  ]
}
```

##### Response:

- `agentId`: the calling upline's agent ID
- `username`: the calling upline's username
- `providers`: the upline's own providers, with company rate and commission rate
- `subagents`: the sub-agents under this line (one level), each with its own provider list
- `providerId` / `providerName` : the provider's ID and name
- `isActive`: whether that provider is enabled for this line
- `companyRate`: the company's share percentage with this provider (%)
- `commissionRate` : this line's commission percentage with this provider (%)
- `canSetRtp`: whether this provider allows setting RTP
- `canSetPreset` : whether this provider accepts presets. false means numbers only — hide the preset dropdown for these.
- `gameTypes`: the game types this provider offers — use it to decide whether to show the Set RTP button (we suggest showing it only for providers that have slots)
- `rtpMode`: this provider's current mode — rtp (numeric) or preset
- `rtp` / `presetId`: the value currently set; whichever is unused is null. Use it with set-rtp (section 5.2) to build your own settings page.

### 5.2 Set RTP

An endpoint for setting a provider's RTP, for your own line or for a sub-agent exactly one level down. The value is stored persistently — you don't have to send it on every game launch.

Combined with the other two endpoints this gives you everything the "Providers" page in our back office has — for anyone who wants to build their own settings page:

1. `get-sub-agent-providers` — fetch the provider list together with each provider's current RTP
2. `get-presets` — fetch the preset list to build a dropdown
3. `set-rtp` — save the value

Each provider is in exactly one mode

- **Numeric mode** — send `rtp` as an integer from 30 to 99
- **Preset mode** — send the `presetId` you got from get-presets

Send one or the other — **sending both, or neither, is rejected** — and whichever you send clears the other to `null` automatically. To switch modes just send the field for the mode you want; there is no need to clear anything yourself. Each provider's current mode is in the `rtpMode` field of get-sub-agent-providers.

Order of precedence for RTP at game launch:

1. If `init-session` also sends `rtp`, that value is used for that session (what you send always wins)
2. If omitted, the value set via `set-rtp` is used
3. If it has never been set, the provider's own default is used

In other words, if your system already sends `rtp` with every init-session, the value set via set-rtp will not be used.

Providers with canSetPreset true: the number you send is a preset's name, not a free-floating RTP value

Providers with canSetPreset true (e.g. PG_plus and JOKER_plus) accept only presets. The number you send is matched against a preset with that name, and that preset is sent to the provider — the number itself is never passed through.

So if you send a number with no preset of that name — say `93` when only presets named 94 and 96 exist — you get `RTP_HAS_NO_MATCHING_PRESET` back, along with an `availableRtp` field listing the numbers that do work, which you can turn straight into options on your own screen.

Providers with canSetPreset false take the raw number — send anything from 30 to 99, no preset required.

Providers with canSetPreset true: set a real RTP number + volatility (payout models)

Call ensure-model-preset with the RTP you want (up to 2 decimals). It returns one preset for that value — the same id however often you call it — and you use its presetId with set-rtp or init-session like any preset. Every game pays the RTP you set, because it is computed from each game's own pay table.

- model "mixture" = your RTP + volatility low / medium / high
- model "pgx_v2" = each game's original RTP (send no targetRtp or volatility)
- model "rewardflow" = automatic per-player adjustment (RewardFlow) at your RTP; every style pays the same RTP

Or send it with init-session directly (providers with canSetPreset true only): model + targetRtp + volatility, or rewardFlow: true + rtp. Not together with presetId, payoffSetting or a pool — that returns MODEL_LAUNCH_CONFLICT.

```json
POST /api/external/ensure-model-preset
Authorization: YOUR_PRIVATE_KEY
{ "agentId": "YOUR_AGENT_ID", "model": "mixture", "targetRtp": 95.5, "volatility": "medium" }

→ { "id": "PRESET_ID", "note": "95.5% ผันผวนกลาง", "rtpNormal": 0.955,
    "model": { "model": "mixture", "targetRtp": 95.5, "volatility": "medium" }, ... }

# per launch (canSetPreset providers only)
POST /api/external/init-session
{ ..., "model": "mixture", "targetRtp": 95.5, "volatility": "high" }
{ ..., "rewardFlow": true, "rtp": 96 }
```

Only supported providers can be set — check the `canSetRtp` field. If it is `false` the call is rejected with `PROVIDER_CANNOT_SET_RTP` . We also suggest hiding the button for providers with no slot games (see `gameTypes`), because adjusting RTP is meaningless for live casino or sports — our own back office uses the same rule.

Request:

```json
POST /api/external/set-rtp Content-Type: application/json Authorization: YOUR_PRIVATE_KEY { "agentId": "string", "providerId": "string", "rtp": number, // numeric mode: 30-99 (integer) "presetId": "string", // preset mode — send either this or rtp "targetAgentId": "string" // optional }
```

##### Request body:

- `agentId` (required): the calling upline's agent ID (the owner of the private key)
- `providerId` (required): the ID of the provider to configure. Use the value from `get-sub-agent-providers` or `get-games`
- `rtp`: the RTP as an integer from 30 to 99 (decimals are rejected). Sending this switches to numeric mode and clears presetId.
- `presetId`: the ID of a preset from `get-presets` . Sending this switches to preset mode and clears rtp — only for providers where canSetPreset = true.
- `targetAgentId` (optional): the agent ID to configure. Omitted means yourself. Only yourself or a sub-agent exactly one level down is allowed (grand-sub-agents are rejected), and the provider must be one you hold.

Response:

```json
{
  "agentId": "agent-001",
  "username": "headagent",
  "providerId": "provider-uuid",
  "providerName": "PG_plus",
  "rtpMode": "rtp",
  "rtp": 96,
  "presetId": null,
  "previousRtp": 90,
  "previousPresetId": null
}
```

##### Response:

- `agentId` / `username`: the line actually configured (yourself, or the sub-agent named in targetAgentId)
- `rtpMode`: this provider's mode after saving — either `rtp` or `preset`
- `rtp` / `presetId`: the value now in effect; whichever is unused is `null`
- `previousRtp` / `previousPresetId` : the previous values, to confirm what changed to what (if it was in preset mode and you send rtp, previousPresetId has a value and presetId is null)

##### Possible errors:

- `RTP_OR_PRESET_ID_REQUIRED` (400): neither rtp nor presetId was sent, or both were
- `RTP_MUST_BE_BETWEEN_30_AND_99` (400): rtp is not an integer between 30 and 99
- `RTP_HAS_NO_MATCHING_PRESET` (400): this provider has canSetPreset true and no preset is named after the number you sent — see the availableRtp field on the error for the numbers that actually work
- `PROVIDER_OPERATOR_NOT_CONFIGURED` (400): a provider with canSetPreset true has no operator bound on this line yet, so a numeric value cannot be set (use a preset instead). Contact the team if you hit this.
- `PROVIDER_CANNOT_SET_RTP` (400): this provider does not support setting RTP (canSetRtp = false)
- `PROVIDER_CANNOT_SET_PRESET` (400): this provider only accepts a number, not a preset (canSetPreset = false)
- `INVALID_PRIVATE_KEY` (401): the private key does not match agentId
- `AGENT_DO_NOT_HAVE_PERMISSION` (403): targetAgentId is neither you nor a direct sub-agent, or you do not hold this provider
- `AGENT_PROVIDER_NOT_FOUND` (404): the specified line does not have this provider enabled
- `PRESET_NOT_FOUND` (404): the presetId sent is not in your preset list

##### Example code:

```bash
# Numeric mode — set RTP 96 on one of your own providers curl -X POST https://api.neoapihub.com/api/external/set-rtp \ -H "Authorization: YOUR_PRIVATE_KEY" \ -H "Content-Type: application/json" \ -d '{ "agentId": "YOUR_AGENT_ID", "providerId": "PROVIDER_ID", "rtp": 96 }' # Preset mode — use a presetId from get-presets (rtp is cleared automatically) curl -X POST https://api.neoapihub.com/api/external/set-rtp \ -H "Authorization: YOUR_PRIVATE_KEY" \ -H "Content-Type: application/json" \ -d '{ "agentId": "YOUR_AGENT_ID", "providerId": "PROVIDER_ID", "presetId": "PRESET_ID" }' # Set it for the next-level sub-agent curl -X POST https://api.neoapihub.com/api/external/set-rtp \ -H "Authorization: YOUR_PRIVATE_KEY" \ -H "Content-Type: application/json" \ -d '{ "agentId": "YOUR_AGENT_ID", "providerId": "PROVIDER_ID", "targetAgentId": "SUBAGENT_ID", "rtp": 92 }'
```

### 6. Player lottery bet history

An endpoint for pulling one player's lottery bet history, with pagination and status filtering — suited to a history page or to checking a player's wins and losses

Request:

```json
POST /api/external/get-poy-group-history-by-user
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "userId": "string",
  "poyGroupStatusList": ["WIN", "LOSE"], // optional
  "skip": 0, // optional (default: 0)
  "take": 10 // optional (default: 10)
}
```

##### Request body:

- `agentId` (required): the agent ID of the line that owns the player
- `userId` (required): the player's username on the agent side
- `poyGroupStatusList` (optional): filter by entry status, e.g. `WIN`, `LOSE`, `SETTLED`, `PENDING`, `FAILED`, `CANCELLED`, `REFUND`
- `skip` (optional): how many entries to skip
- `take` (optional): entries per page

##### What the statuses mean (PoyGroupStatus):

- `PENDING`: the bill was received and is awaiting processing
- `SETTLED`: paid out successfully
- `FAILED`: payout failed
- `WIN`: the round closed as a win
- `LOSE`: the round closed as a loss
- `CANCELLED`: the entry was cancelled
- `REFUND`: cancelled and refunded successfully (the cancel callback succeeded)

Response:

```json
{ "total": 120, "take": 10, "skip": 0, "data": [ { "id": "string", "roundStartDate": "2026-03-12T08:00:00.000Z", "roundEndDate": "2026-03-12T09:00:00.000Z", "gameName": "Thai Government Lottery", "gameCode": "THAI_GOV", "totalAmount": 1000, "totalPayoff": 1500, "userId": "player123", "status": "WIN", "createdAt": "2026-03-12T08:10:00.000Z", "updatedAt": "2026-03-12T09:05:00.000Z", "poys": [ { "id": "string", "userId": "player123", "multiple": 1, "poyType": "THREE_UP", "poyNumber": "123", "amount": 100, "payoff": 900, "rate": 9, "status": "SUCCESS", "createdAt": "2026-03-12T08:11:00.000Z", "updatedAt": "2026-03-12T09:05:00.000Z", "subPoys": [ { "id": "string", "poyType": "TWO_UP", "poyNumber": "12", "amount": 50, "payoff": 0, "multiplier": 1, "status": "FAILED", "createdAt": "2026-03-12T08:11:00.000Z", "updatedAt": "2026-03-12T09:05:00.000Z" } ] } ] } ] }
```

##### Response:

###### Root level ( `GetPoyGroupHistoryByUserResponse` )

- `data`: the user's bill groups ( `PoyGroupHistoryItem[]` ) matching the filter and pagination
- `total`: how many bill groups match (before skip/take)
- `skip`: how many to skip (the pagination offset)
- `take`: how many per page (the pagination limit)

###### Bill-group level ( `PoyGroupHistoryItem` )

- `id`: the bill group's transaction ID (for reference / confirmation with the operator)
- `roundStartDate` : when the round started
- `roundEndDate` : when the round closed
- `gameName`: the game name (some types append a set suffix)
- `gameCode`: the game code
- `totalAmount`: the total the user bet in this bill group
- `totalPayoff`: the total paid or returned to the user in this bill group
- `userId`: the ID of the user who bet
- `status`: the bill group's status (e.g. `PENDING`, `SETTLED`, `WIN`, `LOSE`, `FAILED`, `CANCELLED`, `REFUND`)
- `createdAt`: when the bill group was created
- `updatedAt`: when it was last updated
- `poys`: the sub-bills ( `PoyHistoryItem[]` ) in this bill group

###### Bill level ( `PoyHistoryItem` )

- `id`: the sub-bill ID
- `userId`: the user ID
- `multiple`: the multiple (how many times the stake per set)
- `poyType`: the number type / format (e.g. TWO_UP, THREE_DOWN, SET_FOUR)
- `poyNumber`: the number bet (string)
- `amount`: the stake on this bill
- `payoff`: the amount paid or returned on this bill
- `rate`: the rate used in the calculation
- `status`: the sub-bill's status
- `createdAt`: when the bill was created
- `updatedAt`: when it was last updated
- `subPoys`: lower-level sub-bills (present in some cases, such as set games)

###### subPoy level ( `SubPoyHistoryItem` )

- `id`: the SubPoy ID
- `poyType`: the sub-bill's number type
- `poyNumber`: the sub-bill's number
- `amount`: the amount the sub-bill refers to
- `payoff`: the amount paid on the sub-bill
- `multiplier`: the sub-bill's prize multiplier
- `status`: the sub-bill's status
- `createdAt`: when it was created
- `updatedAt`: when it was last updated

Structure summary:

Response = the bill groups (

data

) + pagination (

total

,

skip

,

take

) and each bill group contains

poys

with some types carrying

subPoys

one level deeper

### 7. Per-player transaction history

An endpoint for pulling the game transaction history (bet / settle / cancel) of players in your line, filterable by player name and date range, with pagination — suited to a history page or to checking a player's bet volume and win/loss

Request:

```json
POST /api/external/get-transaction-by-username
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "username": "player123", // optional
  "startDate": "2026-06-01T00:00:00.000Z", // optional
  "endDate": "2026-06-19T23:59:59.999Z", // optional
  "skip": 0, // optional (default: 0)
  "take": 10 // optional (default: 10)
}
```

##### Request body:

- `agentId` (required): your agent ID (the owner of the private key)
- `username` (optional): the player's name on the agent side — omit it to get entries for every player in your line
- `startDate` (optional): start time (ISO 8601)
- `endDate` (optional): end time (ISO 8601)
- `skip` (optional): how many entries to skip (default: 0)
- `take` (optional): entries per page (default: 10)

Note:

every entry is scoped to players under your agent (by private key) — you cannot see another agent

'

s data even with a matching username

Response:

```json
{
  "total": 2,
  "take": 10,
  "skip": 0,
  "data": [
    {
      "id": "string",
      "providerTransactionId": "string",
      "usernamePlayer": "player123",
      "betAmount": 100,
      "settleAmount": 0,
      "turnOver": 100,
      "transferIn": 0,
      "transferOut": 100,
      "gameType": "SLOT",
      "status": "SUCCESS",
      "gameId": "string",
      "agentId": "string",
      "createdAt": "2026-06-19T08:10:00.000Z",
      "updatedAt": "2026-06-19T08:10:05.000Z",
      "isBuyFeature": true,
      "isFreeSpin": false,
      "game": {
        "id": "string",
        "name": "Fortune Gems",
        "code": "JILI_FG",
        "providerId": "string",
        "providerName": "JILI_plus"
      }
    }
  ]
}
```

##### Response:

- `data` the player's transactions matching the filter and pagination
- `total` entries on this page
- `skip` / `take`: the pagination values sent (offset / limit)
- `betAmount` the stake
- `settleAmount` the amount paid back (the win/loss result)
- `turnOver` the entry's turnover
- `isBuyFeature` : `true` when the player bought the feature (Buy Feature) on that round
- `isFreeSpin`: `true` when the round is a spin the player did not pay extra for — covering in-game free spins, re-spins and rounds carried over from a previous bet, which is why these entries usually have `betAmount` of 0 but still pay out
- **Both fields are null when the provider does not send us this information** — that does not mean the player did not buy the feature or that it was not a free spin, it means the provider never told us, so do not count `null` as `false` in your reports · see the table below for which providers do and do not send it
- `status`: the entry's status ( `PENDING`, `SUCCESS`, `FAILED`)
- `game`: game details such as `name`, `code`, `providerName` (the provider's name)

How isBuyFeature and isFreeSpin differ

`isBuyFeature` = this round comes from a feature the player paid a lump sum to buy straight into, rather than waiting to trigger it. The buy-in is usually around 100x their normal stake, so the round where they paid carries an unusually high betAmount compared with that same player's other rounds

`isFreeSpin` = a round the player did not pay extra for, carried over from a previous round — in-game free spins, re-spins and continuation rounds all count. That is why these rounds usually have betAmount 0 while still paying out

The two normally come together — the player buys the feature on one round (isBuyFeature) and then gets several free rounds after it (isFreeSpin). When you compute turnover or real stake, take care not to count the free rounds as money the player put in

Some providers (e.g. PG and AMB) also mark the free rounds that follow a purchase with isBuyFeature, so those rounds are true on both fields and have betAmount 0 — to count how many times players bought the feature, count only rounds where isBuyFeature is true and isFreeSpin is not true, or the PG figure comes out roughly 20 times too high

⚠️ null does not mean "did not buy" or "not a free spin"

- null means the provider does not send us this information — so we do not know whether the player bought the feature or whether it was a free spin. Only false means the provider told us "no"
- In the callback we only attach the field when it is true — if it is absent, check the table below: for a ✅ provider it means "no", for a ⚠️ or ❌ provider it means "unknown"
- Do not count null as false in your reports, or the numbers will say almost nobody ever bought the feature — which is not true

Which providers have isBuyFeature / isFreeSpin

| Provider | `isBuyFeature` | `isFreeSpin` |
| --- | --- | --- |
| PG_plus, JILI_plus, JOKER_plus, NOLIMITCITY_plus, EVOPLAY_plus, FACHAI_plus | ✅ | ✅ |
| NEXTSPIN_plusNew provider (Oct 2026), still being confirmed against real transactions | ⚠️ | ⚠️ |
| PG | ✅ | ✅ |
| AMB | ✅ | ✅ |
| 759GAMING, AFB1188_SLOT, AMBGAMING | ✅ | ✅ |
| JILI | ✅ | ❌ |
| PP | ✅ | ❌ |
| OCTOPLAYsent only on rounds where the feature was bought | ⚠️ | ❌ |
| CLOTPLAYsent on roughly half of the records | ⚠️ | ❌ |
| BOOMING, YGR, I8 | ❌ | ✅ |
| JOKERsent only on bonus rounds | ❌ | ⚠️ |
| NEXTSPINsent only on rounds that are free spins | ❌ | ⚠️ |
| BIGPOT, HOTDOG, FUNKYsent on roughly half of the records | ❌ | ⚠️ |
| SA_plus, SEXY_pluslive casino, the feature does not exist here | always false | always false |

✅ sent on every record · ⚠️ sent on some records only, treat a missing value as unknown, not false · ❌ never sent, always null

Every other provider has neither — always null

- Every other _plus provider not in the table, e.g. PRAGMATIC_plus, CQ9_plus, HABANERO_plus, HACKSAW_plus, JDB_plus, KA_plus, PLAYSON_plus, SPRIBE_plus, TADA_plus, 3OAKS_plus — these run on a different upstream system from the _plus providers in the table, even though the names end in _plus the same way
- PNG, HAB, RLX, NE, RTG, WAZ, YGG, PRG, NLC, EVP and FCG
- Other slot providers, e.g. ROYAL, LIVE22, SLOTXO, RICH88, PRETTY, SPADE, KINGMAKER
- Live casino, sports and lottery (SA, SEXY, DG, WM, SBO, BTI, UFAPLUS, HIPPO, HUAYDRAGON, LEKTHONG) — free spin / buy feature does not exist in these products

**Provider names can repeat** — JILI_plus and JILI, PG_plus and PG, NOLIMITCITY_plus and NLC, EVOPLAY_plus and EVP, NEXTSPIN_plus and NEXTSPIN are different providers on different systems, and they do not support these fields the same way. Key your reports on providerId, not the provider name

### 8. Per-round detail link

An endpoint for requesting the history page of a single round, so you can look back at what happened — a slot replay, the cards of a live casino hand, or a sports bet slip. Send the entry id you got from step 7 and the system returns a link that opens straight away. Ideal for a "view result" button on a player's history page, or for checking when a player asks. **Available for 7 days from the time of the bet** — after that the provider no longer keeps the data.

Request:

```json
POST /api/external/get-bet-detail-url
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "transactionId": "string", // optional
  "providerTransactionId": "string", // optional
  "lang": "th" // optional (default: en)
}
```

##### Request body:

- `agentId` (required): your agent ID (the owner of the private key)
- `transactionId` (optional): our-side entry id — the `id` you got from step 7
- `providerTransactionId` (optional): the provider-side entry id — the `providerTransactionId` you got from step 7 (the same id you see in the provider's back office)
- `lang` (optional): the language of the history page. `th` and `en` are supported (default: `en`) — providers that do not support choosing a language ignore it.

Note:

you must send at least one of

transactionId

or

providerTransactionId

(if you send both, the system uses

transactionId

first)

Response:

```json
{
  "provider": "BTI",
  "type": "url",
  "url": "https://api.neoapihub.com/api/external/bet-detail-view?t=eyJhbGciOi...",
  "expiresInSeconds": 900
}
```

##### Response:

- `provider` the provider this entry happened on
- `type`: currently always `url`, whether the destination is the provider's own page or one we assemble — you can open the link directly without branching.
- `url` the link to that round's history page. It opens without any headers, so you can hand it straight to the player — usually the provider's own page on their domain. For providers that have none, we assemble a summary page and return a link on our own domain instead.
- `expiresInSeconds` the link's lifetime in seconds — present only on links whose page we assemble ourselves, which is `900` (15 minutes). Links that are the provider's own page do not carry this field; follow that provider's rules. Either way you can request a fresh link with the same id at any time, so there is no need to keep the old one.

##### Errors you may receive:

- `BET_DETAIL_ID_REQUIRED` (400): no id was sent at all
- `TRANSACTION_NOT_FOUND` (404): no such entry
- `BET_DETAIL_TOO_OLD` (410): the round is older than the provider retains ( `retentionDays` and `roundAgeDays` are returned too)
- `BET_DETAIL_NOT_SUPPORTED` (400): this provider has no per-round detail page (a `reason` from the provider is returned too)
- `BET_DETAIL_UNAVAILABLE` (503): the provider could not answer at that moment; you can retry

**Limitations to be aware of:**

- **Up to 7 days back** — this is what we support, set by the provider that keeps data for the shortest time. Anything older returns `BET_DETAIL_TOO_OLD` (some providers keep it longer, but don't design around that)
- **Links expire** after `expiresInSeconds` — request one when the player asks to view it, not in advance to store
- **Unsettled rounds** return a summary page with status `IN_PLAY` and the bet amount instead of the full history, because the provider only writes the report once the round settles
- Most providers rate-limit these calls. Don't fire them in bursts to pull many rounds at once — call one when a player actually asks to view it.
- The link opens without authentication — you can send it to the player it belongs to, but it should not be posted publicly, since anyone with it can view that player's round until it expires

### 9. Downline API

A set of endpoints for pulling your downline's win/loss board and managing sub-agents from your own system, without opening the website — suited to anyone running a downline structure who wants their sub-agents to see their own figures inside your site.

Rules that apply to every endpoint in this section

- `agentId` must be your own agent ID (matching the private key attached). Someone else's returns `401`
- **Read operations** reach the whole downline (children, grandchildren, great-grandchildren) via `targetAgentId` ; omit it for your own
- **Write operations only reach the next level down** — calling one on a grand-sub-agent returns `403` ; their direct upline has to do it
- Sending a field that cannot be set (e.g. `canBuyQuota`, `hierarchyLevelLimit`, `privateKey`, `password`) returns `400 FIELD_NOT_ALLOWED` naming the offending field.

#### 9.1 Win/loss board by sub-agent

Totals per sub-agent, matching the "By sub-agent" tab on the site, including what you collect from them

```json
POST /api/external/get-downline-summary
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "targetAgentId": "string (optional)",
  "startDate": "2026-09-01T00:00:00Z",
  "endDate": "2026-09-20T23:59:59Z",
  "searchString": "optional",
  "skip": 0,
  "take": 50
}
```

Response:

```json
{
  "total": 4,
  "data": [
    {
      "subAgent": { "username": "ufa88g", "winningQuota": 30000 },
      "summary": { "totalBetAmount": 924.5, "totalWinLose": -308.29 }
    }
  ]
}
```

#### 9.2 Win/loss board by provider

Totals per provider, matching the "By provider" tab, including what must be paid up and the turnover

```json
POST /api/external/get-downline-provider-summary
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "targetAgentId": "string (optional)",
  "startDate": "2026-09-01T00:00:00Z",
  "endDate": "2026-09-20T23:59:59Z",
  "providerId": "optional",
  "skip": 0,
  "take": 50
}
```

Response:

```json
{
  "summaryByProvider": [
    {
      "providerName": "PG_plus",
      "allTotalBetAmount": 323,
      "allTotalCompany": 16.11
    }
  ]
}
```

#### 9.3 Sub-agent list

Fetch the downline with their remaining credit, to build a list page in your own system

```json
POST /api/external/get-sub-agents
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "targetAgentId": "string (optional)",
  "searchString": "optional",
  "skip": 0,
  "take": 50
}
```

Response:

```json
{
  "total": 62,
  "data": [
    {
      "id": "uuid",
      "username": "subagent01",
      "isActive": true,
      "winningQuota": 30000,
      "winningQuotaUsed": 5000,
      "currentHierarchyLevel": 2
    }
  ]
}
```

Note: this endpoint **does not return the sub-agent's private key** — the private key is returned once only, when the sub-agent is created.

#### 9.4 Create a sub-agent

Create a sub-agent beneath you. The credit you give is deducted from your remaining credit, and the system returns the sub-agent's private key once only.

```json
POST /api/external/create-sub-agent Content-Type: application/json Authorization: YOUR_PRIVATE_KEY { "agentId": "string", "username": "subagent02", "password": "at least 8 characters", "callbackType": "SEAMLESS | TRANSFER", "callbackUrl": "https://... (required when SEAMLESS)", "winningQuota": 10000, "providerConfigs": [ { "providerId": "uuid", "companyRate": 0.06 } ] }
```

Response:

```json
{ "id": "uuid", "username": "subagent02", "privateKey": "returned once — keep it safe", "winningQuota": 10000 }
```

- `companyRate` = (100 − % held) / 100 · you cannot hold more than you do yourself, or you get `SUBAGENT_RATE_EXCEEDS_PARENT`
- Not enough credit → `NOT_ENOUGH_WINNING_QUOTA`
- A duplicate name returns `USERNAME_ALREADY_EXISTS` (so retrying does not create a duplicate)

#### 9.5 Edit a sub-agent

Change the callback or enable/disable a direct sub-agent · passwords cannot be changed through the API — that must be done on the website

```json
POST /api/external/update-sub-agent
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "subAgentId": "uuid",
  "callbackType": "SEAMLESS | TRANSFER",
  "callbackUrl": "https://...",
  "isActive": true
}
```

Response:

```json
{
  "id": "uuid",
  "username": "subagent02",
  "isActive": true
}
```

#### 9.6 Set a sub-agent's % held

Set a sub-agent's % held per provider — a different thing from set-rtp, which adjusts a game's RTP

```json
POST /api/external/set-sub-agent-rate
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "subAgentId": "uuid",
  "providerId": "uuid",
  "companyRate": 0.06,
  "commissionRate": 0
}
```

Response:

```json
{
  "id": "uuid",
  "companyRate": 0.06
}
```

- A sub-agent cannot hold more than you → `SUBAGENT_RATE_EXCEEDS_PARENT`
- You cannot go below what their own sub-agents hold → `RATE_BELOW_SUBAGENT_HOLD` ; lower the level beneath first

#### 9.7 Add credit to a sub-agent

Transfer credit from you to a direct sub-agent. An Idempotency-Key header is required every time.

```json
POST /api/external/add-sub-agent-quota Content-Type: application/json Authorization: YOUR_PRIVATE_KEY Idempotency-Key: a value unique per entry { "agentId": "string", "subAgentId": "uuid", "winningAmount": 1000, "note": "optional" }
```

Response:

```json
{
  "success": true,
  "message": "Quota added successfully",
  "log": { "id": "uuid", "winningAmount": 1000 }
}
```

**Idempotency-Key is required** — omitting it returns `400 IDEMPOTENCY_KEY_REQUIRED` . If you get no response (dropped connection / timeout), **retry with the same key** and the system returns the original entry's result with `"replayed": true` and **does not transfer the credit again** · change the key and it is treated as a new entry and transferred again

#### 9.8 Reclaim credit from a sub-agent

Reclaim credit from a direct sub-agent. Uses the Idempotency-Key just like adding credit.

```json
POST /api/external/retrieve-sub-agent-quota Content-Type: application/json Authorization: YOUR_PRIVATE_KEY Idempotency-Key: a value unique per entry { "agentId": "string", "subAgentId": "uuid", "winningAmount": 1000, "note": "optional" }
```

Response:

```json
{
  "success": true,
  "message": "Quota retrieved successfully",
  "log": { "id": "uuid", "winningAmount": 1000 }
}
```

You cannot reclaim more than the sub-agent has left

### More APIs

Coming Soon
