डेवलपर दस्तावेज़

Gramix API v1

सर्वर-साइड इंटीग्रेशन बनाते समय इस गाइड को API कॉन्ट्रैक्ट के रूप में इस्तेमाल करें।

सामान्य जानकारी

सार्वजनिक API से बैलेंस प्राप्त करना, वॉलेट टॉप-अप करना और Telegram Stars, Telegram Premium व GRAM खरीदना संभव है।

Base URL

text

https://api.gramix.io/api/v1

डेटा फ़ॉर्मैट

API रिक्वेस्ट body और रिस्पॉन्स application/json का इस्तेमाल करते हैं।
धनराशि के मान चार दशमलव स्थानों वाले string के रूप में भेजे जाते हैं। सटीक गणना के लिए decimal type का इस्तेमाल करें या मानों को string के रूप में रखें।
Webhook में तिथियाँ ISO 8601 फ़ॉर्मैट में भेजी जाती हैं। अज्ञात JSON field पर निर्भर न रहें।

मेथड की सूची

मेथड	Endpoint	उद्देश्य	HTTP code
`GET`	`/api/v1/wallets/balance`	मौजूदा बैलेंस लौटाता है।	`200`
`POST`	`/api/v1/wallets/balance`	TON network पर टॉप-अप के लिए address और memo बनाता है या मौजूदा मान लौटाता है।	`201`
`POST`	`/api/v1/purchase/stars`	दिए गए Telegram username के लिए 50 से 1,000,000 Telegram Stars खरीदता है।	`201`
`POST`	`/api/v1/purchase/premium/{duration}`	3, 6 या 12 महीने का Telegram Premium खरीदता है।	`201`
`POST`	`/api/v1/purchase/gram`	दिए गए Telegram प्राप्तकर्ता के लिए 1 से 10,000 GRAM खरीदकर भेजता है।	`201`

प्रमाणीकरण

सभी मेथड के लिए सक्रिय API कुंजी आवश्यक है, जिसे x-api-key HTTP header में भेजा जाता है।

http

x-api-key: YOUR_API_KEY

रिक्वेस्ट का उदाहरण

bash

curl --request GET 'https://api.gramix.io/api/v1/wallets/balance' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Accept: application/json'

Header न होने, कुंजी ग़लत होने, रद्द होने या निष्क्रिय होने पर API 401 Unauthorized लौटाता है।

API कुंजी गोपनीय है। इसे repository, URL, query parameter, log या सार्वजनिक client code में न रखें।

सामान्य रिस्पॉन्स फ़ॉर्मैट

सफ़ल रिस्पॉन्स

सफ़ल रिस्पॉन्स में statusCode और data होते हैं। POST रिक्वेस्ट के लिए API HTTP 201 लौटाता है।

json

{
  "statusCode": 200,
  "data": {}
}

एरर रिस्पॉन्स

एरर रिस्पॉन्स में statusCode और पठनीय message होते हैं। Client logic को पहले HTTP status code पर निर्भर करना चाहिए।

json

{
  "statusCode": 400,
  "message": "Idempotency-Key header is required"
}

सामान्य एरर

HTTP code	`message`
`400`	`Bad Request`
`401`	`Unauthorized`
`403`	`Insufficient balance`
`404`	`Not Found`
`405`	`Method Not Allowed`
`500`	`Internal server error`

http

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "statusCode": 401,
  "message": "Unauthorized"
}

http

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "statusCode": 403,
  "message": "Insufficient balance"
}

सामान्य Schema

PaymentCurrency

paymentCurrency तय करता है कि खरीदारी का भुगतान किस बैलेंस से होगा। केवल lowercase gram और usdt स्वीकार्य हैं।

typescript

type PaymentCurrency = "gram" | "usdt";

RecipientName

recipientName, @ के बिना प्राप्तकर्ता का Telegram username है। लंबाई 5 से 32 अक्षर; केवल lowercase Latin letter, अंक और _ की अनुमति है।

text

durov
user_123
telegram_user

text

@durov
User123
1username
user-name
abc

PurchaseRequestBase

json

{
  "recipientName": "telegram_user",
  "paymentCurrency": "usdt"
}

PurchaseResponse

सभी purchase method orderId, status और idempotencyKey लौटाते हैं। नए ऑर्डर का status आम तौर पर processing होता है।

json

{
  "statusCode": 201,
  "data": {
    "orderId": "7ba77616-7706-4215-9e6f-b6c67e4df292",
    "status": "processing",
    "idempotencyKey": "order_20260713_0001"
  }
}

typescript

type OrderStatus = "created" | "processing" | "completed" | "failed" | "canceled";

खरीदारी की idempotency

सभी /purchase/* method के लिए 8 से 64 अक्षर लंबा idempotency-key header आवश्यक है।

http

idempotency-key: UNIQUE_REQUEST_KEY

Latin letter, अंक, _ और - की अनुमति है। कुंजी एक API कुंजी के दायरे में unique होनी चाहिए।
Network error पर वही रिक्वेस्ट उसी कुंजी के साथ दोबारा भेजें। नई खरीदारी के लिए नई कुंजी का इस्तेमाल करें।

text

order_20260713_0001
01J2Y5VN7CV8ZQ7DPZ9J0P6E4M
client-req-12345678

संभावित एरर

json

{
  "statusCode": 400,
  "message": "Idempotency-Key header is required"
}

json

{
  "statusCode": 400,
  "message": "Idempotency-Key must be between 8 and 64 characters"
}

json

{
  "statusCode": 400,
  "message": "Idempotency-Key contains invalid characters"
}

वॉलेट

GET `/api/v1/wallets/balance`

मौजूदा बैलेंस लौटाता है।

Header	आवश्यक	विवरण
`x-api-key`	हाँ	प्रमाणीकरण
`Accept`	नहीं	`application/json`

रिक्वेस्ट का उदाहरण

bash

curl --request GET 'https://api.gramix.io/api/v1/wallets/balance' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Accept: application/json'

json

{
  "statusCode": 200,
  "data": {
    "gram": "14.2500",
    "usdt": "125.5000"
  }
}

POST `/api/v1/wallets/balance`

TON network पर टॉप-अप के लिए address और memo बनाता है या मौजूदा मान लौटाता है।

Transaction comment या forward payload में memo अवश्य भेजें। इसके बिना transfer अपने-आप credit नहीं होगा।

Header	आवश्यक	विवरण
`x-api-key`	हाँ	प्रमाणीकरण
`Accept`	नहीं	`application/json`

bash

curl --request POST 'https://api.gramix.io/api/v1/wallets/balance' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Accept: application/json'

json

{
  "statusCode": 201,
  "data": {
    "address": "UQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "memo": "a1b2c3d4e5f6g7h8"
  }
}

Credit असिंक्रोनस रूप से होता है। GRAM, gram में और TON network पर USDT, usdt में credit होता है।

अनुशंसित टॉप-अप फ़्लो

POST /wallets/balance
Transaction comment या forward payload में memo अवश्य भेजें। इसके बिना transfer अपने-आप credit नहीं होगा।
GET /wallets/balance

खरीदारी

खरीदारी असिंक्रोनस रूप से process होती है। API रिक्वेस्ट और बैलेंस की जाँच करता है, ऑर्डर बनाकर राशि काटता है और processing status के साथ orderId लौटाता है।

ऑर्डर failed होने पर काटी गई राशि उसी बैलेंस में वापस हो जाती है।

POST `/api/v1/purchase/stars`

दिए गए Telegram username के लिए 50 से 1,000,000 Telegram Stars खरीदता है।

Header	आवश्यक	विवरण
`x-api-key`	हाँ	प्रमाणीकरण
`idempotency-key`	हाँ	8–64
`Accept`	नहीं	`application/json`
`Content-Type`	हाँ	`application/json`

json

{
  "recipientName": "telegram_user",
  "paymentCurrency": "usdt",
  "stars": 500
}

bash

curl --request POST 'https://api.gramix.io/api/v1/purchase/stars' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'idempotency-key: stars_20260713_0001' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "recipientName": "telegram_user",
    "paymentCurrency": "usdt",
    "stars": 500
  }'

json

{
  "statusCode": 201,
  "data": {
    "orderId": "7ba77616-7706-4215-9e6f-b6c67e4df292",
    "status": "processing",
    "idempotencyKey": "stars_20260713_0001"
  }
}

POST `/api/v1/purchase/premium/{duration}`

3, 6 या 12 महीने का Telegram Premium खरीदता है।

Header	आवश्यक	विवरण
`x-api-key`	हाँ	प्रमाणीकरण
`idempotency-key`	हाँ	8–64
`Accept`	नहीं	`application/json`
`Content-Type`	हाँ	`application/json`

json

{
  "recipientName": "telegram_user",
  "paymentCurrency": "gram"
}

bash

curl --request POST 'https://api.gramix.io/api/v1/purchase/premium/6' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'idempotency-key: premium_6_20260713_0001' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "recipientName": "telegram_user",
    "paymentCurrency": "gram"
  }'

json

{
  "statusCode": 201,
  "data": {
    "orderId": "18ca3cce-8441-4de6-874a-fd34792ae1b5",
    "status": "processing",
    "idempotencyKey": "premium_6_20260713_0001"
  }
}

json

{
  "statusCode": 400,
  "message": "Invalid premium duration. Allowed values: 3, 6, 12"
}

POST `/api/v1/purchase/gram`

दिए गए Telegram प्राप्तकर्ता के लिए 1 से 10,000 GRAM खरीदकर भेजता है।

Header	आवश्यक	विवरण
`x-api-key`	हाँ	प्रमाणीकरण
`idempotency-key`	हाँ	8–64
`Accept`	नहीं	`application/json`
`Content-Type`	हाँ	`application/json`

json

{
  "recipientName": "telegram_user",
  "paymentCurrency": "usdt",
  "gram": 2.5
}

bash

curl --request POST 'https://api.gramix.io/api/v1/purchase/gram' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'idempotency-key: gram_20260713_0001' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "recipientName": "telegram_user",
    "paymentCurrency": "usdt",
    "gram": 2.5
  }'

json

{
  "statusCode": 201,
  "data": {
    "orderId": "882dd8ca-5d68-4b85-bb26-c25ee38d9a98",
    "status": "processing",
    "idempotencyKey": "gram_20260713_0001"
  }
}

ऑर्डर स्टेटस webhook

API कुंजी के लिए webhookUrl सेट होने पर API ऑर्डर पूरा होने के बाद POST भेजता है।

http

POST {webhookUrl}
Content-Type: application/json

सफ़ल ऑर्डर order.completed event और असफ़ल ऑर्डर order.failed event भेजता है।

json

{
  "event": "order.completed",
  "orderId": "7ba77616-7706-4215-9e6f-b6c67e4df292",
  "status": "completed",
  "processingStatus": "completed_fragment_purchase",
  "type": "stars",
  "amount": "7.6500",
  "currency": "usd",
  "recipientName": "telegram_user",
  "createdAt": "2026-07-13T10:20:30.000Z"
}

json

{
  "event": "order.failed",
  "orderId": "7ba77616-7706-4215-9e6f-b6c67e4df292",
  "status": "failed",
  "processingStatus": "failure_fragment_purchase",
  "type": "stars",
  "amount": "7.6500",
  "currency": "usd",
  "recipientName": "telegram_user",
  "createdAt": "2026-07-13T10:20:30.000Z"
}

Webhook schema

फ़ील्ड	टाइप	सीमाएँ
`event`	string	`order.completed \| order.failed`
`orderId`	UUID	—
`status`	string	`completed \| failed`
`type`	string	`stars \| gram \| premium_*`
`amount`	decimal(4)	—
`currency`	string	`gram \| usd`
`recipientName`	string	—
`createdAt`	ISO 8601	—

Webhook handler की आवश्यकताएँ

HTTP 2xx जल्द से जल्द लौटाएँ, event को idempotent रूप से process करें और उनके पहुँचने के क्रम पर निर्भर न रहें।

क्लाइंट फ़्लो का पूरा उदाहरण

बैलेंस की जाँच करें।
ज़रूरत होने पर टॉप-अप विवरण प्राप्त करें, वॉलेट टॉप-अप करें और बैलेंस बदलने की प्रतीक्षा करें।
एक unique idempotency-key के साथ खरीदारी बनाएँ।
orderId, status और idempotencyKey सहेजें। 201 रिस्पॉन्स का मतलब है कि ऑर्डर process करने के लिए स्वीकार हो गया है।
order.completed या order.failed की प्रतीक्षा करें और event को orderId से मिलाएँ।

http

GET /api/v1/wallets/balance
x-api-key: YOUR_API_KEY

http

POST /api/v1/wallets/balance
x-api-key: YOUR_API_KEY

http

POST /api/v1/purchase/stars
x-api-key: YOUR_API_KEY
idempotency-key: order_20260713_0001
Content-Type: application/json

{
  "recipientName": "telegram_user",
  "paymentCurrency": "usdt",
  "stars": 500
}

TypeScript क्लाइंट का उदाहरण

typescript

type SuccessResponse<T> = {
  statusCode: number;
  data: T;
};

type ApiError = {
  statusCode: number;
  message: string;
};

type PurchaseResponse = {
  orderId: string;
  status: "created" | "processing" | "completed" | "failed" | "canceled";
  idempotencyKey: string;
};

type WalletBalance = {
  gram: string;
  usdt: string;
};

const BASE_URL = "https://api.gramix.io";

async function apiRequest<T>(path: string, apiKey: string, init: RequestInit = {}): Promise<T> {
  const response = await fetch(
    `${BASE_URL}${path}`,
    {
      ...init,
      headers: {
        Accept: "application/json",
        "x-api-key": apiKey,
        ...(init.body ? { "Content-Type": "application/json" } : {}),
        ...init.headers,
      },
    },
  );

  const payload = (await response.json()) as SuccessResponse<T> | ApiError;

  if (!response.ok) {
    const error = payload as ApiError;
    throw new Error(`[${error.statusCode}] ${error.message}`);
  }

  return (payload as SuccessResponse<T>).data;
}

export function getBalance(apiKey: string): Promise<WalletBalance> {
  return apiRequest<WalletBalance>("/api/v1/wallets/balance", apiKey);
}

export function purchaseStars(
  apiKey: string,
  idempotencyKey: string,
  input: {
    recipientName: string;
    paymentCurrency: "gram" | "usdt";
    stars: number;
  },
): Promise<PurchaseResponse> {
  return apiRequest<PurchaseResponse>("/api/v1/purchase/stars", apiKey, {
    method: "POST",
    headers: { "idempotency-key": idempotencyKey },
    body: JSON.stringify(input),
  });
}

इंटीग्रेशन शुरू करने के लिए तैयार हैं?

API कुंजी बनाएँ और webhook URL कॉन्फ़िगर करें।

API प्रबंधन

API दस्तावेज़

Gramix API v1

सामान्य जानकारी

Base URL

डेटा फ़ॉर्मैट

मेथड की सूची

प्रमाणीकरण

रिक्वेस्ट का उदाहरण

सामान्य रिस्पॉन्स फ़ॉर्मैट

सफ़ल रिस्पॉन्स

एरर रिस्पॉन्स

सामान्य एरर

सामान्य Schema

PaymentCurrency

RecipientName

PurchaseRequestBase

PurchaseResponse

खरीदारी की idempotency

संभावित एरर

वॉलेट

GET /api/v1/wallets/balance

रिक्वेस्ट का उदाहरण

POST /api/v1/wallets/balance

अनुशंसित टॉप-अप फ़्लो

खरीदारी

POST /api/v1/purchase/stars

POST /api/v1/purchase/premium/{duration}

POST /api/v1/purchase/gram

ऑर्डर स्टेटस webhook

Webhook schema

Webhook handler की आवश्यकताएँ

क्लाइंट फ़्लो का पूरा उदाहरण

TypeScript क्लाइंट का उदाहरण

GET `/api/v1/wallets/balance`

POST `/api/v1/wallets/balance`

POST `/api/v1/purchase/stars`

POST `/api/v1/purchase/premium/{duration}`

POST `/api/v1/purchase/gram`