Documentación para desarrolladores

Gramix API v1

Utiliza esta guía como contrato para desarrollar tu integración del lado del servidor.

Información general

La API pública permite consultar el saldo, recargar la billetera y comprar Telegram Stars, Telegram Premium y GRAM.

URL base

text

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

Formato de los datos

Los cuerpos de las solicitudes y las respuestas de la API utilizan application/json.
Los valores monetarios se envían como cadenas con cuatro decimales. Para realizar cálculos exactos, utiliza tipos decimales o conserva los valores como cadenas.
Las fechas de los webhooks utilizan el formato ISO 8601. No dependas de campos JSON desconocidos.

Métodos disponibles

Método	Endpoint	Finalidad	Estado HTTP
`GET`	`/api/v1/wallets/balance`	Devuelve el saldo actual.	`200`
`POST`	`/api/v1/wallets/balance`	Crea o devuelve la address y el memo necesarios para recargar la billetera en la red TON.	`201`
`POST`	`/api/v1/purchase/stars`	Compra entre 50 y 1.000.000 de Telegram Stars para el nombre de usuario de Telegram indicado.	`201`
`POST`	`/api/v1/purchase/premium/{duration}`	Compra Telegram Premium por 3, 6 o 12 meses.	`201`
`POST`	`/api/v1/purchase/gram`	Compra y envía entre 1 y 10.000 GRAM al destinatario de Telegram indicado. Solo se acepta "gram" en minúsculas como paymentCurrency; "usdt" no está disponible para este endpoint. El valor de gram debe ser un número entero entre 1 y 10.000; no se aceptan valores decimales.	`201`
`GET`	`/api/v1/orders`	Devuelve los pedidos de API del usuario del más reciente al más antiguo.	`200`
`GET`	`/api/v1/orders/{id}`	Devuelve un pedido de API por su UUID.	`200`

Autenticación

Todos los métodos requieren una clave de API activa enviada en el encabezado HTTP x-api-key.

http

x-api-key: YOUR_API_KEY

Ejemplo de solicitud

bash

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

Si falta el encabezado o la clave no es válida, fue revocada o está inactiva, la API devuelve 401 Unauthorized.

La clave de API es secreta. No la guardes en repositorios, URL, parámetros de consulta, registros ni código de cliente de acceso público.

Formato general de las respuestas

Respuesta correcta

Una respuesta correcta contiene statusCode y data. Las solicitudes POST devuelven el estado HTTP 201.

json

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

Respuesta de error

Los errores contienen statusCode y un message comprensible. La lógica del cliente debe basarse principalmente en el código de estado HTTP.

json

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

Errores comunes

Estado 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"
}

Esquemas comunes

PaymentCurrency

paymentCurrency selecciona el saldo utilizado para pagar la compra. Solo se aceptan gram y usdt en minúsculas.

typescript

type PaymentCurrency = "gram" | "usdt";

RecipientName

recipientName es el nombre de usuario de Telegram del destinatario sin @. Debe tener entre 5 y 32 caracteres y puede contener letras latinas minúsculas, números y _.

text

durov
user_123
telegram_user

text

@durov
User123
1username
user-name
abc

PurchaseRequestBase

json

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

PurchaseResponse

Todos los métodos de compra devuelven orderId, status e idempotencyKey. Un pedido nuevo suele tener el estado 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";

Idempotencia de las compras

Todos los métodos /purchase/* requieren un encabezado idempotency-key de entre 8 y 64 caracteres.

http

idempotency-key: UNIQUE_REQUEST_KEY

Se admiten letras latinas, números, _ y -. La clave debe ser única para cada clave de API.
Tras un error de red, repite la misma solicitud con la misma clave. Utiliza una clave nueva para una compra nueva.

text

order_20260713_0001
01J2Y5VN7CV8ZQ7DPZ9J0P6E4M
client-req-12345678

Posibles errores

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"
}

Billeteras

GET `/api/v1/wallets/balance`

Devuelve el saldo actual.

Encabezados	Obligatorio	Descripción
`x-api-key`	sí	Autenticación
`Accept`	no	`application/json`

Ejemplo de solicitud

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`

Crea o devuelve la address y el memo necesarios para recargar la billetera en la red TON.

Incluye siempre el memo en el comentario de la transacción o en el forward payload. Sin él, la transferencia no se acreditará automáticamente.

Encabezados	Obligatorio	Descripción
`x-api-key`	sí	Autenticación
`Accept`	no	`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"
  }
}

Las recargas se acreditan de forma asíncrona. GRAM se acredita en gram y USDT en la red TON se acredita en usdt.

Flujo de recarga recomendado

POST /wallets/balance
Incluye siempre el memo en el comentario de la transacción o en el forward payload. Sin él, la transferencia no se acreditará automáticamente.
GET /wallets/balance

Compras

Las compras se procesan de forma asíncrona. La API valida la solicitud y el saldo, crea el pedido, descuenta los fondos y devuelve orderId con el estado processing.

Si el pedido pasa al estado failed, el importe cobrado se devuelve al mismo saldo.

POST `/api/v1/purchase/stars`

Compra entre 50 y 1.000.000 de Telegram Stars para el nombre de usuario de Telegram indicado.

Encabezados	Obligatorio	Descripción
`x-api-key`	sí	Autenticación
`idempotency-key`	sí	8–64
`Accept`	no	`application/json`
`Content-Type`	sí	`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}`

Compra Telegram Premium por 3, 6 o 12 meses.

Encabezados	Obligatorio	Descripción
`x-api-key`	sí	Autenticación
`idempotency-key`	sí	8–64
`Accept`	no	`application/json`
`Content-Type`	sí	`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`

Compra y envía entre 1 y 10.000 GRAM al destinatario de Telegram indicado. Solo se acepta "gram" en minúsculas como paymentCurrency; "usdt" no está disponible para este endpoint. El valor de gram debe ser un número entero entre 1 y 10.000; no se aceptan valores decimales.

Encabezados	Obligatorio	Descripción
`x-api-key`	sí	Autenticación
`idempotency-key`	sí	8–64
`Accept`	no	`application/json`
`Content-Type`	sí	`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"
  }
}

Pedidos

Usa estos métodos para obtener los pedidos creados mediante la API pública.

Solo se devuelven los pedidos de API del usuario asociado a la clave autenticada. Un pedido desconocido o de otro usuario devuelve 404 Not Found.

GET `/api/v1/orders`

Devuelve los pedidos de API del usuario del más reciente al más antiguo.

Encabezados	Obligatorio	Descripción
`x-api-key`	sí	Autenticación
`Accept`	no	`application/json`

Parámetros de consulta

Campo	Tipo	Obligatorio	Restricciones
`limit`	integer	no	1–100; default = 20
`offset`	integer	no	≥ 0; default = 0

La respuesta está paginada. Usa total para saber si hace falta otra solicitud con un offset mayor; se devuelven hasta 100 pedidos por solicitud.

Ejemplo de solicitud

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'

Respuesta correcta

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
  }
}

Campo	Tipo	Descripción
`data`	Order[]	Pedidos de la página actual.
`total`	integer	Número total de pedidos coincidentes.
`limit`	integer	Tamaño de página aplicado a la solicitud.
`offset`	integer	Número de pedidos omitidos.

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

Devuelve un pedido de API por su UUID.

Encabezados	Obligatorio	Descripción
`x-api-key`	sí	Autenticación
`Accept`	no	`application/json`

Ejemplo de solicitud

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'

Respuesta correcta

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"
  }
}

Campos de respuesta

Campo	Tipo	Restricciones
`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	—

Posibles errores

Si el pedido no existe, no pertenece al usuario o no se creó mediante la API, el endpoint devuelve 404 Not Found.

json

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

Webhook de estado del pedido

Si se ha configurado un webhookUrl para la clave de API, la API envía una solicitud POST al finalizar el pedido.

http

POST {webhookUrl}
Content-Type: application/json

Un pedido completado correctamente envía el evento order.completed; un pedido fallido envía 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"
}

Esquema del webhook

Campo	Tipo	Restricciones
`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	—

Requisitos del receptor del webhook

Devuelve una respuesta HTTP 2xx lo antes posible, procesa los eventos de forma idempotente y no dependas del orden en que se entregan.

Ejemplo completo del flujo del cliente

Consulta el saldo.
Si es necesario, obtén los datos de recarga, recarga la billetera y espera a que cambie el saldo.
Crea una compra con un idempotency-key único.
Guarda orderId, status e idempotencyKey. Una respuesta 201 significa que el pedido ha sido aceptado para su procesamiento.
Espera order.completed u order.failed y asocia el evento mediante 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
}

Ejemplo de cliente 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),
  });
}

¿Todo listo para iniciar la integración?

Crea una clave de API y configura la URL de tu webhook.

Gestionar la API

Documentación de la API

SDK para una integración más rápida

Python SDK

Node.js SDK

Gramix API v1

Información general

URL base

Formato de los datos

Métodos disponibles

Autenticación

Ejemplo de solicitud

Formato general de las respuestas

Respuesta correcta

Respuesta de error

Errores comunes

Esquemas comunes

PaymentCurrency

RecipientName

PurchaseRequestBase

PurchaseResponse

Idempotencia de las compras

Posibles errores

Billeteras

GET /api/v1/wallets/balance

Ejemplo de solicitud

POST /api/v1/wallets/balance

Flujo de recarga recomendado

Compras

POST /api/v1/purchase/stars

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

POST /api/v1/purchase/gram

Pedidos

GET /api/v1/orders

Parámetros de consulta

Ejemplo de solicitud

Respuesta correcta

GET /api/v1/orders/{id}

Ejemplo de solicitud

Respuesta correcta

Campos de respuesta

Posibles errores

Webhook de estado del pedido

Esquema del webhook

Requisitos del receptor del webhook

Ejemplo completo del flujo del cliente

Ejemplo de cliente 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}`