Documentação para desenvolvedores

Gramix API v1

Use este guia como contrato para desenvolver sua integração no servidor.

Informações gerais

A API pública permite consultar o saldo, adicionar fundos à carteira e comprar Telegram Stars, Telegram Premium e GRAM.

URL base

text

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

Formato dos dados

Os corpos das requisições e as respostas da API usam application/json.
Os valores monetários são enviados como strings com quatro casas decimais. Para fazer cálculos exatos, use tipos decimais ou mantenha os valores como strings.
As datas dos webhooks usam o formato ISO 8601. Não dependa de campos JSON desconhecidos.

Métodos disponíveis

Método	Endpoint	Finalidade	Status HTTP
`GET`	`/api/v1/wallets/balance`	Retorna o saldo atual.	`200`
`POST`	`/api/v1/wallets/balance`	Cria ou retorna o address e o memo necessários para adicionar fundos à carteira na rede TON.	`201`
`POST`	`/api/v1/purchase/stars`	Compra de 50 a 1.000.000 de Telegram Stars para o nome de usuário do Telegram informado.	`201`
`POST`	`/api/v1/purchase/premium/{duration}`	Compra o Telegram Premium por 3, 6 ou 12 meses.	`201`
`POST`	`/api/v1/purchase/gram`	Compra e envia de 1 a 10.000 GRAM para o destinatário do Telegram informado. Apenas "gram" em minúsculas é aceito como paymentCurrency; "usdt" não está disponível para este endpoint. O valor de gram deve ser um número inteiro de 1 a 10.000; valores decimais não são aceitos.	`201`
`GET`	`/api/v1/orders`	Retorna os pedidos de API do usuário do mais recente para o mais antigo.	`200`
`GET`	`/api/v1/orders/{id}`	Retorna um pedido de API pelo UUID.	`200`

Autenticação

Todos os métodos exigem uma chave de API ativa enviada no cabeçalho HTTP x-api-key.

http

x-api-key: YOUR_API_KEY

Exemplo de requisição

bash

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

Se o cabeçalho estiver ausente ou a chave for inválida, revogada ou inativa, a API retornará 401 Unauthorized.

A chave de API é secreta. Não a armazene em repositórios, URLs, parâmetros de consulta, logs ou código de cliente acessível ao público.

Formato geral das respostas

Resposta bem-sucedida

Uma resposta bem-sucedida contém statusCode e data. As requisições POST retornam o status HTTP 201.

json

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

Resposta de erro

Os erros contêm statusCode e uma message legível. A lógica do cliente deve se basear principalmente no código de status HTTP.

json

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

Erros comuns

Status 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 comuns

PaymentCurrency

paymentCurrency seleciona o saldo usado para pagar a compra. Apenas gram e usdt em letras minúsculas são aceitos.

typescript

type PaymentCurrency = "gram" | "usdt";

RecipientName

recipientName é o nome de usuário do destinatário no Telegram sem @. Deve ter de 5 a 32 caracteres e pode conter letras latinas minúsculas, números e _.

text

durov
user_123
telegram_user

text

@durov
User123
1username
user-name
abc

PurchaseRequestBase

json

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

PurchaseResponse

Todos os métodos de compra retornam orderId, status e idempotencyKey. Um pedido novo normalmente tem o 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";

Idempotência das compras

Todos os métodos /purchase/* exigem um cabeçalho idempotency-key com 8 a 64 caracteres.

http

idempotency-key: UNIQUE_REQUEST_KEY

São aceitos letras latinas, números, _ e -. A chave deve ser única para cada chave de API.
Após um erro de rede, repita a mesma requisição com a mesma chave. Use uma nova chave para uma nova compra.

text

order_20260713_0001
01J2Y5VN7CV8ZQ7DPZ9J0P6E4M
client-req-12345678

Possíveis erros

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

Carteiras

GET `/api/v1/wallets/balance`

Retorna o saldo atual.

Cabeçalhos	Obrigatório	Descrição
`x-api-key`	sim	Autenticação
`Accept`	não	`application/json`

Exemplo de requisição

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`

Cria ou retorna o address e o memo necessários para adicionar fundos à carteira na rede TON.

Sempre inclua o memo no comentário da transação ou no forward payload. Sem ele, a transferência não será creditada automaticamente.

Cabeçalhos	Obrigatório	Descrição
`x-api-key`	sim	Autenticação
`Accept`	não	`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"
  }
}

Os depósitos são creditados de forma assíncrona. GRAM é creditado em gram, enquanto o USDT na rede TON é creditado em usdt.

Fluxo de recarga recomendado

POST /wallets/balance
Sempre inclua o memo no comentário da transação ou no forward payload. Sem ele, a transferência não será creditada automaticamente.
GET /wallets/balance

Compras

As compras são processadas de forma assíncrona. A API valida a requisição e o saldo, cria o pedido, debita os fundos e retorna orderId com o status processing.

Se o pedido passar para failed, o valor debitado será devolvido ao mesmo saldo.

POST `/api/v1/purchase/stars`

Compra de 50 a 1.000.000 de Telegram Stars para o nome de usuário do Telegram informado.

Cabeçalhos	Obrigatório	Descrição
`x-api-key`	sim	Autenticação
`idempotency-key`	sim	8–64
`Accept`	não	`application/json`
`Content-Type`	sim	`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 o Telegram Premium por 3, 6 ou 12 meses.

Cabeçalhos	Obrigatório	Descrição
`x-api-key`	sim	Autenticação
`idempotency-key`	sim	8–64
`Accept`	não	`application/json`
`Content-Type`	sim	`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 e envia de 1 a 10.000 GRAM para o destinatário do Telegram informado. Apenas "gram" em minúsculas é aceito como paymentCurrency; "usdt" não está disponível para este endpoint. O valor de gram deve ser um número inteiro de 1 a 10.000; valores decimais não são aceitos.

Cabeçalhos	Obrigatório	Descrição
`x-api-key`	sim	Autenticação
`idempotency-key`	sim	8–64
`Accept`	não	`application/json`
`Content-Type`	sim	`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

Use estes métodos para obter pedidos criados pela API pública.

Somente pedidos de API do usuário associado à chave autenticada são retornados. Um pedido desconhecido ou de outro usuário retorna 404 Not Found.

GET `/api/v1/orders`

Retorna os pedidos de API do usuário do mais recente para o mais antigo.

Cabeçalhos	Obrigatório	Descrição
`x-api-key`	sim	Autenticação
`Accept`	não	`application/json`

Parâmetros de consulta

Campo	Tipo	Obrigatório	Restrições
`limit`	integer	não	1–100; default = 20
`offset`	integer	não	≥ 0; default = 0

A resposta é paginada. Use total para saber se outra requisição com offset maior é necessária; cada requisição retorna até 100 pedidos.

Exemplo de requisição

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'

Resposta bem-sucedida

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	Descrição
`data`	Order[]	Pedidos da página atual.
`total`	integer	Número total de pedidos correspondentes.
`limit`	integer	Tamanho da página aplicado à requisição.
`offset`	integer	Número de pedidos ignorados.

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

Retorna um pedido de API pelo UUID.

Cabeçalhos	Obrigatório	Descrição
`x-api-key`	sim	Autenticação
`Accept`	não	`application/json`

Exemplo de requisição

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'

Resposta bem-sucedida

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 da resposta

Campo	Tipo	Restrições
`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	—

Possíveis erros

Se o pedido não existir, não pertencer ao usuário ou não tiver sido criado pela API, o endpoint retorna 404 Not Found.

json

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

Webhook de status do pedido

Se um webhookUrl estiver configurado para a chave de API, a API enviará uma requisição POST após a conclusão do pedido.

http

POST {webhookUrl}
Content-Type: application/json

Um pedido bem-sucedido envia o evento order.completed; um pedido malsucedido envia 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 do webhook

Campo	Tipo	Restrições
`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 do receptor do webhook

Retorne uma resposta HTTP 2xx o mais rápido possível, processe os eventos de forma idempotente e não dependa da ordem de entrega.

Exemplo completo do fluxo do cliente

Consulte o saldo.
Se necessário, obtenha os dados de recarga, adicione fundos à carteira e aguarde a alteração do saldo.
Crie uma compra com um idempotency-key exclusivo.
Salve orderId, status e idempotencyKey. Uma resposta 201 significa que o pedido foi aceito para processamento.
Aguarde order.completed ou order.failed e associe o evento usando 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
}

Exemplo 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),
  });
}

Tudo pronto para iniciar a integração?

Crie uma chave de API e configure a URL do webhook.

Gerenciar API

Documentação da API

SDKs para uma integração mais rápida

Python SDK

Node.js SDK

Gramix API v1

Informações gerais

URL base

Formato dos dados

Métodos disponíveis

Autenticação

Exemplo de requisição

Formato geral das respostas

Resposta bem-sucedida

Resposta de erro

Erros comuns

Esquemas comuns

PaymentCurrency

RecipientName

PurchaseRequestBase

PurchaseResponse

Idempotência das compras

Possíveis erros

Carteiras

GET /api/v1/wallets/balance

Exemplo de requisição

POST /api/v1/wallets/balance

Fluxo 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

Exemplo de requisição

Resposta bem-sucedida

GET /api/v1/orders/{id}

Exemplo de requisição

Resposta bem-sucedida

Campos da resposta

Possíveis erros

Webhook de status do pedido

Esquema do webhook

Requisitos do receptor do webhook

Exemplo completo do fluxo do cliente

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