Skip to content

botsgalaxy/G2Bulk-Public-API-DOC

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

7 Commits
README.md
README.md
 
 

Repository files navigation

G2Bulk Public API Documentation

Professional gaming top-up and digital voucher services. Secure, reliable, and lightning-fast API designed for developers and businesses. Support for PUBG Mobile, Mobile Legends, Free Fire, and more.

Base URL

https://api.g2bulk.com/v1/

Last Updated: 12 March 2026

Quick Stats

  • ⚡ 99.9% Uptime
  • 🔒 Secure API Authentication
  • 🎮 150+ Games Supported
  • 🚀 <200ms Avg Response Time

Table of Contents

Authentication

API Key Authentication

Protected endpoints require authentication using an API key. Include your API key in the request header for all authenticated requests.

Request Header:

X-API-Key: your_api_key_here

Get Your API Key: Obtain an API key instantly from our Telegram Bot

⚠️ Security Warning: Multiple failed authentication attempts will trigger a permanent IP ban. Keep your API key secure and never share it publicly.

Idempotency

To prevent duplicate charges on retries or network failures, you can include an optional idempotency key with your requests.

Header: X-Idempotency-Key (UUID format)

When provided and reused within 30 minutes, the original response is returned without re-processing.

Example:

X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

User Endpoints

Get Me

Retrieve authenticated user details including balance, username, and user ID.

  • Endpoint: GET /v1/getMe
  • Authentication: Required
  • Response: 
    {
  "success": true,
  "user_id": 123456789,
  "username": "johndoe",
  "first_name": "John Doe",
  "balance": 8.74
}

Products & Categories

Get Categories

Retrieve all available product categories with product counts.

  • Endpoint: GET /v1/category
  • Authentication: Public
  • Response: 
    {
  "success": true,
  "categories": [
    {
      "id": 1,
      "title": "PUBG Mobile UC Vouchers",
      "description": "",
      "image_url": "https://example.com/pubg.png",
      "custom_emoji_id": "5368324170671202286",
      "product_count": 11
    },
    {
      "id": 2,
      "title": "Razer Gold Accounts",
      "description": "",
      "image_url": null,
      "custom_emoji_id": null,
      "product_count": 5
    }
  ]
}

Get Products

Retrieve all available products with pricing and stock information.

  • Endpoint: GET /v1/products
  • Authentication: Public
  • Response: 
    {
  "success": true,
  "products": [
    {
      "id": 1,
      "title": "60 UC Voucher",
      "description": "",
      "category_id": 1,
      "category_title": "PUBG Mobile UC Vouchers",
      "unit_price": 0.84,
      "image_url": null,
      "stock": 1006
    }
  ]
}

Get Product by ID

Retrieve detailed information about a specific product.

  • Endpoint: GET /v1/products/:id
  • Authentication: Public

Get Category Products

Retrieve all products from a specific category.

  • Endpoint: GET /v1/category/:id
  • Authentication: Public

Purchase Product

Purchase a product with specified quantity. Balance is automatically deducted.

  • Endpoint: POST /v1/products/:id/purchase
  • Authentication: Required
  • Optional Header: X-Idempotency-Key: <uuid>
  • Request Body: 
    {
  "quantity": 5
}
  • Response: 
    {
  "success": true,
  "order_id": 123,
  "transaction_id": 456,
  "product_id": 1,
  "product_title": "60 UC Voucher",
  "delivery_items": ["KEY1", "KEY2", "KEY3"]
}

Orders

Get All Orders

Retrieve paginated order history for the authenticated user, sorted by most recent.

  • Endpoint: GET /v1/orders

  • Authentication: Required

  • Query Parameters:

    Parameter Type Default Description
    page integer 1 Page number
    limit integer 50 Items per page (max 100)
    search string — Search in description, status, product title

  • Response:

    {
  "success": true,
  "orders": [
    {
      "id": 1,
      "user_id": 123456789,
      "product_id": 1,
      "product_title": "60 UC Voucher",
      "quantity": 1,
      "total_price": "0.840",
      "status": "COMPLETED",
      "description": "Purchase from G2Bulk Bot",
      "created_at": "2025-10-19T05:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 120,
    "total_pages": 3
  }
}

Get Order by ID

Retrieve detailed information about a specific order.

  • Endpoint: GET /v1/orders/:id
  • Authentication: Required

Games & Top-up Services

Get Available Games

Retrieve all supported games for top-up services.

  • Endpoint: GET /v1/games
  • Authentication: Public
  • Response: 
    {
  "success": true,
  "games": [
    {
      "id": 1,
      "code": "pubg_mobile",
      "name": "PUBG Mobile",
      "image_url": "/images/pubg_mobile.png"
    },
    {
      "id": 2,
      "code": "free_fire",
      "name": "Free Fire",
      "image_url": "/images/free_fire.png"
    }
  ]
}

Get Game Fields

Get required input fields for a specific game (e.g., user ID, server ID).

  • Endpoint: POST /v1/games/fields
  • Authentication: Public
  • Request Body: 
    {
  "game": "mlbb"
}
  • Response: 
    {
  "code": "200",
  "info": {
    "fields": ["userid", "serverid"],
    "notes": "Not available for Indonesia users"
  }
}

Get Game Servers

Get available server list for a specific game. Some games require server selection during top-up.

  • Endpoint: POST /v1/games/servers
  • Authentication: Public
  • Request Body: 
    {
  "game": "mlbb"
}
  • Response (With Servers): 
    {
  "code": "200",
  "servers": {
    "SouthEast Asia": "SouthEast Asia",
    "America": "America",
    "Europe": "Europe"
  }
}
  • Response (No Servers Required): 
    {
  "detail": {
    "code": "403",
    "message": "Game does not requires any servers"
  }
}

ℹ️ Note: A 403 response indicates the game doesn't have predefined servers, not that the game is invalid.

Check Player ID

Validate a player ID before placing an order. Returns player name if valid.

  • Endpoint: POST /v1/games/checkPlayerId
  • Authentication: Public
  • Request Body: 
    {
  "game": "mlbb",
  "user_id": "123456789",
  "server_id": "2001"
}
  • Response (Valid): 
    {
  "valid": "valid",
  "name": "John Doe",
  "openid": "41581795132966184"
}

Get Game Catalogue

Get all available denominations/packages for a specific game with current prices.

  • Endpoint: GET /v1/games/:code/catalogue
  • Authentication: Public
  • Response: 
    {
  "success": true,
  "game": {
    "code": "pubgm",
    "name": "PUBG Mobile",
    "image_url": "/images/pubgm.png"
  },
  "catalogues": [
    {
      "id": 1,
      "name": "60 UC",
      "amount": 0.88
    },
    {
      "id": 2,
      "name": "120 UC",
      "amount": 1.75
    }
  ]
}

ℹ️ Note: Prices are automatically updated every 5 minutes to ensure accuracy.

Get Estimated Completion Time

Get an estimated completion time for a specific game top-up denomination. Useful for showing users how long their order might take.

  • Endpoint: POST /v1/games/eta
  • Authentication: Public
  • Request Body: 
    {
  "game_code": "pubgm",
  "denom_id": "60"
}
  • Response: 
    {
  "success": true,
  "estimated_time": {
    "label": "less_than_5_minutes",
    "display": "Less than 5 minutes",
    "median_seconds": 187
  }
}
  • Response (Insufficient Data): 
    {
  "success": true,
  "estimated_time": {
    "label": "no_data",
    "display": "No estimate available",
    "median_seconds": null
  }
}

ETA Labels:

Label Display Text Time Range
instant Instant <30 seconds
less_than_1_minute Less than 1 minute 30s – 1 minute
less_than_2_minutes Less than 2 minutes 1 – 2 minutes
less_than_5_minutes Less than 5 minutes 2 – 5 minutes
less_than_10_minutes Less than 10 minutes 5 – 10 minutes
less_than_30_minutes Less than 30 minutes 10 – 30 minutes
more_than_30_minutes More than 30 minutes Over 30 minutes
no_data No estimate available Insufficient data

ℹ️ Note: Estimates may not be available for newly added catalogues.

Create Game Order

Place a game top-up order. Player ID is validated automatically and balance is checked before processing.

  • Endpoint: POST /v1/games/:code/order
  • Authentication: Required
  • Optional Header: X-Idempotency-Key: <uuid>
  • Request Body: 
    {
  "catalogue_name": "60 UC",
  "player_id": "5679523421",
  "server_id": "2001",
  "remark": "Optional note",
  "callback_url": "https://your-domain.com/webhook/order-status"
}
  • Response (Success): 
    {
  "success": true,
  "message": "Order created successfully. We are processing your order.",
  "order": {
    "order_id": 42,
    "game": "PUBG Mobile",
    "catalogue": "60 UC",
    "player_id": "5679523421",
    "player_name": "PlayerName",
    "price": 0.88,
    "status": "PENDING",
    "callback_url": "https://your-domain.com/webhook/order-status"
  }
}

Callback URL (Optional)

You can provide an optional callback_url to receive automatic notifications when the order status changes. This is particularly useful for automating your workflow without polling for order status.

Callback Properties:

Property Details
Method POST request with JSON body
Timeout 10 seconds
Retry Policy Single retry on timeout or failure
When Called Whenever the order status changes (PENDING → PROCESSING → COMPLETED/FAILED)

Callback Payload:

Your callback URL will receive a POST request with the following JSON structure:

{
  "order_id": 42,
  "game_code": "pubgm",
  "game_name": "PUBG Mobile",
  "player_id": "5679523421",
  "player_name": "PlayerName",
  "server_id": "2001",
  "denom_id": "60 UC",
  "price": 0.88,
  "status": "COMPLETED",
  "message": "Order completed successfully",
  "remark": "your order remark",
  "timestamp": "2024-01-15T10:30:00Z"
}

ℹ️ Important: Your callback endpoint should respond with HTTP status 200-299 within 10 seconds. Failed callbacks will be retried once. Ensure your endpoint can handle duplicate notifications gracefully.

Order Status Values

Status Description
PENDING Order created and waiting to be processed
PROCESSING Order is currently being processed
COMPLETED Order completed successfully, items delivered
FAILED Order failed, balance automatically refunded

Check Order Status

Check the current status of a specific game order.

  • Endpoint: POST /v1/games/order/status
  • Authentication: Required
  • Request Body: 
    {
  "order_id": 42,
  "game": "pubgm"
}

Get All Game Orders

Retrieve paginated game top-up order history for the authenticated user, sorted by most recent.

  • Endpoint: GET /v1/games/orders

  • Authentication: Required

  • Query Parameters:

    Parameter Type Default Description
    page integer 1 Page number
    limit integer 50 Items per page (max 100)
    search string — Search in game code, nickname, player ID, status, remark

  • Response:

    {
  "success": true,
  "orders": [
    {
      "order_id": 42,
      "game_code": "pubgm",
      "game_name": "PUBG Mobile",
      "player_id": "5123456789",
      "player_name": "PlayerOne",
      "server_id": "",
      "denom_id": "60",
      "price": 0.84,
      "status": "completed",
      "is_refunded": false,
      "remark": "",
      "message": "Top-up successful",
      "callback_url": null,
      "created_at": "2025-10-19T05:30:00Z",
      "completed_at": "2025-10-19T05:31:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 85,
    "total_pages": 2
  }
}

Legacy Endpoints (Disabled)

⚠️ Disabled: These endpoints have been disabled. Use the unified /v1/games/* endpoints for all game top-up operations.

  • GET /v1/topup/freeFire/offers - Get available Free Fire top-up offers
  • GET /v1/topup/pubgMobile/offers - Get available PUBG Mobile top-up offers
  • POST /v1/topup/pubgMobile/checkPlayerId - Validate PUBG Mobile player ID
  • POST /v1/topup/pubgMobile/purchase - Purchase PUBG Mobile top-up
  • GET /v1/topup/pubgMobile/status - Check PUBG Mobile top-up status
  • GET /v1/topups - Get all PUBG Mobile top-up history

Transactions

Get Transactions

Retrieve paginated transaction history including balance additions, charges, and refunds, sorted by most recent.

  • Endpoint: GET /v1/transactions

  • Authentication: Required

  • Query Parameters:

    Parameter Type Default Description
    page integer 1 Page number
    limit integer 50 Items per page (max 100)
    search string — Search in description, transaction type, status

  • Response:

    {
  "success": true,
  "data": [
    {
      "id": 45,
      "user_id": 123456789,
      "transaction_type": "charge_balance",
      "amount": "1.126",
      "balance_before": "10.000",
      "balance_after": "8.874",
      "status": "success",
      "description": "Purchase PUBG Mobile 60 UC",
      "created_at": "2025-10-19T05:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 200,
    "total_pages": 4
  }
}

Transaction Types

Type Description
add_balance Balance added (manual addition or refund)
charge_balance Balance deducted (purchase or top-up)

Plans & Subscriptions

Users can subscribe to recurring plans. Balance is deducted when creating a subscription, and only one active subscription is allowed at a time.

Get All Plans

Retrieve all available subscription plans with pricing and duration details.

  • Endpoint: GET /v1/plans
  • Authentication: Public
  • Response: 
    {
  "success": true,
  "plans": [
    {
      "ID": 1,
      "CreatedAt": "2025-11-27T10:00:00Z",
      "UpdatedAt": "2025-11-27T10:00:00Z",
      "DeletedAt": null,
      "name": "Basic Plan",
      "description": "Basic subscription with standard features",
      "price": 9.99,
      "duration_days": 30
    },
    {
      "ID": 2,
      "CreatedAt": "2025-11-27T10:00:00Z",
      "UpdatedAt": "2025-11-27T10:00:00Z",
      "DeletedAt": null,
      "name": "Premium Plan",
      "description": "Premium subscription with all features",
      "price": 29.99,
      "duration_days": 30
    }
  ]
}

Get Plan by ID

Retrieve detailed information about a specific subscription plan.

  • Endpoint: GET /v1/plans/:id
  • Authentication: Public
  • Response: 
    {
  "success": true,
  "plan": {
    "ID": 1,
    "CreatedAt": "2025-11-27T10:00:00Z",
    "UpdatedAt": "2025-11-27T10:00:00Z",
    "DeletedAt": null,
    "name": "Basic Plan",
    "description": "Basic subscription with standard features",
    "price": 9.99,
    "duration_days": 30
  }
}

Create Subscription

Create a subscription for the authenticated user. Plan price is automatically deducted.

  • Endpoint: POST /v1/subscriptions
  • Authentication: Required
  • Request Body: 
    {
  "plan_id": 1
}
  • Response: 
    {
  "success": true,
  "subscription": {
    "ID": 1,
    "CreatedAt": "2025-11-27T12:00:00Z",
    "UpdatedAt": "2025-11-27T12:00:00Z",
    "DeletedAt": null,
    "user_id": 123456,
    "plan_id": 1,
    "start_date": "2025-11-27T12:00:00Z",
    "end_date": "2025-12-27T12:00:00Z",
    "status": "active",
    "plan": {
      "ID": 1,
      "name": "Basic Plan",
      "description": "Basic subscription with standard features",
      "price": 9.99,
      "duration_days": 30
    }
  }
}

⚠️ Requirements:

  • User must have sufficient balance
  • Only one active subscription per user
  • A transaction record is automatically created

Get User Subscriptions

Retrieve all subscriptions (past and present) for the authenticated user.

  • Endpoint: GET /v1/subscriptions
  • Authentication: Required
  • Response: 
    {
  "success": true,
  "subscriptions": [
    {
      "ID": 1,
      "CreatedAt": "2025-11-27T12:00:00Z",
      "UpdatedAt": "2025-11-27T12:00:00Z",
      "DeletedAt": null,
      "user_id": 123456,
      "plan_id": 1,
      "start_date": "2025-11-27T12:00:00Z",
      "end_date": "2025-12-27T12:00:00Z",
      "status": "active",
      "plan": {
        "ID": 1,
        "name": "Basic Plan",
        "price": 9.99,
        "duration_days": 30
      }
    }
  ]
}

Get Active Subscription

Retrieve the currently active subscription for the authenticated user.

  • Endpoint: GET /v1/subscriptions/active
  • Authentication: Required
  • Response (Active Found): 
    {
  "success": true,
  "subscription": {
    "ID": 1,
    "user_id": 123456,
    "plan_id": 1,
    "start_date": "2025-11-27T12:00:00Z",
    "end_date": "2025-12-27T12:00:00Z",
    "status": "active",
    "plan": {
      "ID": 1,
      "name": "Basic Plan",
      "price": 9.99,
      "duration_days": 30
    }
  }
}
  • Response (No Active Subscription): 
    {
  "success": false,
  "message": "No active subscription found"
}

Cancel Subscription

Cancel a subscription. Status changes to cancelled; no refund is issued.

  • Endpoint: POST /v1/subscriptions/:id/cancel
  • Authentication: Required
  • Response: 
    {
  "success": true,
  "message": "Subscription cancelled successfully"
}

⚠️ Note: Cancelling a subscription does not provide a refund and the subscription cannot be reactivated.

Rate Limiting

  • Rate Limit: 1000 requests per 10 seconds per API key

⚠️ Warning: Multiple failed requests to protected endpoints will trigger a permanent IP ban. Ensure your API key is valid before making requests.

Best Practices

  • Implement exponential backoff for retries
  • Cache responses when appropriate
  • Monitor your API usage regularly
  • Use batch operations when available

Error Handling

HTTP Status Codes

Status Code Meaning Description
200 OK Request successful
400 Bad Request Invalid request format or parameters
401 Unauthorized Authentication failed or API key invalid
404 Not Found Requested resource does not exist
429 Too Many Requests Rate limit exceeded
500 Internal Server Error An unexpected error occurred

Error Response Format

{
  "success": false,
  "message": "Detailed error message",
  "error_code": "ERROR_CODE_HERE"
}

Support

For any questions, issues, or API key requests, please contact:

© 2026 G2Bulk API. Professional gaming top-up services. Built with security and reliability in mind.

This documentation is subject to updates. Always check for the latest version to ensure compatibility with the API.

About

Professional gaming top-up and digital voucher services. Secure, reliable, and lightning-fast API designed for developers and businesses. Support for PUBG Mobile, Mobile Legends, Free Fire, and more.

api.g2bulk.com

Topics

api games topup g2bulk

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors