Skip to content

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_lookup on a quote and an order, and found on a quote's recipient.
  • Three event types: order.accepted, order.refunded and deposit.confirmed.
  • USD credits: usd, headline, activity and spending_currency on GET /balance, pay_with on a quote, conversion on a credited GRAM deposit and gram_conversion on the statement.
  • POST /sandbox/deposits, a simulated deposit that names its asset.
  • balance_after on the response that reserved an order, and payment and lines on 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_stars and telegram_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/deposits and POST /sandbox/funding/deposits. Prices and reference rates: GET /prices and GET /rates.
  • Required Idempotency-Key on every request that changes the balance, replay with Idempotent-Replayed. An optional key on quotes, endpoints, rotations and delivery replays, bound permanently in the same way.
  • Balance with available, held and pending_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-Policy and RateLimit headers 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 /webhook-endpoints/{id}/test sends a marked, synthetic test event, at most 20 an endpoint in any hour.
  • funding.credited is 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-Key is bound permanently, in the database, instead of caching a response for 24 hours. A replay never returns a secret.
  • limits on GET /account keeps max_queued only: the daily and per-order amounts are removed, because no such limit exists.
  • kyb_status gains active, for an organisation activated for live.
  • Every operation lists its RateLimit-Policy and RateLimit headers and its 429 answer, and each that takes a body its 413.
  • The statement gains the reversal type, and ten problem codes are added, among them invalid_api_key, key_expired and service_unavailable.