Documentation

Gram Store is a Telegram Mini App launchpad on The Open Network. Founders choose a funding goal, run a fair periodic uniform-price auction, and graduate to Ston.fi. Supporters bid on auctions or trade live apps — everyone in the same clearing period pays the same token price.

Open Gram Store in Telegram via https://t.me/GramStoreApp_bot (served at https://app.gram.store, TON Connect only). In a browser at https://gram.store, sign in with Telegram via Privy to use embedded wallets for Base, Polygon, Arbitrum, Robinhood, BNB Chain, and TON. See Swaps for cross-chain and in-app trading.

Every project on Gram Store moves through three stages:

1. 1

   Draft

   The founder creates a listing with token details, links, and team info. Drafts are saved to your profile and can be edited anytime.

2. 2

   Auction

   The owner chooses a funding goal (3,000 GRAM (unverified) or 10,000 GRAM (verified)), pays the publish fee (2 GRAM to the Gram admin wallet), and publishes to auction. Supporters bid GRAM on-chain until the 3-day window closes — the total committed GRAM can exceed the goal.

3. 3

   Live

   After the auction lock ends with the goal met, gram.store automatically deploys the DEX. Gram Store deploys the jetton + Ston.fi pool, pays the Graduation Bonus (10% of bonded GRAM) to the owner wallet, and uses that wallet as the default swap fee treasury. The app appears in the Live tab.

The Apps page is the main catalog. It has three tabs:

• Auction — apps currently raising GRAM
• Live — apps that finished auction and launched on Ston.fi
• Featured — highlighted apps and tools on Gram Store

Auction apps use /tma/[id] detail pages with progress, top contributors, and a commit panel. Live apps keep the same /tma/[id] listing link after launch — with trading links, fee balances, and owner tools.

To launch your TMA token on Gram Store:

1. 1

   Connect your wallet

   Use TON Connect in the header. Your wallet address identifies you as the listing owner.

2. 2

   Create a listing

   Go to Launch TMA and fill in your token name, ticker, logo, app links, team profiles, and description.

3. 3

   Publish to auction

   Choose your auction goal (3,000 GRAM (unverified) or 10,000 GRAM (verified); default 3,000 GRAM). Pay the publish fee (2 GRAM) to the Gram admin wallet; Gram Store deploys an auction contract with that goal baked in. Start the 3-day auction window on-chain from the owner panel.

4. 4

   Launch on Ston.fi

   Once the auction lock ends with the goal met, gram.store automatically starts DEX deployment. You receive the Graduation Bonus — 10% of bonded GRAM — in your owner wallet. Swap fees also route there by default; you can optionally set a different treasury wallet. Gram Store mints tokens, seeds the pool, airdrops committers, and locks owner LP in a vesting vault.

After launch, use Edit token on the live app page to update on-chain metadata, monitor your vesting schedule, and withdraw vested LP in partial amounts.

Browse auction and live apps to find projects to back.

During auction, connect your wallet and place auction bids with a GRAM budget and optional max price per token. Bids clear at a uniform price every hour over the 3-day window (72 periods) — no sniping advantage for late bidders. The total committed GRAM can exceed the goal; new bids are still accepted until the window closes. Early bidders fill up to their per-wallet 2% token cap each period before unsold tokens roll forward.

When the project launches on Ston.fi, you receive app tokens from your on-chain auction allocation (72% of the 100M supply is sold via the auction). If your bid did not spend its full budget across all clearing periods, the unfilled GRAM is automatically refunded in batched on-chain messages after DEX deploy. If the goal is not met before the lock ends, you reclaim your full committed GRAM automatically after the deadline; no owner action is required. Track commitments on your profile page.

Gram Store includes built-in swapping powered by Ston.fi Omniston. Use the dedicated Swap page or the swap panel on any live app page (/tma/[id], the same short listing link as auction).

Wallets. In a browser, connect with Privy to swap on TON and bridge from Base, Polygon, Arbitrum, Robinhood, or BNB Chain. Inside Telegram, Gram Store uses TON Connect only — GRAM, USDT on TON, and Gram Store jettons on Ston.fi pools; EVM bridging requires opening Gram Store in a browser with Privy.

Gasless TON swaps.Swapping into GRAM on TON (e.g. USDT → GRAM) is gasless when your GRAM balance is too low to cover network fees: Gram Store's relay sponsors the gas via TON Connect's signed-message flow, so you don't need to hold GRAM first. Wallets that don't support gasless signing fall back to paying their own gas. This works the same on app.gram.store and inside Telegram.

Swap fees & gasless minimum. Omniston cross-chain and TON swaps charge an integrator fee, taken from the asset you receive:

• Gasless (relay-sponsored) swaps — 1%. Applies whenever Gram Store sponsors the TON gas: EVM → GRAM, EVM → USDT (TON), USDT (TON) → EVM, and USDT (TON) → GRAM.
• User-gas swaps (you pay your own gas) — 0.5%. Applies to GRAM/USDT (TON) → EVM and EVM → TON when your wallet covers the fee itself.
• Gasless minimum — 50 (≈ $50) on the EVM-stable leg of relay-sponsored cross-chain routes: EVM → GRAM, gasless USDT (TON) → EVM, and gasless GRAM → EVM. Direct same-chain TON swaps (USDT (TON) ↔ GRAM) and the direct EVM stable → USDT (TON) bridge have no minimum — so even a 1 USDC or 1 USDT swap works.

Swaps fall into two settlement types:

• GRAM swap — on-chain trades on Ston.fi between GRAM, USDT (TON), and Gram Store jettons
• Cross-chain · HTLC — Omniston bridges between USDT (TON) and EVM stables (USDC on Base, USDC on Polygon, USDC on Arbitrum, USDG on Robinhood, pUSD on Polygon, USDT on BNB Chain)

Cross-chain routes (Privy). Bridge into TON: USDC (Base), USDC (Polygon), USDC (Arbitrum), USDG (Robinhood), pUSD (Polygon), or USDT (BNB) → USDT (TON). Bridge out of TON: USDT (TON) → USDC (Base), USDC (Polygon), USDC (Arbitrum), USDG (Robinhood), pUSD (Polygon), or USDT (BNB). First-time EVM swaps may require a one-time token approval for gas on that chain.

TON routes. On TON you can swap GRAM ↔ USDT (TON), GRAM ↔ any Gram Store jetton, and jettons ↔ USDT (TON). Live app pages default to swapping into that app's token; the Swap page lists all live Gram Store jettons in the picker.

Available tokens depend on what you choose as the receive asset. The pay picker only shows valid sources for that destination:

• Receive USDT (TON) — pay with GRAM, Gram Store jettons, USDC (Base), USDC (Polygon), USDC (Arbitrum), USDG (Robinhood), pUSD (Polygon), or USDT (BNB)
• Receive GRAM — pay with USDT (TON) or Gram Store jettons
• Receive a Gram Store jetton — pay with GRAM, USDT (TON), or other Gram Store jettons
• Receive USDC (Base, Polygon, Arbitrum), USDG (Robinhood), pUSD (Polygon), or USDT (BNB) — pay with USDT (TON)

1. 1

   Connect wallet

   Use Privy in a browser for full routes, or TON Connect in Telegram for TON-only swaps.

2. 2

   Choose receive asset first

   Pick what you want to receive — the pay list updates to valid sources only.

3. 3

   Enter amount and review quote

   Omniston fetches a live quote. Cross-chain swaps show an estimated receive amount before you confirm.

4. 4

   Confirm in wallet

   Swaps on TON approve in your TON wallet — gasless when swapping into GRAM with a low GRAM balance, otherwise keep a little GRAM for fees. EVM→TON swaps sign on Base, Polygon, Arbitrum, Robinhood, or BNB; TON→EVM swaps sign on TON. Keep native gas (ETH, POL, ETH on Arbitrum, ETH on Robinhood, BNB) on the EVM chain you send from.

Use the ↕ control between pay and receive to flip direction when the reverse route is supported. Gram Store jettons can be found by ticker in the picker or pasted by jetton address (EQ… / UQ…).

Gram Store raises use a periodic uniform-price auction. Instead of rewarding whoever bids last, the 3-day window is split into 72 clearing periods (1 hours each). Everyone whose bid fills in the same period pays the same token price — early and late bidders in that period are treated equally.

The auction sells 72% of the app's fixed 100M token supply. That supply is divided across the 72 periods (1% per 1-hour period). The project graduates when total committed GRAM reaches the owner's chosen goal (3,000 GRAM (unverified) or 10,000 GRAM (verified); each listing shows its cap on the app page).

Clearing price. At the end of each period, the on-chain contract computes one uniform clearing price from active bid budgets in that period. More demand for the period's token slice pushes the clearing price up; less demand leaves it nearer the floor (the minimum price implied by the funding goal and total tokens for sale). Unsold tokens in a period roll into the next period's supply (each period always adds its own 1M-token hourly slice on top of all accumulated rollover, through period 72). The app page shows the current period, floor, and latest clearing price as checkpoints run.

1. 1

   Set your GRAM budget

   Choose how much GRAM to commit (minimum 0.1 GRAM). Your full budget is locked in the auction contract until the 3-day window closes. New bids are accepted even after the goal is reached, so total committed GRAM can exceed the goal.

2. 2

   Optionally cap your price

   Add a max price per token, or leave it empty for no limit. If a period's clearing price would exceed your cap, your bid skips that period but can still participate in later periods while your budget remains.

3. 3

   Budget competes per period at full cap

   Your bid stays active until its budget is used. Each hourly period tries to fill your per-wallet 2% token cap first — early bidders absorb supply before unsold tokens roll forward. When a period is oversubscribed, everyone in that period fills pro-rata and leftover budget carries forward.

4. 4

   Receive tokens and refunds at launch

   Each period your bid qualifies, you accrue tokens at that period's uniform clearing price. After DEX deploy, any unfilled GRAM is automatically refunded to your wallet in batched on-chain messages. You do not need to send a manual Withdraw once automatic refunds are processed.

While the auction is open. GRAM stays locked until the 3-day deadline passes. Bidding continues even after the goal is reached, so total committed GRAM can exceed the goal. You cannot withdraw early during an open round.

• Goal met — GRAM spent in clearing buys your tokens. New bids can still be placed until the window closes, pushing the clearing price up. Any unfilled GRAM from your bid is automatically refunded in batches after DEX deploy.
• Goal not met — after the auction lock ends, the contract automatically refunds your full committed GRAM in batched on-chain messages. Token allocations from partial clearing are voided. A manual Withdraw on the app page is optional and is a no-op once automatic refunds are processed.
• Unsold tokens roll over — each period adds its 1M-token base slice plus all accumulated unsold tokens from prior periods, through the final period
• Multiple bids — you can place more than one bid; each is tracked separately on-chain and contributes to your total allocation.
• Automatic batched refunds — refund messages are sent in batches to avoid gas limits, and each message pays its own gas out of the refunded GRAM.

This design removes sniping: bidding in the last seconds of a period does not let you pay less than everyone else who cleared in that same period. Competing on price means setting a budget and, if you want, a max price you are willing to pay per token across the remaining periods.

Each TMA launch uses a simplified periodic uniform-price auction on the auction contract. The diagram below is the end-to-end path for owners, supporters, and Gram Store admin.

Each auction round uses an on-chain auction contract with fixed rules:

• Funding goal: owner chooses 3,000 GRAM (unverified) or 10,000 GRAM (verified) (set at publish, cannot change after deploy)
• Minimum bid starts at floor price and ratchets up to the previous period's clearing price, so late bids must meet or beat the market
• The Commit UI enforces the current minimum max-price per token
• Publish fee: 2 GRAM to the Gram admin wallet (covers auction contract deploy, jetton mint, and STON.fi LP seed gas; paid once at publish via TON Connect)
• 3-day auction window — owner must start on-chain before bids are accepted
• 72% of supply sold via auction — 1% per clearing period (72 periods, 1 hours each)
• 72 uniform-price clearing periods (1 hour each) — everyone in a period fills at the same price; each period fills bids up to the per-wallet 2% token cap before unsold tokens roll into the next period
• Optional max price per token — if a period's clearing price exceeds your cap, your bid skips that period but can still participate later while budget remains
• Bids are locked until the goal is met or the auction lock ends — no early withdrawals while the round is open
• Over-subscription is allowed — total committed GRAM can exceed the goal; new bids are accepted until the 3-day window closes or refunds open
• Automatic batched refunds — at auction end (failed auction or DEX deploy), the contract sends back unfilled GRAM in batches to avoid gas limits; the refund transaction gas is deducted from the refunded amount
• If the goal is not met after the lock, the contract automatically returns full committed GRAM (partial clearing allocations are voided; no owner or manual action required)
• If the goal is met, GRAM spent in clearing funds Ston.fi liquidity; unfilled GRAM is returned automatically when the DEX is deployed after the auction lock ends
• DEX deployment is automatic — when the auction lock ends and the goal is reached, gram.store deploys the DEX and processes LP funding and token mints; no owner action is required

Auction progress is shown on each app page as a scale with total committed GRAM, participant count, and per-wallet allocation percentages.

See simulated auction examples with clearing-price charts, period logs, and filled-bidder tables for three demand patterns on a 3,000 GRAM goal.

Auction strategy and simulations →

Auction contracts hold bidder GRAM in a contributor escrow until the auction lock ends or funds are deployed to Ston.fi. What happens next depends on whether the funding goal was reached.

1. 1

   Goal not met

   After the 3-day lock, the contract automatically refunds your full committed GRAM in batched on-chain messages. Any tokens allocated in earlier partial clearings are voided. No manual transaction is required, but you can also send a Withdraw message from the app page to claim the same full amount.

2. 2

   Goal met — DEX launched

   GRAM spent in clearing is split at DEX deploy: 10% Gram Store treasury, 10% Graduation Bonus to the owner wallet, 80% Ston.fi LP. Bidders receive app tokens from their on-chain clearing allocation. Any unfilled GRAM from your bid is automatically refunded in batches after the DEX is deployed; the refund gas is deducted from the returned amount.

3. 3

   Goal met — bid partially filled

   If your bid did not spend its full budget across all 72 clearing periods (for example, your max price was below the clearing price in some periods, or demand did not absorb your per-wallet 2% token cap), you receive back the unfilled portion — committed GRAM minus GRAM already spent on tokens. Tokens you already received in clearing are kept. This is handled automatically after DEX deploy.

4. 4

   Goal met — automatic DEX launch

   Once the auction lock ends and the goal has been reached, gram.store automatically deploys the DEX, funds Ston.fi liquidity, mints app tokens, and refunds any unfilled GRAM in batches. No owner action or grace window is required.

The app reads on-chain goal state and your withdrawable balance so refunds stay available even if indexed commitment data is stale. Refunds are triggered automatically at auction end (failed auction or DEX deploy). They are processed in on-chain batches to stay within gas limits, and each refund message pays its own gas out of the returned GRAM. If an automatic refund has already been sent, sending a manual Withdraw is a no-op. If the goal is not met, the refund is your full committed GRAM; if the goal is met, the refund is only the unfilled portion (committed minus GRAM already spent on tokens).

When the auction lock ends and the goal is reached, gram.store automatically deploys the DEX. Gram Store:

• Deploys committed GRAM from the auction contract (10% Gram Store treasury, 10% Graduation Bonus to owner, 80% toward LP)
• Deploys a jetton with 100,000,000 fixed supply (9 decimals)
• Mints 72% to auction bidders (per on-chain clearing allocation)
• Seeds Ston.fi with 28% of supply paired with LP GRAM (minus a 0.25 GRAM gas reserve)
• Locks the owner LP position in an on-chain vesting vault
• Revokes further minting — supply is fixed

The owner's connected wallet is used as the default swap fee treasury at deploy — no separate treasury address is required before launch. An optional admin wallet (defaults to the same owner wallet) can update on-chain metadata and withdraw vested LP. Change the swap fee treasury later via Edit token. At DEX deploy, the Graduation Bonus (10% of bonded GRAM) is sent to your owner wallet; swap fees and withdrawn LP accrue there as well.

The owner's 28% LP share is locked in a dedicated on-chain vault. Vesting is expressed as a share of total token supply:

• 14% of supply — cliff unlock (Starter: month 3; Verified & Premium: month 6)
• 14% of supply — 2% per month for 7 months after the cliff (Starter: months 4–10; Verified & Premium: months 7–13)

After the cliff, the token admin wallet can withdraw vested LP from the vault — in full or in part (by percentage or exact LP amount). Withdrawn LP jettons arrive in the admin wallet; remove liquidity on Ston.fi to receive GRAM and app tokens.

Monitor cliff dates, vest progress, and available balances on the Edit token page (/tma/[id]/edit-token) under Owner unlock schedule.

Gram Store uses several fee layers:

• Publish fee: 2 GRAM — one-time payment to the Gram admin wallet when launching an auction (covers contract deploy, jetton mint, and STON.fi LP seed gas)
• Graduation Bonus: 10% of bonded GRAM to the owner wallet at DEX deploy (plus 10% Gram Store treasury and 80% Ston.fi LP, of GRAM spent in clearing)
• Swap fee: 0.75% on Ston.fi DEX trades — 0.25% of GRAM-side volume to Gram Store, 0.5% to owner swap fee wallet; 0.75% of paired-token volume to owner swap fee wallet (0% to Gram Store)

Live app swaps route through the app's Ston.fi pool directly (DEX v2), not only Omniston. Fee routing is baked into jetton metadata at deploy (gram-store://swap-fee). STON.fi applies the split on-chain. On DEX v2, a share of fees accrues in per-token referral vaults (one vault per treasury wallet × token) rather than landing instantly in your wallet. Omniston swaps (cross-chain and pre-pool auction tokens) pass integrator/referrer parameters with flexibleIntegratorFee so routes through DEX v1 (0.1% cap) remain eligible.

Collecting vault fees. The owner panel on live app pages shows treasury wallet balances and STON.fi vault accruals. To withdraw accrued vault fees, send a withdraw_fee message to your vault with about 0.3 GRAM attached for gas — the treasury wallet must hold enough GRAM to pay this. You can collect via the STON.fi vault UI (connect the treasury wallet) or the STON.fi SDK. Fees already in your treasury wallet balance are available immediately; vault balances must be collected separately.

Live app pages show accrued fee balances for owners. The swap fee treasury address can be updated later via Edit token.

Owners of live apps can:

• Edit listing metadata (name, logo, links, description) from the live app page
• Edit token — update swap fee wallet, name, description, and image on-chain
• Monitor owner vesting schedule and withdraw partial LP
• View Ston.fi trading link, treasury balances, and referral vault accruals
• Collect STON.fi vault fees (requires ~0.3 GRAM gas in the treasury wallet)

Supporters can favorite apps, track trades, and view commitments from Profile.

When creating or editing a listing, you provide:

• Ticker — short symbol (letters and numbers; locked after auction starts)
• Token name — on-chain jetton name (e.g. shown as $TICKER - name)
• App name — display name of your Mini App (locked after auction starts)
• App link — Telegram bot URL (https://t.me/…_bot)
• App logo — 1:1 image URL, min 256×256 px
• App banner — 3:1 image URL, min 600×200 px
• Short description — pitch for supporters (max 500 characters, no external links)
• Team profile links — 1–5 URLs for founders and contributors
• Telegram App Center link — optional; add a valid tapps.center listing URL to unlock 10,000 GRAM and show a Verified Badge on your app card
• Telegram community — optional group or channel link
• Web page — optional project site
• X page — optional social link

Gram Store uses several on-chain components:

• Auction contract — periodic uniform-price GRAM fundraising (3-day window, 72 hourly clearing periods, cumulative token rollover, cap-first bid filling), full refunds when the goal fails, partial unfilled refunds when the goal succeeds, automatic Ston.fi DEX deployment when the goal succeeds
• Jetton minter — 100M fixed-supply app tokens with swap-fee metadata
• LP lock vault — timelocked Ston.fi LP with cliff + linear vest for owners