TgPay Merchant API

transfer

Destructive

Pay a Telegram user from the app balance (instant, irreversible). Address by user_id (must have opened the bot) OR username (unknown → parked in escrow until they open the bot, auto-returned after 30 days). MONEY MOVES — double-check the recipient and amount; spend_id is the idempotency key.

Input Schema

TableJSON Schema

Name	Required	Description
`asset`	Yes	Asset code.
`amount`	Yes	Decimal string in MAJOR units, e.g. "5" = 5 USDT. Never a float.
`comment`	No	Shown to the recipient (≤1024).
`user_id`	No	Recipient Telegram user id (or pass username).
`spend_id`	Yes	Idempotency key (≤64) — persist before calling.
`username`	No	Recipient @username (or pass user_id).
`disable_send_notification`	No	Skip the recipient DM.

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant behavioral detail beyond the annotations: payments are instant and irreversible, unknown usernames enter escrow and auto-return after 30 days, and spend_id is the idempotency key. The 'MONEY MOVES' warning reinforces the destructiveHint=true annotation without contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences carry substantial, non-redundant information: what the tool does, how recipient addressing works, and the critical warning about irreversibility and idempotency. The most important context is front-loaded, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating payment tool with 7 parameters and no output schema, the description is complete enough for safe invocation. It covers the recipient addressing rules, the escrow edge case, the irreversible nature, and the idempotency requirement, leaving no critical decision unclear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics on top by explaining the difference between user_id and username, including the escrow/auto-return behavior, and by emphasizing spend_id as the idempotency key. This exceeds what the raw schema entries convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb and resource: 'Pay a Telegram user from the app balance.' It clearly differentiates itself from siblings like transferBatch and getTransfers by describing a single, instant, irreversible payment with its own idempotency semantics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly scopes the tool to paying a Telegram user and explains the two addressing modes (user_id vs username) with their different behaviors. It does not explicitly name transferBatch as the alternative for multiple payments, so there is no direct exclusion, but the context is clear enough for an agent to select this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All TgPay Merchant API tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.6/5.0

Disambiguation5/5

Each tool targets a distinct resource and action: invoices, subscription plans, subscriptions, checks, transfers, connection status, and app info are cleanly separated. Even similarly named tools like transfer and transferBatch are clearly distinguished by single vs. batch behavior.

Naming Consistency4/5

The overwhelming majority follow a clear camelCase verb_noun pattern, such as createInvoice, getChecks, and refundInvoice. Minor deviations exist with get_docs and connect_status using snake_case, and bare verbs like connect and transfer, but these do not seriously harm predictability.

Tool Count4/5

At 24 tools, the set is slightly above the ideal compact range, but the scope is genuinely broad: connection onboarding, invoices, subscriptions, checks, transfers, balances, rates, app settings, and documentation. Most tools cover distinct needed operations for a merchant payments API.

Completeness4/5

The core lifecycles are well covered: create/list/delete/refund for invoices, create/list/archive for subscription plans, create/list/delete for checks, and single/batch transfers with listings. The main gap is a lack of singular get-by-id endpoints for individual resources, though list endpoints likely make this workable.

Resources

Need Help?