First, be precise about what GRAM means here
Inside Mini Empire, GRAM is the commercial label used for the platform reward balance handled by the native TON transfer service. It is not presented as a separate project Jetton. That distinction matters when an owner funds the wallet, explains network transfers and compares an in-app balance with a transferable asset.
A project may also operate its own points or token campaign. Keep those units separate. A score can represent progress, a project token can have its own contract and payout process, and the GRAM-labelled native reward can follow the platform withdrawal flow. Combining all three into one balance creates accounting and trust failures.
GRAM rewards are not Telegram’s Stars affiliate program
Telegram now provides an official affiliate-program mechanism for Mini Apps. An affiliate link can attribute a new Mini App user and pay the affiliate a percentage of that user’s future Telegram Stars purchases for a configured period. That is purchase commission denominated in Stars; it is not the same product as a bot owner paying a fixed GRAM reward after a qualified referral.
Mini Empire’s referral engine lets the project define the qualifying event and configured GRAM reward. The project wallet and payout rules remain the owner’s responsibility. Use Telegram’s native affiliate program when the business wants revenue share on Stars purchases; use a refer-and-earn bot when the campaign wants to reward a published non-purchase event. A project can use both, but it must name them separately in balances, rules and reporting.
| Model | What triggers value | Reward asset | Who funds it |
|---|---|---|---|
| Mini Empire GRAM referral reward | The project’s configured qualifying event | GRAM-labelled native reward through the supported payout flow | Project owner’s funded wallet |
| Telegram Mini App affiliate program | Purchases made in Stars by the referred user | Commission in Telegram Stars | A share of Mini App Stars revenue |
| Project points or future allocation | Campaign-specific activity or eligibility | Internal score or separately defined project asset | Project campaign under its published terms |
The five events in a safe GRAM reward flow
Do not collapse these events into a single “paid” state. A referral may be recorded but not qualified; a reward may be credited but not yet requested; a request may be queued but not yet finalized. Visible states reduce support disputes and make retries safer.
- Referral captured
The new Telegram user arrives through the sponsor deep link and the relationship is recorded once.
- Referral qualified
The invited user completes the published requirement that makes the referral valuable.
- Reward credited
One ledger event increases the sponsor balance by the configured amount.
- Withdrawal requested
The user provides a valid address and satisfies minimum, balance and policy checks.
- Transfer finalized
The queue sends from the funded project wallet and stores a success or failure result.
Fund liabilities before you promote the bot
A referral reward creates a future withdrawal obligation as soon as it becomes spendable. Estimate the maximum qualified referrals for the campaign and reserve that amount before buying distribution. Keep an additional buffer for network fees, retries and unexpected conversion between displayed precision and transfer precision.
Do not use new participant deposits to conceal an underfunded reward pool. The project should be able to honor earned balances even if acquisition stops today. If the wallet reserve falls below the operating threshold, pause new reward creation or move withdrawals into a clearly disclosed maintenance state.
Required reserve = qualified reward liability + pending withdrawals + fee buffer + failure reserveSet withdrawal controls that protect both sides
| Control | Purpose | User-facing explanation |
|---|---|---|
| Minimum amount | Avoid fees and support on tiny transfers | The balance required before requesting |
| Address validation | Reject malformed destinations before queueing | Which TON address formats are accepted |
| Daily limit | Contain an incident or automated drain | How much can be processed in one period |
| Deposit or activity rule | Only when genuinely required by the product | The exact reason and condition—never hide it |
| Maintenance switch | Pause transfers without corrupting balances | Rewards remain recorded while payouts are paused |
| Idempotency key | Prevent a repeated tap from creating duplicate transfers | Invisible control; support can trace the request |
Handle failed payouts without inventing money
A transfer can fail because of an invalid destination, insufficient project funds, provider interruption, network behavior or an internal timeout. The request needs one authoritative status and a known refund rule. If the balance was debited when the request entered the queue, either complete the transfer or restore that debit exactly once.
Never retry blindly after an ambiguous response. Check whether the transfer was broadcast or finalized before sending again. Store a traceable reference where available and make support distinguish “queued”, “broadcast”, “confirmed”, “failed and refunded” and “requires review”.
- One request identifier
- One ledger debit
- One transfer attempt state
- A final transaction reference
- An idempotent refund path
- A visible support status
Build the first GRAM referral bot in seven controlled steps
Mini Empire can launch the branded bot for $0 so the owner can validate the rules before the current one-time $15 ownership unlock. Neither price removes the need to fund real rewards. Pause acquisition whenever the available reserve cannot cover earned balances and pending withdrawals.
- Register the bot
Use /newbot in the official BotFather, choose the public identity and keep the token private.
- Connect Mini Empire
Create a bot project and provide the token only inside the authenticated builder.
- Write the qualification rule
Name the action that turns an invited account into a payable referral.
- Configure the reward contract
Set the GRAM amount, required channels, limits, minimum withdrawal, timing and prohibited behavior.
- Fund a test wallet
Deposit only enough native balance for controlled end-to-end tests plus fees.
- Run the sponsor journey
Use clean accounts to capture, qualify, credit and withdraw one referral while repeating every callback.
- Launch to a small cohort
Observe qualification, retention, payout cost and support questions before purchasing reach.
Test with a deliberately tiny funded wallet
- Fund only the test amount
Limit the impact of a configuration error.
- Create one valid referral
Confirm the exact displayed and ledger amount.
- Request below the minimum
The bot should explain the limit without changing balance.
- Use an invalid address
The request should stop before entering the payout queue.
- Complete one real withdrawal
Match the ledger, queue state and on-chain result.
- Repeat the confirmation action
A duplicate transfer must not be created.
- Simulate insufficient project funds
The user balance must remain recoverable and the owner must see the problem.
Publish rules that a nontechnical user can audit
State the qualification event, reward amount, minimum withdrawal, timing, limits, prohibited behavior and support route in plain language. Avoid claiming guaranteed income or implying that an in-app number has external value beyond the supported payout process.
When a rule changes, version it and decide which cohort it applies to. A lower future reward should not silently rewrite an already qualified ledger entry. Send a broadcast for material changes and keep the effective date visible.
Common questions
Is GRAM a separate Jetton in Mini Empire?
Mini Empire uses GRAM as the commercial label for the native reward balance handled by its TON payout flow. A project-specific Jetton is a different asset and needs separate configuration and accounting.
Is a GRAM referral reward the same as a Telegram Stars affiliate commission?
No. A Mini Empire GRAM reward follows the project’s configured qualification and funded payout rules. Telegram’s official Mini App affiliate program pays a share of referred users’ Stars purchases.
Who funds automatic referral payouts?
The project owner funds the wallet used by the bot. Mini Empire supplies the workflow; it does not make an unfunded campaign solvent.
Can a user withdraw immediately after one referral?
That depends on the owner’s published qualification and minimum-withdrawal rules. The interface should show whether a reward is pending, spendable or eligible for withdrawal.
What happens if a transfer fails?
A safe system records the failure and restores any debited user balance exactly once when the transfer did not complete. Ambiguous transfers should be reviewed before retrying.
Sources and further reading
Technical and product claims were checked against these primary sources.