Документация для разработчиков

Gramix API v1

Используйте это руководство как контракт при разработке серверной интеграции.

Общая информация

Публичный API позволяет получать баланс, пополнять кошелек и покупать Telegram Stars, Telegram Premium и GRAM.

Base URL

text

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

Формат данных

Тело запроса и ответы API используют application/json.
Денежные значения передаются строками с четырьмя знаками после точки. Для точных расчетов используйте decimal-типы или храните значения как строки.
Даты в webhook передаются в формате ISO 8601. Не полагайтесь на неизвестные поля JSON.

Список методов

Метод	Endpoint	Назначение	HTTP-код
`GET`	`/api/v1/wallets/balance`	Возвращает текущий баланс.	`200`
`POST`	`/api/v1/wallets/balance`	Создает или возвращает address и memo для пополнения в сети TON.	`201`
`POST`	`/api/v1/purchase/stars`	Покупает от 50 до 1 000 000 Telegram Stars для указанного Telegram username.	`201`
`POST`	`/api/v1/purchase/premium/{duration}`	Покупает Telegram Premium на 3, 6 или 12 месяцев.	`201`
`POST`	`/api/v1/purchase/gram`	Покупает и отправляет от 1 до 10 000 GRAM указанному Telegram-получателю. Для paymentCurrency принимается только значение "gram" в нижнем регистре; "usdt" для этого endpoint недоступен. Значение gram должно быть целым числом от 1 до 10 000; дробные значения не принимаются.	`201`
`GET`	`/api/v1/orders`	Возвращает API-заказы пользователя от новых к старым.	`200`
`GET`	`/api/v1/orders/{id}`	Возвращает один API-заказ по его UUID.	`200`

Авторизация

Все методы требуют активный API-ключ, переданный в HTTP-заголовке x-api-key.

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'

Если заголовок отсутствует, ключ неверен, отозван или неактивен, API возвращает 401 Unauthorized.

API-ключ является секретом. Не храните его в репозитории, URL, query-параметрах, логах и общедоступном клиентском коде.

Общий формат ответа

Успешный ответ

Успешный ответ содержит statusCode и data. Для POST-запросов API возвращает HTTP-код 201.

json

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

Ответ с ошибкой

Ошибки содержат statusCode и человекочитаемое message. Клиентская логика должна опираться прежде всего на HTTP-код.

json

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

Общие ошибки

HTTP-код	`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"
}

Общие схемы

PaymentCurrency

paymentCurrency определяет баланс, с которого будет оплачена покупка. Допустимы только gram и usdt в нижнем регистре.

typescript

type PaymentCurrency = "gram" | "usdt";

RecipientName

recipientName — Telegram username получателя без @. Длина от 5 до 32 символов; допустимы строчные латинские буквы, цифры и _.

text

durov
user_123
telegram_user

text

@durov
User123
1username
user-name
abc

PurchaseRequestBase

json

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

PurchaseResponse

Все методы покупки возвращают orderId, status и idempotencyKey. Новый заказ обычно имеет статус 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";

Идемпотентность покупок

Все методы /purchase/* требуют заголовок idempotency-key длиной от 8 до 64 символов.

http

idempotency-key: UNIQUE_REQUEST_KEY

Допустимы латинские буквы, цифры, _ и -. Ключ должен быть уникален в пределах API-ключа.
При сетевой ошибке повторите тот же запрос с тем же ключом. Для новой покупки используйте новый ключ.

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`

Возвращает текущий баланс.

Заголовки	Обязательно	Описание
`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`

Создает или возвращает address и memo для пополнения в сети TON.

Обязательно передайте memo в комментарии или forward payload. Без него перевод не будет автоматически зачислен.

Заголовки	Обязательно	Описание
`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"
  }
}

Зачисление выполняется асинхронно. GRAM зачисляется на gram, USDT в сети TON — на usdt.

Покупки

Покупки обрабатываются асинхронно. API проверяет запрос и баланс, создает заказ, списывает средства и возвращает orderId со статусом processing.

При переходе заказа в failed списанная сумма возвращается на тот же баланс.

POST `/api/v1/purchase/stars`

Покупает от 50 до 1 000 000 Telegram Stars для указанного Telegram username.

Заголовки	Обязательно	Описание
`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}`

Покупает Telegram Premium на 3, 6 или 12 месяцев.

Заголовки	Обязательно	Описание
`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`

Покупает и отправляет от 1 до 10 000 GRAM указанному Telegram-получателю. Для paymentCurrency принимается только значение "gram" в нижнем регистре; "usdt" для этого endpoint недоступен. Значение gram должно быть целым числом от 1 до 10 000; дробные значения не принимаются.

Заголовки	Обязательно	Описание
`x-api-key`	да	Авторизация
`idempotency-key`	да	8–64
`Accept`	нет	`application/json`
`Content-Type`	да	`application/json`

json

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

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": "gram",
    "gram": 2
  }'

json

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

Заказы

Используйте эти методы, чтобы получать заказы, созданные через публичный API.

Возвращаются только API-заказы пользователя, связанного с авторизованным API-ключом. Неизвестный или чужой заказ возвращает 404 Not Found.

GET `/api/v1/orders`

Возвращает API-заказы пользователя от новых к старым.

Заголовки	Обязательно	Описание
`x-api-key`	да	Авторизация
`Accept`	нет	`application/json`

Query-параметры

Поле	Тип	Обязательно	Ограничения
`limit`	integer	нет	1–100; default = 20
`offset`	integer	нет	≥ 0; default = 0

Ответ разбит на страницы. По полю total определяйте, нужен ли следующий запрос с увеличенным offset; за один запрос можно получить до 100 заказов.

Пример запроса

bash

curl --request GET 'https://api.gramix.io/api/v1/orders?limit=1&offset=0' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Accept: application/json'

Успешный ответ

json

{
  "statusCode": 200,
  "data": {
    "data": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "type": "stars",
        "method": "api",
        "currency": "usd",
        "amount": "1.5500",
        "status": "completed",
        "processingStatus": "completed_fragment_purchase",
        "recipientName": "telegram_user",
        "extraData": {
          "quantityCoins": 100
        },
        "transactionHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "idempotencyKey": "stars_20260716_0001",
        "createdAt": "2026-07-16T12:00:00.000Z"
      }
    ],
    "total": 42,
    "limit": 1,
    "offset": 0
  }
}

Поле	Тип	Описание
`data`	Order[]	Заказы на текущей странице.
`total`	integer	Общее число найденных заказов.
`limit`	integer	Размер страницы, применённый к запросу.
`offset`	integer	Число пропущенных заказов.

GET `/api/v1/orders/{id}`

Возвращает один API-заказ по его UUID.

Заголовки	Обязательно	Описание
`x-api-key`	да	Авторизация
`Accept`	нет	`application/json`

Пример запроса

bash

curl --request GET 'https://api.gramix.io/api/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Accept: application/json'

Успешный ответ

json

{
  "statusCode": 200,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type": "stars",
    "method": "api",
    "currency": "usd",
    "amount": "1.5500",
    "status": "completed",
    "processingStatus": "completed_fragment_purchase",
    "recipientName": "telegram_user",
    "extraData": {
      "quantityCoins": 100
    },
    "transactionHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "idempotencyKey": "stars_20260716_0001",
    "createdAt": "2026-07-16T12:00:00.000Z"
  }
}

Поля ответа

Поле	Тип	Ограничения
`id`	UUID	—
`type`	string	`stars \| gram_coins \| premium_3_month \| premium_6_month \| premium_12_month`
`method`	string	`api`
`currency`	string	`gram \| usd`
`amount`	decimal string	—
`status`	string	`created \| processing \| completed \| failed \| canceled`
`processingStatus`	string	`pending_processing \| payment_verified \| completed_fragment_purchase \| failure_verify_payment \| failure_fragment_purchase \| retrying_fragment_purchase`
`recipientName`	string	—
`extraData`	object \| null	`quantityStars \| quantityCoins`
`transactionHash`	string \| null	—
`idempotencyKey`	string \| null	—
`createdAt`	ISO 8601	—

Возможные ошибки

Если заказ не существует, не принадлежит пользователю или был создан не через API, endpoint возвращает 404 Not Found.

json

{
  "statusCode": 404,
  "message": "Not Found"
}

Webhook статуса заказа

Если для API-ключа указан webhookUrl, API отправляет POST после завершения заказа.

http

POST {webhookUrl}
Content-Type: application/json

Успешный заказ отправляет событие order.completed, неуспешный — order.failed.

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

Поле	Тип	Ограничения
`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

Верните HTTP 2xx как можно быстрее, обрабатывайте события идемпотентно и не полагайтесь на порядок их доставки.

Полный пример клиентского сценария

Проверьте баланс.
При необходимости получите реквизиты, пополните кошелек и дождитесь изменения баланса.
Создайте покупку с уникальным idempotency-key.
Сохраните orderId, status и idempotencyKey. Ответ 201 означает, что заказ принят в обработку.
Дождитесь order.completed или order.failed и сопоставьте событие по 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-ключ и настройте URL для webhook.

Управление API

Документация API

SDK для быстрой интеграции

Python SDK

Node.js SDK

Gramix API v1

Общая информация

Base URL

Формат данных

Список методов

Авторизация

Пример запроса

Общий формат ответа

Успешный ответ

Ответ с ошибкой

Общие ошибки

Общие схемы

PaymentCurrency

RecipientName

PurchaseRequestBase

PurchaseResponse

Идемпотентность покупок

Возможные ошибки

Кошельки

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

Заказы

GET /api/v1/orders

Query-параметры

Пример запроса

Успешный ответ

GET /api/v1/orders/{id}

Пример запроса

Успешный ответ

Поля ответа

Возможные ошибки

Webhook статуса заказа

Схема webhook

Требования к обработчику webhook

Полный пример клиентского сценария

Пример 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`

GET `/api/v1/orders`

GET `/api/v1/orders/{id}`