Ai X Shop API Documentation

The Ai X Shop API allows developers to automate product delivery, check available coupons and stock in real-time, retrieve order details, and monitor account wallet balances using a standard HTTP-based REST interface.

Authorizing your bot

Each API key is generated via our official Telegram bot. You must include your API key in all requests passed in the X-API-Key HTTP request header.

X-API-Key: AK_YOUR_SECRET_API_KEY

Keep your key secure. If compromised, you can revoke or regenerate it anytime directly inside the bot under My Wallet > API Settings.

Making requests

All queries to the Ai X Shop Bot API must be served over HTTPS and should be presented in this form:

https://<your-domain>/api/v1/<endpoint>

We support GET and POST HTTP methods. For POST requests, payloads must be formatted as application/json.

Rate Limits & Anti-Bruteforce Policy

Security Enforced

To safeguard stock integrity, prevent bot spamming, and eliminate brute-force credential stuffing, all API endpoints are actively protected by a high-performance in-memory sliding window rate limiter.

Limit Scope	Threshold / Policy	Window	HTTP Action & Behavior
Per API Key Limit	60 requests	Per 60 Seconds (Sliding Window)	Returns `429 Too Many Requests` if threshold exceeded.
Per IP Address Limit	120 requests	Per 60 Seconds (Sliding Window)	Protects against distributed unauthenticated requests & scraping across keys.
Anti-Bruteforce Lockout	15 Failed Auth Attempts	5 Minutes IP Lockout	Any IP with ≥ 15 consecutive missing/invalid API key hits is banned for 300 seconds (5 min).

💡 Integration Best Practice: If your client encounters HTTP 429, implement an exponential backoff retry mechanism (e.g. wait 2s, 4s, 8s) before re-issuing requests.

Errors & Status Codes

Standard JSON

The API uses standard HTTP response codes to indicate success or failure. All non-2xx error responses always return a predictable JSON payload format:

{
  "success": false,
  "error": "Detailed human-readable error explanation."
}

Comprehensive Error Catalog

Status Code	Reason	Exact Error Message in JSON	How to Resolve
400 Bad Request	Invalid JSON body	`"Invalid JSON payload format."`	Verify your request body is valid JSON with `Content-Type: application/json`.
400 Bad Request	Missing / Bad Quantity	`"Quantity must be a positive integer >= 1."`	Ensure `quantity` is an integer greater than or equal to 1.
400 Bad Request	Out of Stock	`"Insufficient stock available. Requested: X, Available for API purchase: Y"`	Request fewer items or wait until restocked.
400 Bad Request	Insufficient Balance	`"Insufficient balance in both wallets. Primary (INR): Required X, Balance Y. Fallback (USDT): Required A, Balance B."`	Deposit funds into your bot wallet balance via the Telegram Bot (INR or Crypto).
401 Unauthorized	Missing Header	`"Missing API Key. Pass 'X-API-Key: <your_key>' in headers."`	Pass the `X-API-Key` header in every request.
401 Unauthorized	Invalid Key	`"Invalid or revoked API Key."`	Generate a new API key from the Telegram bot under My Wallet > API Settings.
404 Not Found	Product Not Found	`"Product/Service '<slug>' does not exist."`	Call `GET /api/v1/products` to view active valid `service_id` slugs.
404 Not Found	Order Not Found	`"Order '<order_id>' not found or unauthorized."`	Verify that the `order_id` belongs to your authenticated API account.
429 Too Many Requests	Key Rate Limit Exceeded	`"Too Many Requests. Rate limit exceeded (Max 60 requests/min per API key)."`	Throttle requests to ≤ 60 req/min per API key.
429 Too Many Requests	IP Rate Limit Exceeded	`"Too Many Requests. Rate limit exceeded (Max 120 requests/min per IP)."`	Throttle requests to ≤ 120 req/min per IP address.
429 Too Many Requests	Anti-Bruteforce Lockout	`"Too many failed authentication attempts. Access temporarily locked for 5 minutes."`	Check API Key configuration and wait 5 minutes for automatic unlock.
503 Service Unavailable	API Disabled	`"API service is currently disabled by administrator."`	Wait until the admin re-enables API access in bot settings.
500 Internal Error	Race Condition Safety Refund	`"Failed to reserve items (concurrent stock exhaustion). Your balance of X INR has been refunded."`	Automatic atomic refund executed. Retry order with available stock.

Code Examples

Ready-to-use code snippets in popular programming languages to quickly integrate the Ai X Shop API into your applications, bots, or automated vending systems:

Example Scenario:

curl -X POST https://<your-domain>/api/v1/order \
  -H "X-API-Key: AK_YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_id": "gemini", "quantity": 1}'

import requests

url = "https://<your-domain>/api/v1/order"
headers = {
    "X-API-Key": "AK_YOUR_SECRET_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "service_id": "gemini",
    "quantity": 1
}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())

const axios = require('axios');

async function placeOrder() {
  try {
    const response = await axios.post('https://<your-domain>/api/v1/order', {
      service_id: 'gemini',
      quantity: 1
    }, {
      headers: {
        'X-API-Key': 'AK_YOUR_SECRET_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    console.log('Order Success:', response.data);
  } catch (error) {
    console.error('Order Failed:', error.response ? error.response.data : error.message);
  }
}

placeOrder();

<?php
$url = 'https://<your-domain>/api/v1/order';
$apiKey = 'AK_YOUR_SECRET_API_KEY';

$payload = [
    'service_id' => 'gemini',
    'quantity' => 1
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP Code: $httpCode\n";
echo "Response: $response\n";
?>

Available methods

/api/v1/me

A simple method for testing your API key and fetching your account identity and real-time wallet balance. Returns basic user info on success.

HTTP Method

GET /api/v1/me

Response Format

{
  "chat_id": 123456789,
  "first_name": "John Doe",
  "wallet_balance": 150.50,
  "inr_balance": 150.50,
  "crypto_balance": 0.0,
  "currency": "INR"
}

/api/v1/products

Use this method to retrieve the complete catalog of active services/products, current pricing, and exact available stock units.

HTTP Method

GET /api/v1/products

Response Format

{
  "services": [
    {
      "service_id": "gemini",
      "name": "Gemini Pro 1 Month",
      "price": 10.0,
      "stock": 42
    }
  ]
}

/api/v1/order

Places an automated instant order. Costs are atomically deducted from your bot wallet balance and the purchased product codes or links are delivered in the response.

HTTP Method

POST /api/v1/order

Parameters (JSON)

Field	Type	Required	Description
`service_id`	String	Yes	Unique product/coupon slug (e.g. `gemini`).
`quantity`	Integer	Yes	Number of items to purchase (minimum `1`).

Response Format (Success)

{
  "success": true,
  "order_id": "TRXN9A2K7LM4PQ",
  "service_id": "gemini",
  "quantity": 1,
  "total_cost": 10.0,
  "new_balance": 140.50,
  "products": [
    "https://g.co/coupon/sample123"
  ]
}

/api/v1/orders

Fetch your complete order history. Supports optional pagination parameters page and limit.

Parameters (Query String)

Parameter	Type	Default	Description
`page`	Integer	1	Page number.
`limit`	Integer	50	Number of orders per page (max 200).

Response Format

{
  "success": true,
  "page": 1,
  "limit": 50,
  "total_orders": 120,
  "total_pages": 3,
  "orders": [
    {
      "order_id": "TRXN9A2K7LM4PQ",
      "service": "Gemini Pro",
      "quantity": 1,
      "amount": 10.0,
      "status": "completed",
      "delivered_products": ["https://g.co/coupon/sample123"],
      "created_at": "2026-09-04 16:30:00"
    }
  ]
}

/api/v1/order/{id}

Fetch details and delivered product codes or links of a specific order by Order ID.

HTTP Method

GET /api/v1/order/{id}

Path Parameters

Parameter	Type	Required	Description
`id`	String	Yes	The unique Order ID (e.g. `TRXN9A2K7LM4PQ`).

Response Format

{
  "success": true,
  "order": {
    "order_id": "TRXN9A2K7LM4PQ",
    "service": "Gemini Pro",
    "quantity": 1,
    "amount": 10.0,
    "status": "completed",
    "delivered_products": [
      "https://g.co/coupon/sample123"
    ],
    "created_at": "2026-09-04 16:30:00"
  }
}

/api/v1/stats

Fetch comprehensive account statistics including deposits, total spends, and per-product sales breakdown. Supports optional start and end date filters.

HTTP Method

GET /api/v1/stats

Parameters (Query String - Optional)

Parameter	Type	Example	Description
`start`	String	`2026-07-09-10:00-AM`	Filter records starting from this datetime (also accepts `YYYY-MM-DD`).
`end`	String	`2026-07-09-02:00-PM`	Filter records up to this datetime.

Response Format

{
  "success": true,
  "deposits": {
    "today": 0.0,
    "7d": 500.0,
    "30d": 1200.0,
    "365d": 3500.0,
    "all_time": 3500.0
  },
  "sales": {
    "today": 100.0,
    "7d": 450.0,
    "30d": 980.0,
    "365d": 2800.0,
    "all_time": 2800.0
  },
  "products_breakdown": [
    {
      "service_id": "gemini",
      "name": "Gemini Pro 1 Month",
      "quantity_sold": 10,
      "revenue": 100.0
    },
    {
      "service_id": "chatgpt",
      "name": "ChatGPT Plus",
      "quantity_sold": 2,
      "revenue": 20.0
    }
  ]
}

Interactive API Playground

Execute real-time test queries against your live backend.

API Key (X-API-Key) *

Method / Endpoint *

Ready

Response Ready

Click "Execute Request" to see output...