docs
API Endpoints

API Endpoints

This document describes the available API endpoints for the GSwarm Telegram-Discord linking system.

Base URL

All endpoints are available at: https://gswarm.dev/api

Authentication

Most endpoints use rate limiting to prevent abuse. Some endpoints may require additional authentication headers.

Endpoints

POST /api/telegrams/issue-code

Issues a verification code for a Telegram channel.

Request Headers:

Content-Type: application/json

Request Body:

{
  "telegramId": 123456789,
  "peerIds": ["peer_id_1", "peer_id_2", "peer_id_3"],
  "eoa": "0x1234567890abcdef1234567890abcdef12345678",
  "code": "ABC12345"
}

Parameters:

  • telegramId (number): Telegram channel ID
  • peerIds (array): Array of peer IDs associated with the channel
  • eoa (string): Ethereum address (must be valid 0x format)
  • code (string): 8-character verification code (A-Z, 0-9 only)

Success Response (200):

{
  "success": true,
  "code": "ABC12345",
  "message": "Verification code generated successfully"
}

Error Responses:

  • 400 Bad Request - Invalid request body or validation errors
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

POST /api/telegrams/check-verification

Check if a Telegram channel is verified.

Request Headers:

Content-Type: application/json

Request Body:

{
  "telegramId": 123456789
}

Parameters:

  • telegramId (number): Telegram channel ID to check

Success Response (200):

{
  "isVerified": true
}

Error Responses:

  • 400 Bad Request - Missing telegramId
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

POST /api/user/data

Get user data and rankings for a Telegram channel.

Note: The GET variant of this endpoint is deprecated and returns 410 Gone. Avoid placing identifiers in URLs.

Preferred Usage (Headers):

X-Telegram-ID: 123456789
X-Peer-Ids: QmAAA,QmBBB  (optional, CSV)

Alternative Usage (Body):

{
  "telegramId": 123456789,
  "peerIds": ["QmAAA", "QmBBB"]
}

Success Response (200):

{
  "ranks": [
    {
      "peerId": "Qmed5QTNsGQQJ9ZaXFWFAAAzwgZZLE2VMibZr5RZA623a3",
      "rank": 885,
      "totalWins": 87,
      "totalRewards": 40,
      "lastSeen": "2025-06-27T11:38:40.822883"
    }
  ],
  "stats": {
    "totalNodes": 4,
    "rankedNodes": 4
  }
}

Empty Response (200):

{
  "ranks": [],
  "stats": {
    "totalNodes": 0,
    "rankedNodes": 0
  }
}

Error Responses:

  • 400 Bad Request - Invalid telegramId format
  • 401 Unauthorized - Missing telegramId
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

POST /api/discord/link

Consume a verification code and link Discord account.

Request Headers:

Content-Type: application/json
X-API-SECRET: your_api_secret_here

Request Body:

{
  "discordId": "123456789012345678",
  "code": "ABC12345"
}

Parameters:

  • discordId (string): Discord user ID
  • code (string): 8-character verification code

Success Response (200):

{
  "roleId": "9876543210"
}

Error Responses:

  • 400 Bad Request - Invalid or expired code
  • 401 Unauthorized - Invalid API secret
  • 500 Internal Server Error - Server error

Data Types

Peer ID

A unique identifier for a node in the GSwarm network. Format: Base58 encoded string starting with "Qm".

EOA (Externally Owned Account)

An Ethereum address in 0x format (42 characters total).

Verification Code

An 8-character alphanumeric code (A-Z, 0-9) used for Discord verification.

Telegram Channel ID

The numeric ID of a Telegram channel where the bot operates.

Rate Limiting

All endpoints implement rate limiting to ensure fair usage. Limits are applied per IP address or per channel ID depending on the endpoint.

Error Handling

All endpoints return JSON error responses with the following structure:

{
  "error": "Error message description"
}

Some endpoints may include additional error details:

{
  "error": "Validation failed",
  "details": [
    {
      "field": "telegramId",
      "message": "Must be a positive integer"
    }
  ]
}

Examples

Issue a Verification Code

curl -X POST https://gswarm.dev/api/telegrams/issue-code \
  -H "Content-Type: application/json" \
  -d '{
    "telegramId": 123456789,
    "peerIds": ["QmWPvLPBPkh5h2v3c65VxCsfHJzmi4cgMXaGguoXLgmVsa"],
    "eoa": "0x1234567890abcdef1234567890abcdef12345678",
    "code": "ABC12345"
  }'

Check Verification Status

curl -X POST https://gswarm.dev/api/telegrams/check-verification \
  -H "Content-Type: application/json" \
  -d '{"telegramId": 123456789}'

Get User Data (POST)

curl -X POST https://gswarm.dev/api/user/data \
  -H "Content-Type: application/json" \
  -H "X-Telegram-ID: 123456789" \
  -H "X-Peer-Ids: QmAAA,QmBBB" \
  -d '{
    "peerIds": ["QmAAA", "QmBBB"]
  }'

Link Discord Account

curl -X POST https://gswarm.dev/api/discord/link \
  -H "Content-Type: application/json" \
  -H "X-API-SECRET: your_secret_here" \
  -d '{
    "discordId": "123456789012345678",
    "code": "ABC12345"
  }'
API ReferenceFAQ