Fragment APIREST v1

One formula. Live provider pricing.

Fragment API charges the current provider amount plus a 5% service margin for both Telegram Stars and Premium. The order currency follows the balance you choose.

Service margin

Stars and Premium

Settlement assets

TON or USDT on TON

100%

Failed-order return

Full reserved order amount

Price formula

order_total = provider_amount + (provider_amount × 0.05)

Equivalently: order_total = provider_amount × 1.05.

Component	Rule	Example
`base_amount`	Live provider amount	10.000000 TON
`margin_amount`	5% of the provider amount	0.500000 TON
`amount`	Balance reserved for the order	10.500000 TON

The numbers above illustrate the formula; they are not a product quote. Stars and Premium provider prices can change.

Use live prices, not a cached rate card

The exact amount is resolved when the order is created. The successful 202 response returns amount, which is the total reserved from the selected wallet and already includes the 5% service margin.

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "username": "alexdev",
  "quantity": 100,
  "amount": 10.5,
  "created_at": "2026-09-21T10:30:00Z"
}

For Premium display pricing, call GET /premium/packages. Its usd_value and ton_value are presentation values with the service margin included. The created order remains the authoritative charge.

TON and USDT orders use the same 5% formula, but they are independent balances. The API never converts one developer balance into the other.

Set your own customer price

Fragment API does not enforce the price you show your customers. Your gross resale spread is the amount you collect before tax, less the Fragment API order total and your own payment or operating costs.

gross_spread = customer_price_ex_vat

− fragment_api_order_total

− your_payment_and_operating_costs

Do not calculate your resale price from the provider amount alone. The value charged to your balance is amount, which already includes our 5% margin.

VAT and local taxes

The API does not calculate, add, collect, or remit VAT. The order amount is the provider amount plus the 5% Fragment API service margin only.

If your business must charge VAT or another local tax, calculate it in your own checkout and keep it separate from the Fragment API order amount. Tax treatment depends on your entity, customer, and jurisdiction, so confirm the correct approach with your tax adviser.

Failed orders return the reserved amount

When the system can definitively determine that a queued order failed before a successful blockchain settlement, it returns the full reserved amount to the same TON or USDT balance. The refund is recorded as a separate wallet transaction.

Field	Meaning
`refunded`	`true` confirms that the balance return was recorded.
`refund_amount`	The full order amount restored to the selected balance.
`refund_transaction_id`	The wallet transaction created for the return.

If a blockchain broadcast may already have occurred, the order can remain processing while recovery checks the chain. Do not retry with a new idempotency key until the existing order reaches a final state.