Changelog
Every change to the contract these pages are built from.
This site is generated from one pinned copy of the API contract. When the pin moves, the pages change with it and the entry below records what moved. There is no earlier public version.
The deployed sandbox serves the operations on these pages.
1.0.0-draft.10
Pinned on 2026-11-13. A draft contract: no live provider availability is claimed.
Added in this contract:
POST /recipient-lookups, the account found at a username, for your customer to confirm before you quote.recipient_lookupon a quote and an order, andfoundon a quote'srecipient.- Three event types:
order.accepted,order.refundedanddeposit.confirmed. - USD credits:
usd,headline,activityandspending_currencyonGET /balance,pay_withon a quote,conversionon a credited GRAM deposit andgram_conversionon the statement. POST /sandbox/deposits, a simulated deposit that names its asset.balance_afteron the response that reserved an order, andpaymentandlineson a quote.- Display currencies are judged from two independent sources, and shown only when they are fresh and agree.
What the contract holds:
- Products:
telegram_starsandtelegram_premium, with provisional limits. - Quotes that lock a price for up to 60 seconds, and orders from a quote or direct with a
max_amount. - GRAM funding:
GET /funding/deposit-address,GET /funding/depositsandPOST /. Prices and reference rates:sandbox/ funding/ deposits GET /pricesandGET /rates. - Required
Idempotency-Keyon every request that changes the balance, replay withIdempotent-Replayed. An optional key on quotes, endpoints, rotations and delivery replays, bound permanently in the same way. - Balance with
available,heldandpending_funding; fundings and a statement. - Events with 30-day retention, of 10 types; webhook endpoints with signed deliveries (Standard Webhooks v1), retries, replay, secret rotation and test events.
RateLimit-PolicyandRateLimitheaders on every successful response and every 429.- RFC 9457 problems with 39 documented codes.
Earlier: since 1.0.0-draft.3
- The request sent to your endpoint is defined: its three headers, the signing scheme, the answers that count as delivered and the retry schedule.
POST /sends a marked, synthetic test event, at most 20 an endpoint in any hour.webhook-endpoints/ {id}/ test funding.creditedis raised once by every credited funding. Three event types that nothing raised, for a held funding, a low balance and a changed account, are removed.- The optional
Idempotency-Keyis bound permanently, in the database, instead of caching a response for 24 hours. A replay never returns a secret. limitsonGET /accountkeepsmax_queuedonly: the daily and per-order amounts are removed, because no such limit exists.kyb_statusgainsactive, for an organisation activated for live.- Every operation lists its
RateLimit-PolicyandRateLimitheaders and its 429 answer, and each that takes a body its 413. - The statement gains the
reversaltype, and ten problem codes are added, among theminvalid_api_key,key_expiredandservice_unavailable.
