TGCore SDK

A fluent DSL framework for composing Telegram, APIs, and AI workflows.

Turn messy APIs into clean, composable chains.

Like Flutter for backend logic.

# Chain your backend, not JSON

result = await tg.app("groq.ai", tgmod=True)\
        .model("moonshotai/kimi-k2-instruct-0905")\
        .messages(
            tg.user("Say test")
        )\
        .stream(False)\
        .send()

print(result.text())

Framework TgCore | TeamKillerX Docs IO | TgCore API Docs | Original Telegram API Docs

Security-focused Telegram Bot Framework.

• Getting Started
  • Installation
  • What makes TGCore different
  • Chain & DSL
  • AI Chain
  • Traditional API
  • TGCore Fluent Builder
  • Ultra-fast with parallel
  • System Benchmark
  • payload DSL (domain-specific language)
  • Clean architecture
  • Authentication
  • Usage
  • Simple comparison
  • New fluent chain API
  • sendMessage
  • Simple Call
  • Builder Pattern
  • Rest API & TGCore Bot
  • Why TGCore?
  • Compared to Native Telegram API
  • License
  • Contributing
  • Status
  • Author

What makes TGCore different

• Secure and scalable architecture
• Async-first design
• Fluent API builder pattern
• Supports Telegram bots, APIs, and AI workflows
• Designed for complex system composition

📦 Installation

pip install tgcore

Or install locally:

pip install -e .

Getting started

from tgcore import Client

tg = Client(api_key="YOUR_API_KEY")

await tg.raw.sendMessage()\
    .chat_id(123456789)\
    .text("Hello from TGCore")\
    .send()

Chain & DSL

await tg.use.default\
     .route("games", "chain")\
     .user(
         tg.where(
             name="Randy Architect",
             age="145",
             hobi="all"
         )
     )\
     .database(
         tg.where(
             mongodb=True,
             redis=True,
             sqlite=True
         )
     )\
     .pretty()

AI Chain

msg = tg.msg.core("Hello")

res = await tg.ai.groq()\
    .model("kimi-k2")\
    .messages([msg])\
    .send()

print(res.text())

Traditional API

send_message(
    chat_id,
    text,
    parse_mode,
    disable_notification,
    reply_markup,
    protect_content
)

TGCore Fluent Builder

send_message()\
    .chat_id(id)\
    .text("hello")\
    .send()

Ultra-fast with parallel

Ultra-fast AES-256 cryptography for Telegram MTProto with hardware AES-NI acceleration.

• Mode: tgcrypto or cryptg

tg.parallel(
    install_type="tgcrypto",
    debug=True
)

System Benchmark

Standardized routing layer across APIs

• API devs, etc
• Use router enums: /v1, /openai, /api or custom

from tgcore import Client

tg = Client(
    bearer_token="gsk_xxxx",
    base_url="https://api.groq.com",
    is_bearer=True
)

await (
    tg.app(
      "v1/chat/completions",
        router="/openai",
        tgmod=False
    )
    .model("moonshotai/kimi-k2-instruct-0905")
    .messages(tg.user("say test"))
).execute()

• TGCore (full control)

from tgcore import Client

tg = Client(api_key="xxxxxx")

result = await tg.app("groq.ai", tgmod=True)\
        .model("moonshotai/kimi-k2-instruct-0905")\
        .messages(
            tg.user("Say test")
        )\
        .send()

print(result.text())

Simple comparison

❌ Regular Telegram

InlineKeyboardMarkup([
    [InlineKeyboardButton("A", url="...")]
])

✅ tgcore (which you already use)

tg.kb.inline().url("A", "...").build()

payload DSL (domain-specific language)

JSON is the output, not the source of truth The architecture should absorb API changes

result = await tg.use.default\
      .route("gemini", "gemini-2.5-flash")\
      .contents(
          [
              tg.where(
                  parts=[tg.where(text="lu siapa?")]
              )
          ]
      )\
      .system_instruction(
          tg.where(
              parts=[tg.where(text="kamu adalah TgCore komedi lucu")]
          )
      )\
      .generationConfig(
          tg.where(
              temperature=1.0,
              topP=0.8,
              topK=10
          )
      )\
      .send()

return result.text()

Clean architecture

• Architecture: clean
• Code: perfect
• Async: working

tg = Client(api_key="something", base_url="https://your_domain.com")

result = await tg.use.default\
    .endpoint("/v1/chat/completions")\
    .model("model")\
    .messages([...])\
    .stream(False)\
    .send()

print(result)

🔑 Authentication

Create client instance:

from tgcore import Client

client = Client("fw_live_xxx")

await client.telegram.send_message(
    chat_id="@channel",
    text="hello"
)

👾 Usage

Platform Tools

resp = await tg.platform.facebook\
    .download(url="https://facebook.com/...")\
    .send()

New fluent chain API

Parameters can be chained (builder-style) without having to write long functions like send_message(...).

Example of using fluent chain API:

# version: 1.0.43+, 1.0.68+
async def full_code():
    _ = await tg.fetch_post(
        "/api/web/facebook/download",
        url="https://www.facebook.com/groups/788889186033999/permalink/1325624742360438/?app=fbl",
        check_errors=True
    )
    await tg.raw\
    .sendVideo()\
    .chat_id(chat_id)\
    .video(_.data.video[0].url)\
    .reply_markup(
        tg.kb().copy_text(
            "this SDK builder style",
            "use a framework"
        )
        .build()
    )\
    .skip()

Example: await tg.raw.sendMessage().chat_id(chat_id).text("tgcore").skip()

That's the concept of builder + fluent chain API.

sendMessage

# Latest version 1.0.16+, 1.0.68+
# Support Pyrogram/Kurigram (KeyboardBuilder)

from tgcore import Client, KeyboardBuilder

tg = Client()

async def send():
    await (
        tg.raw
        .sendMessage(
            chat_id=m.chat.id,
            text="Testing",
            reply_markup=(
                KeyboardBuilder()
                .url("This Url", "https://github.com/TeamKillerX/tgcore")
                .style("This color", "danger", callback_data="#abc")
                .build()
            )
        )
        .execute()
    )

New button

# old version: 1.0.14
from tgcore import Client, KeyboardBuilder

tg = Client()

async def use_pyrogram(m):
    await tg.telegram.send_message(
        chat_id=str(m.chat.id),
        text="This Button",
        reply_markup=(
            KeyboardBuilder()
            .row("GitHub", url="https://github.com")
            .row("Docs", url="https://www.learnpython.org/")
            .row("Pypi", url="https://pypi.org/project/tgcore/")
            .build()
        )

Simple Call

await client.telegram.send_message(
    chat_id="@channel",
    text="Hello world"
)

Builder Pattern

await (
    client.telegram
        .send_photo_call(chat_id="@channel", photo="https://img.jpg")
        .execute()
)

Rest API & TgCore Bot

# Version: 1.0.68+
from tgcore import Client, KeyboardBuilder

tg = Client()

async def pinterest_images(q: str):
    kw = await tg._post(
        "/api/web/pinterest",
        payload={"query": q}
    )
    like_ts = tg.to_obj(kw)
    if not like_ts.ok or not like_ts.data:
        return None
    return like_ts.data.pins[1].media.images.orig.url

async def send_photo():
    newurl = await pinterest_images("Real coding")
    resp = await tg.raw.sendPhoto(
        chat_id=-100123456789,
        photo=newurl,
        reply_markup=(
            KeyboardBuilder()
            .url("View Pinterest", newurl)
            .url("Tgcore on PyPI", "https://pypi.org/project/tgcore/")
            .row()
            .url("Tgcore on NPMJS", "https://www.npmjs.com/package/@xtsea/tgcore-ts")
            .build()
        )
    ).execute()
    return tg.to_obj(resp).ok

🔄 Token Rotation Support

The server supports storing encrypted tokens using AES-256-GCM. The SDK automatically uses the active token version.

🔒 Security Model

TgCoreSDK never exposes bot tokens to clients.

Flow:

Client → API Gateway → Decrypt → Telegram API

Benefits:

• prevents token leaks
• safe frontend usage
• safe monitoring dashboards
• supports IP restrictions

Why TGCore?

Unlike traditional Telegram SDKs, TGCore is built as a secure middleware layer that prevents token leaks, enforces API-key auth, and supports enterprise-grade scaling.

Designed for production, not demos.

Compared to Native Telegram API

🧾 License

Licensed under Apache License 2.0

You may:

• use commercially
• modify
• distribute
• sublicense

🤝 Contributing

Pull requests welcome. For major changes, open an issue first to discuss what you would like to change.

🔥 Status

Production Ready

👑 Author

Built with ❤️ by Randy W