---
title: "Quote a price"
method: GET
path: "/v1/pricing"
tags: ["Pricing"]
---

# Quote a price

`GET /v1/pricing`

Get a quote for an item in a payment currency. The `amount` is the full,
all-in total you'll send on-chain (in `currency`) — there's nothing else to
add.

The quote echoes back **what it priced** — `type` plus `quantity` (for
Stars) or `months` (for Premium); the field that doesn't apply is `null` —
so the `amount` is self-describing and you never have to correlate it to your
request.

The response also carries `quoted_at` + `valid_until` (a re-quote hint —
the price tracks the market and is recomputed about every minute; it is
locked only when you create an order) and `usdt_per_ton` (the current
public GRAM↔USDT rate, for your own conversion; `null` if
momentarily unavailable).

**Rate limit:** this endpoint carries a tighter per-tenant cap of 60
requests/min (in addition to the standard per-tenant budget). If you
exceed this, you receive a `429` and should back off for the remainder of
the minute.

## Query parameters

- `type` 'stars' | 'premium', required
- `quantity` integer
- `months` 3 | 6 | 12
- `payment_currency` 'ton' | 'usdt_ton' — `ton` = GRAM (ex TON), `usdt_ton` = USDT (TON).

## Response `200`

A price quote.

- Quote
  - `type` 'stars' | 'premium', required — The product this quote priced — echoed back from your request.
  - `quantity` integer, nullable, required — The number of Stars priced (when `type=stars`); `null` for Premium.
  - `months` integer, nullable, required — The Premium subscription length in months priced (when `type=premium`); `null` for Stars.
  - `amount` string, required — The full, all-in total to pay, as a decimal string in `currency`. Nothing else to add — send exactly this amount on-chain.
  - `currency` 'ton' | 'usdt_ton', required — `ton` = GRAM (ex TON), `usdt_ton` = USDT (TON).
  - `fee` FeeBreakdown, required — Itemisation of the `usdt_ton` processing fee that is ALREADY part of the all-in amount. `subtotal + processing_fee == total == amount`. Pass-through swap cost only — it does not reveal our cost basis or markup. Only `total` (= `amount`) is binding — the `subtotal`/`processing_fee` split is informational and may shift by a cent with the live FX rate.
    - `subtotal` string, required — The item price before the processing fee, as a decimal string (USDT).
    - `processing_fee` string, required — The 1% DEX swap fee + 0.5 GRAM swap gas, combined and rounded up to the cent, as a decimal string (USDT).
    - `total` string, required — subtotal + processing_fee — equals `amount`. Decimal string (USDT).
    - `description` string, required — Human-readable label for the fee components.
    - `currency` 'usdt', required — The unit of the fee amounts (always `usdt`).
  - `usdt_per_ton` string, nullable, required — The current indicative USDT per 1 GRAM (the field name `usdt_per_ton` is frozen for wire compatibility) — public market data you can use to convert GRAM↔USDT in your own interface. `null` if the rate is momentarily unavailable. This is NOT the amount you pay (that is `amount`); it is informational only.
  - `quoted_at` string, date-time, required — Server timestamp (ISO 8601) when this quote was computed.
  - `valid_until` string, date-time, required — A RE-QUOTE HINT (ISO 8601): the price tracks the market and is recomputed about every minute, so re-fetch after this time. It is **not** a price lock — the price is locked only when you create an order (`POST /v1/orders`), which fixes the amount for the order's payment window. Read `expires_at` on the order for that deadline — it is authoritative; do not assume a fixed duration.

## Other responses

- `400` — Malformed request.
- `401` — Missing or invalid `X-Api-Key`.
- `429` — A rate limit was reached — the per-minute request budget, the tighter pricing/recipient-check probe cap (60 req/min), the daily order cap, or the per-recipient flood guard. See **Rate limits** in the overview. The per-minute-budget responses also carry `RateLimit-*` + `Retry-After` headers.
- `503` — A required source was temporarily unavailable — either the price source, or recipient eligibility could not be verified right now. **Retryable**: reuse the same `Idempotency-Key` and try again shortly. No order is created and you are not charged.

---

[API](https://skmtc.net/mystars/apis/mystars-faas-fulfilment-api.md) · [All operations](https://skmtc.net/mystars/apis/mystars-faas-fulfilment-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mystars/mystars-faas-fulfilment-api/revisions/3c24cb3dfa12/schema)