Документация

REST API FragmentationX

Stars, Premium и NFT-подарки Fragment одним HTTP-запросом. Обычный JSON, без SDK и вебхуков.

Base URLhttps://api.fragmentationx.net/v1
API живёт только на api.fragmentationx.net. На основном домене (fragmentationx.net) Bearer-токен не работает нигде — там только сайт и кабинет на сессионных cookie.

Все эндпоинты

Нажмите на любой, чтобы перейти к подробному описанию ниже.

GET/meБаланс и адрес для пополнения GET/recipientЕсть ли такой username в Telegram, имя и аватар GET/stars/quoteЦена Stars — получатель не нужен GET/premium/quoteЦена Premium — получатель не нужен GET/gift/quoteЦена NFT-подарка вместе с доставкой GET/username/quoteЦена коллекционного username вместе с доставкой GET/number/quoteЦена анонимного номера вместе с доставкой GET/giftsВитрина подарков: фильтр по коллекции, модели, фону и символу — коллекция не обязательна GET/gift/{slug}Модель, фон, символ одного подарка и их редкость GET/gifts/pageТо же, что /gifts, но постранично: следующие 60 подарков по offset GET/gifts/collectionsСписок коллекций подарков и их slug GET/gifts/attributesМодели, фоны и символы одной коллекции GET/usernamesВитрина username, выставленных на продажу сейчас GET/numbersВитрина номеров, выставленных на продажу сейчас GET/orders/{id}Статус одного заказа GET/ordersСписок ваших заказов POST/starsКупить Telegram Stars POST/premiumПодарить Telegram Premium POST/giftКупить NFT-подарок, доставка на username или TON-адрес POST/usernameКупить username, доставка на TON-адрес POST/numberКупить номер, доставка только на TON-адрес GET/rent/gifts · /rent/usernames · /rent/numbersЧто сдаётся в аренду на marketapp.org сейчас GET/rent/{gift,username,number}/quoteТочная цена аренды на выбранный срок POST/rent/{gift,username,number}Арендовать подарок, username или номер POST/rent/attachПоказать арендованный подарок или username в профиле Telegram GET/rent/attach/{id}Статус привязки к профилю

Аутентификация

Токен выдаётся в кабинете после входа через Telegram. Передавайте его в заголовке на каждый запрос к api.fragmentationx.net:

Authorization: Bearer <ваш токен>

Без заголовка или с неверным токеном любой эндпоинт вернёт 401. Токен даёт полный доступ к балансу — храните его как пароль и перевыпускайте в кабинете, если он утёк.

Формат ошибок

Ошибка — это JSON с полем error и соответствующим HTTP-статусом:

{ "error": "Количество звёзд: от 50 до 1 000 000." }
КодЗначит
400Некорректный запрос (не JSON)
401Нет или неверен Bearer-токен
402Недостаточно средств на балансе
409Цена выросла выше max_price — в ответе свежая котировка
422Ошибка валидации или получатель не найден на Fragment
429Только у /gifts без collection: поиск по всей витрине запускается не чаще раза в минуту
503Fragment (или marketapp.org для аренды) временно недоступен, или сервис не может оплатить заказ прямо сейчас

Статусы заказов

Заказ асинхронный: POST /stars (или /premium, /gift) сразу списывает баланс и возвращает заказ в статусе queued, дальше опрашивайте GET /orders/{id}.

queued processing done
СтатусЗначит
queuedПринят, ждёт очереди на выполнение
processingПокупается и/или доставляется прямо сейчас
doneВыполнен полностью
refundedFragment отклонил заказ до оплаты — сумма автоматически вернулась на баланс
reviewСбой уже после оплаты — проверяется вручную, баланс не трогается автоматически
GET

/me

Баланс и реквизиты для пополнения текущего аккаунта.

пример ответа
GET /v1/me

{
  "tg_username": "your_username",
  "balance": { "TON": "12.5", "USDT": "0" },
  "deposit": {
    "address": "UQA-wrI6cqWZPc3Vr3PC-9IBg12WzuDQEMbz8Fpg57DKTTIt",
    "comment": "FRG-A1B2C3D4"
  }
}
GET

/recipient

Проверяет, существует ли пользователь Telegram с таким username, и отдаёт его имя и аватар — без привязки к товару и без списаний.

ПараметрОбязателенЗначит
usernameдаБез «@», 4–32 символа
найден
GET /v1/recipient?username=durov

{
  "found": true,
  "username": "durov",
  "name": "Pavel",
  "avatar_url": "https://cdn4.telesco.pe/file/..."
}
не найден
GET /v1/recipient?username=nosuchuser404

{
  "found": false,
  "username": "nosuchuser404",
  "reason": "Пользователь с таким username не найден."
}

Если аватар не установлен, Fragment отдаёт сгенерированную SVG-заглушку — avatar_url тогда будет data:image/svg+xml;base64,…, а не null: реальную фотографию отличает https://.

Цены: GET /<товар>/quote

У каждого товара есть парный GET-эндпоинт, который считает цену и ничего не списывает: те же параметры, что у POST, но в query-строке. Это отдельные эндпоинты со своими разделами ниже — /stars/quote, /premium/quote, /gift/quote, /username/quote, /number/quote.

Получатель для цены не нужен. username, handle и to_address в quote необязательны: цена от получателя не зависит. Раньше /premium/quote без @username не отвечал вовсе, а с ним упирался в правило Fragment «у этого пользователя уже есть Premium» — теперь цену видно всегда.

Если получателя всё-таки передать, ответ дополнительно проверит его на стороне Fragment и вернёт recipient_name с avatar_url; без него оба поля — null. Сама цена в обоих случаях одна и та же.

Поля ответа

ПолеТипЗначит
priceстрокаИтог к списанию в валюте запроса — ровно столько снимет POST
price_unitsцелоеТа же сумма в минимальных единицах (нанотоны для TON, 10⁻⁶ для USDT). Сравнивайте цены по нему, а не по строке
fragment_priceстрокаСколько из этого берёт сам Fragment
extra_feeстрокаКомиссия за доставку NFT (0.1 TON). У Stars и Premium всегда "0"
commission_percentстрокаНаценка сервиса в процентах, уже учтена в price
recipient_nameстрока / nullИмя получателя в Telegram, если он был указан
avatar_urlстрока / nullАватар получателя, если он был указан

Ответ также повторяет присланные параметры (kind, currency, quantity, months, slug, handle), а у товаров с маркетплейса добавляет название и картинку предмета — см. примеры ниже. Цена живёт около 30 секунд: POST всё равно пересчитает её заново, поэтому передавайте max_price, если не хотите платить больше увиденного.

GET

/stars/quote

Цена Telegram Stars. Зависит только от количества — получателя указывать не нужно.

ПараметрОбязателенЗначит
quantityдаЦелое число, 50–1 000 000
currencyнетTON (по умолчанию) или USDT
usernameнетПолучатель без «@». На цену не влияет, но добавит в ответ его имя и аватар
без получателя
GET /v1/stars/quote?quantity=100

{
  "kind": "stars",
  "currency": "TON",
  "quantity": 100,
  "recipient_name": null,
  "avatar_url": null,
  "commission_percent": "2",
  "fragment_price": "1.0921",
  "extra_fee": "0",
  "price_units": 1113942000,
  "price": "1.113942"
}
с получателем, в USDT
GET /v1/stars/quote?quantity=100&currency=USDT&username=nikolay

{
  "kind": "stars",
  "currency": "USDT",
  "username": "nikolay",
  "quantity": 100,
  "recipient_name": "Nikolay Kolev",
  "avatar_url": "https://cdn1.telesco.pe/file/...",
  "commission_percent": "2",
  "fragment_price": "1.5",
  "extra_fee": "0",
  "price_units": 1530000,
  "price": "1.53"
}

В USDT Fragment продаёт Stars по фиксированным $0,015 за штуку, в TON — по текущему курсу, поэтому цена в TON заметно плавает между запросами. Покупка — POST /stars.

GET

/premium/quote

Цена Telegram Premium на 3, 6 или 12 месяцев. Прайс у Fragment общий для всех, поэтому получатель не нужен.

ПараметрОбязателенЗначит
monthsда3, 6 или 12
currencyнетTON (по умолчанию) или USDT
usernameнетПолучатель без «@». Добавит имя и аватар — и заодно проверит, что ему вообще можно дарить Premium
3 месяца, TON
GET /v1/premium/quote?months=3

{
  "kind": "premium",
  "currency": "TON",
  "months": 3,
  "recipient_name": null,
  "avatar_url": null,
  "commission_percent": "2",
  "fragment_price": "8.73",
  "extra_fee": "0",
  "price_units": 8904600000,
  "price": "8.9046"
}
12 месяцев, USDT
GET /v1/premium/quote?months=12&currency=USDT

{
  "kind": "premium",
  "currency": "USDT",
  "months": 12,
  "recipient_name": null,
  "avatar_url": null,
  "commission_percent": "2",
  "fragment_price": "28.99",
  "extra_fee": "0",
  "price_units": 29569800,
  "price": "29.5698"
}
С username ответ уже зависит от получателя: если у него есть Premium или это канал/бот, Fragment откажет и вернётся 422. Цена при этом всё равно доступна — просто запросите тот же quote без username.
GET

/gift/quote

Цена конкретного NFT-подарка вместе с доставкой. slug и price берутся из GET /gifts. Только TON.

ПараметрОбязателенЗначит
slugдаИдентификатор экземпляра, напр. bdaycandle-247342
priceдаЦена из витрины, в TON. Если на Fragment она уже другая — 422
username или to_addressнетПолучатель. На цену не влияет; для POST обязателен ровно один из двух
пример ответа
GET /v1/gift/quote?slug=bdaycandle-247342&price=5

{
  "kind": "gift",
  "currency": "TON",
  "slug": "bdaycandle-247342",
  "recipient_name": null,
  "avatar_url": null,
  "commission_percent": "2",
  "fragment_price": "5",
  "extra_fee": "0.1",
  "price_units": 5202000000,
  "price": "5.202",
  "gift_title": "B-Day Candle #247342",
  "gift_image": "https://nft.fragment.com/gift/bdaycandle-247342.webp",
  "item_price": "5"
}

price (5.202) = цена подарка (5) + доставка (0.1) + наценка 2%. Покупка — POST /gift.

GET

/username/quote

Цена коллекционного @username вместе с доставкой. handle и price берутся из GET /usernames. Только TON.

ПараметрОбязателенЗначит
handleдаПокупаемый username без «@»
priceдаЦена из витрины, в TON
to_addressнетTON-адрес получателя. На цену не влияет; для POST обязателен. С username вернётся 422
пример ответа
GET /v1/username/quote?handle=a5x6x&price=7

{
  "kind": "username",
  "currency": "TON",
  "handle": "a5x6x",
  "recipient_name": null,
  "avatar_url": null,
  "commission_percent": "2",
  "fragment_price": "7",
  "extra_fee": "0.1",
  "price_units": 7242000000,
  "price": "7.242",
  "item_title": "@a5x6x",
  "item_price": "7"
}

Покупка — POST /username.

GET

/number/quote

Цена анонимного номера +888 вместе с доставкой. slug и price берутся из GET /numbers. Только TON.

ПараметрОбязателенЗначит
slugдаЦифры номера, напр. 88802596343
priceдаЦена из витрины, в TON
to_addressнетTON-адрес получателя. На цену не влияет; для POST обязателен. username у номеров не бывает — с ним вернётся 422
пример ответа
GET /v1/number/quote?slug=88802596343&price=2720

{
  "kind": "number",
  "currency": "TON",
  "slug": "88802596343",
  "recipient_name": null,
  "avatar_url": null,
  "commission_percent": "2",
  "fragment_price": "2720",
  "extra_fee": "0.1",
  "price_units": 2774502000000,
  "price": "2774.502",
  "item_title": "+888 0259 6343",
  "item_price": "2720"
}

Покупка — POST /number.

POST

/stars

Купить Telegram Stars. Цена всегда пересчитывается заново на сервере в момент запроса — посмотреть её заранее, ничего не покупая, можно через GET /stars/quote. Если передать max_price и цена вырастет выше него, вернётся 409 без списания. Отправка всегда анонимная — получатель не видит, кто купил.

ПолеОбязательноЗначит
usernameдаПолучатель, без «@»
quantityдаЦелое число, 50–1 000 000
currencyнетTON (по умолчанию) или USDT
max_priceнетПотолок цены в указанной валюте, напр. "1.10"
пример
curl -X POST https://api.fragmentationx.net/v1/stars \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"durov","quantity":100,"currency":"TON","max_price":"1.10"}'

{
  "id": 1042,
  "kind": "stars",
  "status": "queued",
  "error": null,
  "currency": "TON",
  "amount": "1.0993",
  "item": { "username": "durov", "recipient_name": "Pavel", "quantity": 100 },
  "created_at": "2026-09-18T09:07:20Z",
  "updated_at": "2026-09-18T09:07:20Z"
}
POST

/premium

Подарить Telegram Premium. Цена — GET /premium/quote, покупка — этот POST; та же пара, что и у /stars. Отправка всегда анонимная — получатель не видит, кто подарил.

ПолеОбязательноЗначит
usernameдаПолучатель, без «@»
monthsда3, 6 или 12
currencyнетTON (по умолчанию) или USDT
max_priceнетПотолок цены в указанной валюте
пример
curl -X POST https://api.fragmentationx.net/v1/premium \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"durov","months":3,"currency":"TON"}'

{
  "id": 1043,
  "kind": "premium",
  "status": "queued",
  "currency": "TON",
  "amount": "14.9",
  "item": { "username": "durov", "recipient_name": "Pavel", "months": 3 },
  "created_at": "2026-09-18T09:07:20Z",
  "updated_at": "2026-09-18T09:07:20Z"
}

Если у получателя уже есть Premium, Fragment откажет — заказ вернёт 422 ещё на этапе создания, ничего не спишется.

POST

/gift

Купить NFT-подарок с маркетплейса Fragment. Цена без покупки — GET /gift/quote. slug и price берутся из GET /gifts — Fragment продаёт подарки поштучно, не по коллекции, поэтому сначала нужно найти конкретный экземпляр (см. раздел ниже). Валюта только TON.

ПолеОбязательноЗначит
slugдаИз GET /gifts, напр. plushpepe-1
priceдаТекущая цена в TON из GET /gifts
username или to_addressда, ровно одинКуда доставить — см. доставка
max_priceнетПотолок цены в TON
пример — доставка на username
curl -X POST https://api.fragmentationx.net/v1/gift \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"plushpepe-1","price":"5","username":"durov","max_price":"5.20"}'

{
  "id": 1044,
  "kind": "gift",
  "status": "queued",
  "currency": "TON",
  "amount": "5.1",
  "item": {
    "username": "durov", "recipient_name": "Pavel",
    "gift_title": "Plush Pepe #1",
    "gift_image": "https://nft.fragment.com/gift/plushpepe-1.webp"
  },
  "created_at": "2026-09-18T09:07:20Z",
  "updated_at": "2026-09-18T09:07:20Z"
}

amount (5.1) уже включает цену подарка (5) плюс комиссию за доставку (0.1 TON) — см. доставка ниже.

GET

/gifts

Витрина NFT-подарков, выставленных на продажу на Fragment прямо сейчас. Кроме коллекции фильтрует по атрибутам экземпляра — модели, фону и символу. Коллекция при этом не обязательна: можно искать по фону и символу сразу по всей витрине.

ПараметрОбязателенЗначит
collectionнетslug из GET /gifts/collections — не название. Без фильтров по атрибутам неверный slug молча игнорируется и вернутся все коллекции; вместе с ними — проверяется и даёт 422
modelнетМодель, напр. Ice Crackle
backdropнетФон, напр. Black
symbolнетСимвол (узор), напр. Fire
sortнетprice_asc (по умолчанию), price_desc, listed или ending
queryнетПоиск по названию/атрибуту

У каждого из трёх фильтров можно перечислить несколько значений — повторив параметр или через запятую; внутри одного атрибута это «или», между разными атрибутами — «и». Регистр значения не важен, само слово должно совпадать со списком из GET /gifts/attributes. Фоны и символы у коллекций общие, поэтому список из любой коллекции годится как справочник названий и для поиска по всей витрине.

по всей витрине
# чёрный фон + символ «Fire», любая коллекция
GET /v1/gifts?backdrop=Black&symbol=Fire

[
  {
    "slug": "whipcupcake-206524",
    "name": "Whip Cupcake",
    "num": "#206524",
    "price": "22",
    "image": "https://nft.fragment.com/gift/whipcupcake-206524.webp"
  },
  ... дальше Snake Box, Evil Eye и т.д. — дешёвые сверху
]
внутри коллекции
# «Ice Crackle» или «Stardust» на чёрном фоне
GET /v1/gifts?collection=bdaycandle&model=Ice+Crackle,Stardust&backdrop=Black

[
  {
    "slug": "bdaycandle-154118",
    "name": "B-Day Candle",
    "num": "#154118",
    "price": "50",
    "image": "https://nft.fragment.com/gift/bdaycandle-154118.webp"
  }
]

Чем отличается поиск без коллекции

У самого Fragment фильтра «по всей витрине» нет: его атрибутные фильтры действуют только внутри коллекции, а на общей странице просто игнорируются. Поэтому запрос без collection мы собираем сами — прогоняем точный фильтр по каждой из ~120 коллекций (не спеша, чтобы Fragment не начал придерживать ответы) и объединяем результат. Отсюда два отличия:

ЧтоС коллекциейБез коллекции
скорость~0.1 с~15–20 с на холодную, дальше 5 минут из кэша
sortлюбойтолько price_asc / price_desc — иначе 422
Перебор всей витрины — единственная тяжёлая операция этого API, и Fragment это замечает: если гонять переборы подряд, он начинает придерживать поиск, и тогда перестают работать даже обычные запросы с collection. Поэтому новый перебор запускается не чаще раза в минуту (429, если раньше), результат живёт в кэше 5 минут, а коллекции без нужного атрибута запоминаются на час — повторный поиск по тому же фону или символу стоит уже не 120 запросов, а несколько. Если Fragment всё-таки придержал ответы, вернётся 503 с прямым текстом; отпускает за минуту.

Опечатка в значении в обоих случаях даёт 422, но ловится по-разному. С коллекцией значение сверяется с её списком атрибутов заранее. Без коллекции сверять не с чем — там каждая найденная позиция проверяется по собственным метаданным подарка (в них прямо записаны Model, Backdrop и Symbol): если не подтвердилась ни одна, значит Fragment отдал витрину без учёта фильтра, и вместо чужих позиций вы получите ошибку.

Отбор в обоих случаях точный — это родной фильтр Fragment, а не поиск по словам: symbol=Fire не притащит «Oxen of Fire». Отдаются только позиции со статусом «For sale», максимум 60 штук по sort; без коллекции это 60 самых дешёвых (или дорогих) по всей витрине. Следующие — через /gifts/page, в том числе без коллекции. Ответ с коллекцией кэшируется на 30 секунд, без коллекции — на 5 минут: один такой запрос обходит всю витрину Fragment, и чаще его гонять незачем.

GET

/gifts/page

GET /gifts отдаёт только первые 60 подарков. /gifts/page — та же витрина с теми же параметрами, но постранично, как бесконечная прокрутка на самом Fragment: в ответе рядом с подарками лежит next_offset, и запрос с ним возвращает следующие 60.

ПараметрОбязателенЗначит
collection, model, backdrop, symbol, sort, queryнетКак у /gifts. Для следующих страниц передавайте те же значения, что и для первой
offsetнетnext_offset из предыдущего ответа, как есть. Без него — первая страница
пример
# первая страница
GET /v1/gifts/page?collection=plushpepe&sort=price_asc

{
  "items": [ ... 60 подарков, как в /gifts ... ],
  "next_offset": "60"
}

# следующая — те же параметры плюс offset
GET /v1/gifts/page?collection=plushpepe&sort=price_asc&offset=60

{
  "items": [ ... ещё 14 ... ],
  "next_offset": null   // дальше ничего нет
}

next_offset: null — это последняя страница. Витрина живая: пока вы листаете, цены меняются, поэтому один и тот же подарок изредка может попасть на две соседние страницы — отсеивайте повторы по slug. Поиск по атрибутам без collection листается так же, и порядок по цене сохраняется на всех страницах: первый запрос обходит всю витрину (см. выше), а следующие страницы берутся из его результата и при необходимости догружают по одной коллекции — это быстро и не упирается в лимит «раз в минуту». Результат обхода живёт 5 минут; если листать дольше, следующая страница запустит новый обход и может получить 429. Неверный offset — 422. Страница с коллекцией кэшируется на 30 секунд.

GET

/gift/{slug}

Всё, что Fragment знает о конкретном экземпляре: его модель, фон и символ с редкостью каждого, владелец, тираж и цена, если подарок выставлен на продажу. slug — полный, с номером: plushpepe-1, bdaycandle-247342.

пример ответа
GET /v1/gift/bdaycandle-247342

{
  "slug": "bdaycandle-247342",
  "title": "B-Day Candle #247342",
  "collection": "bdaycandle",
  "num": 247342,
  "image": "https://nft.fragment.com/gift/bdaycandle-247342.webp",
  "owner": "UQAOGen7g1cF6aA-ChkDun8JBzefvCLMFbiBb86rcbOGE_FN",
  "status": "For sale",
  "for_sale": true,
  "price": "5",
  "issued": 271329,
  "total_supply": 307521,
  "attributes": {
    "model":    { "value": "Ice Crackle", "rarity_percent": "1.5", "one_in": 67 },
    "backdrop": { "value": "Coral Red",   "rarity_percent": "2",   "one_in": 50 },
    "symbol":   { "value": "Firebird",    "rarity_percent": "0.5", "one_in": 200 }
  },
  "combined": { "rarity_percent": "0.00015", "one_in": 666667 }
}
ПолеТипЗначит
attributesобъектТри атрибута: model, backdrop, symbol
rarity_percentстрокаДоля подарков коллекции с этим значением — процент самого Fragment
one_inцелоеТо же самое словами «один из N»: 0.5% — это один из 200
combinedобъектШанс выбить именно такое сочетание всех трёх атрибутов сразу
for_saleboolПродаётся ли прямо сейчас; тогда в price цена в TON — её можно сразу передать в POST /gift
issuedцелоеСколько выпущено из total_supply возможных

Проценты — те, что Fragment показывает у себя на странице подарка, и они округлены до одного знака. Поэтому combined (произведение трёх: атрибуты разыгрываются независимо друг от друга) — оценка той же точности, а не пересчёт по штукам. Считать редкость по числу лотов в /gifts нельзя: там видно только то, что выставлено на продажу — у этого подарка 354 «Ice Crackle» в продаже против 1.5% от 307 521 выпущенных.

Неизвестный slug даёт 422: Fragment на такой адрес молча отдаёт общую витрину, поэтому «подарка нет» определяется по отсутствию у страницы атрибутов. Ответ кэшируется на 30 секунд — редкость не меняется никогда, а владелец и цена меняются.

GET

/gifts/collections

Все коллекции подарков: имя, как оно выглядит на Fragment, и slug — то, что реально принимает параметр collection у /gifts.

пример ответа
GET /v1/gifts/collections

[
  { "name": "Plush Pepes", "slug": "plushpepe" },
  { "name": "Chill Flames", "slug": "chillflame" },
  ...
]
GET

/gifts/attributes

Модели, фоны и символы, которые реально есть в одной коллекции — то есть допустимые значения параметров model, backdrop и symbol у GET /gifts.

ПараметрОбязателенЗначит
collectionдаslug из GET /gifts/collections. Незнакомый slug — 422
пример ответа
GET /v1/gifts/attributes?collection=bdaycandle

{
  "models":    ["Ice Crackle", "Candy Message", "Stardust", ...],
  "backdrops": ["Black", "Onyx Black", "Ivory White", ...],
  "symbols":   ["Toilet Paper", "Fire", "Leaf", ...]
}

Списки приходят в том же порядке, что и в фильтрах на fragment.com — сначала самые частые. Это полный набор атрибутов коллекции, а не только то, что сейчас продаётся: сочетание может существовать, но не иметь ни одного лота в продаже — тогда /gifts честно вернёт пустой массив. Ответ кэшируется на час.

Модели у каждой коллекции свои, а фоны и символы общие — «Black» и «Fire» встречаются во многих коллекциях. Поэтому для поиска по всей витрине (/gifts без collection) названия фона и символа можно брать из любой коллекции: отдельного «глобального» справочника у Fragment нет.

POST

/username

Купить коллекционный @username с маркетплейса Fragment. Цена без покупки — GET /username/quote. handle и price берутся из GET /usernames. Валюта только TON. Названо handle, а не username, чтобы не путать покупаемый username с полем username получателя в этом же запросе.

ПолеОбязательноЗначит
handleдаПокупаемый username, без «@», из GET /usernames
priceдаТекущая цена в TON из GET /usernames
to_addressдаTON-адрес получателя — у username нет доставки по Telegram username
max_priceнетПотолок цены в TON
пример
curl -X POST https://api.fragmentationx.net/v1/username \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"handle":"a5x6x","price":"7","to_address":"UQ...","max_price":"7.30"}'

{
  "id": 1045,
  "kind": "username",
  "status": "queued",
  "currency": "TON",
  "amount": "7.242",
  "item": {
    "handle": "a5x6x", "item_title": "@a5x6x",
    "to_address": "UQ..."
  },
  "created_at": "2026-09-18T09:07:20Z",
  "updated_at": "2026-09-18T09:07:20Z"
}

Доставка только на to_address — напрямую в блокчейн. У Fragment нет передачи username на Telegram-аккаунт («Transfer to Telegram» есть только у подарков): владелец потом сам привязывает его к аккаунту на fragment.com, войдя кошельком. С username вернётся 422.

GET

/usernames

Витрина коллекционных @username, выставленных на продажу на Fragment прямо сейчас.

ПараметрОбязателенЗначит
sortнетprice_asc (по умолчанию), price_desc или listed
queryнетПоиск по названию
пример ответа
GET /v1/usernames?sort=price_asc

[
  { "handle": "a5x6x", "price": "7" },
  { "handle": "ahuboss", "price": "7" }
]
POST

/number

Купить анонимный номер +888 с маркетплейса Fragment. Цена без покупки — GET /number/quote. slug и price берутся из GET /numbers. Валюта только TON.

ПолеОбязательноЗначит
slugдаИз GET /numbers, напр. 88802596343
priceдаТекущая цена в TON из GET /numbers
to_addressдаTON-адрес получателя — у номеров нет доставки по username, см. ниже
max_priceнетПотолок цены в TON
пример
curl -X POST https://api.fragmentationx.net/v1/number \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"88802596343","price":"2720","to_address":"UQ...","max_price":"2800"}'

{
  "id": 1046,
  "kind": "number",
  "status": "queued",
  "currency": "TON",
  "amount": "2774.502",
  "item": { "item_title": "+888 0259 6343", "to_address": "UQ..." },
  "created_at": "2026-09-18T09:07:20Z",
  "updated_at": "2026-09-18T09:07:20Z"
}
У номеров нет доставки на username — Fragment не показал рабочего пути передать купленный номер другому аккаунту внутри своего интерфейса, поэтому передавать поле username для kind: number нельзя, запрос вернёт 422. Только to_address.
GET

/numbers

Витрина анонимных номеров, выставленных на продажу на Fragment прямо сейчас.

ПараметрОбязателенЗначит
sortнетprice_asc (по умолчанию), price_desc или listed
queryнетПоиск по цифрам номера
пример ответа
GET /v1/numbers?sort=price_asc

[
  { "slug": "88802596343", "number": "+888 0259 6343", "price": "2720" }
]
GET

/orders/{id}

Текущий статус одного заказа, тот же формат, что в ответе на создание. Опрашивайте раз в несколько секунд, пока статус не станет финальным (done, refunded или review).

GET

/orders

Список ваших заказов (любого товара), новые сверху. Возвращает массив объектов в том же формате.

Как устроена аренда

Аренда идёт через маркетплейс marketapp.org: NFT-подарки, коллекционные @username и анонимные номера +888, которые владельцы сдают на срок. Оплата только в TON, с баланса — так же, как покупки.

ШагЧто делать
1Выбрать лот: GET /rent/usernames (или /rent/gifts, /rent/numbers). Из ответа понадобятся nft_address, price_per_day, min_days/max_days и sale_during_rent.
2Узнать цену: GET /rent/username/quote с теми же полями и сроком days. Необязательно, но так видно итоговую сумму.
3Арендовать: POST /rent/username. Деньги списываются сразу, заказ уходит в очередь; опрашивайте GET /orders/{id} до done — там же появится rent_until.
4Показать в профиле Telegram (подарки и username): POST /rent/attach с номером заказа. В ответе — ссылка login_url: её открывают в Telegram от нужного аккаунта и нажимают «Log In», дальше всё делает сервис. Статус — GET /rent/attach/{id}.
Арендованный NFT не переходит ни к вам, ни к получателю: его держит контракт аренды до конца срока, а заказ в FragmentationX — подтверждение, что аренда ваша. Поэтому у аренды нет username/to_address получателя: к конкретному аккаунту NFT привязывается отдельным шагом 4.
GET

/rent/gifts · /rent/usernames · /rent/numbers

Лоты, которые сдаются в аренду прямо сейчас, по 100 за страницу.

ПараметрОбязателенЗначит
sortнетrecently_touch (по умолчанию), price_per_day_asc, price_per_day_desc, min_price, duration_asc, duration_desc, item_num_asc, item_num_desc
cursorнетnext_cursor из предыдущего ответа — следующая страница (с тем же sort). null — страниц больше нет
пример ответа
GET /v1/rent/usernames?sort=price_per_day_asc

{
  "items": [
    {
      "nft_address": "EQDfVq2dZqAKY0z-f5ldYeSQljpGMExnmC4aY1ivSu0FSHHI",
      "name": "@djbwq",
      "image": "https://i2.anton.market/...",
      "price_per_day": "0.0068",
      "min_days": 180,
      "max_days": 180,
      "discount_per_day_percent": "0",
      "sale_during_rent": false,
      "full_price": null
    }
  ],
  "next_cursor": "rY--yPrgYVnR9dum..."
}
ПолеЗначит
nft_addressАдрес NFT — по нему арендуют и привязывают
price_per_dayЦена за сутки в TON, без комиссии сервиса
min_days / max_daysНа какой срок можно взять. Если они равны — только на этот срок
discount_per_day_percentСкидка в процентах за каждый день после первого, но не больше 50% в сумме
sale_during_renttrue — владелец может продать NFT во время аренды: аренда тогда закончится раньше, а уплаченное вернётся. Такой лот можно взять, только явно передав sale_during_rent: true
full_priceТолько у старых контрактов: фиксированная цена за весь срок. Если не null — передайте её при аренде
GET

/rent/{gift,username,number}/quote

Точная сумма за аренду, которая спишется с баланса. Сервис спрашивает её у marketapp.org с теми же параметрами, с какими будет платить, поэтому цифра настоящая, а не оценка. Ничего не списывает.

ПараметрОбязателенЗначит
nft_addressдаИз витрины
daysдаСрок в днях, от min_days до max_days лота
price_per_dayдаИз витрины, в TON, как есть
sale_during_rentнетКак в витрине; по умолчанию false
full_priceнетТолько если в витрине он не null
пример
GET /v1/rent/username/quote?nft_address=EQDfVq2d...SHHI&days=180&price_per_day=0.0068

{
  "kind": "rent_username",
  "nft_address": "EQDfVq2dZqAKY0z-f5ldYeSQljpGMExnmC4aY1ivSu0FSHHI",
  "item_title": "@djbwq",
  "days": 180,
  "price_per_day": "0.0068",
  "rent_price": "1.224",
  "marketapp_price": "1.324",
  "commission_percent": "1",
  "price": "1.33724",
  "price_units": 1337240000
}
ПолеЗначит
rent_priceСама аренда: дни × цена за день минус скидка
marketapp_priceСколько берёт marketapp.org: аренда + 0.1 TON сетевой комиссии
priceИтог к списанию с баланса — marketapp_price плюс комиссия сервиса
POST

/rent/{gift,username,number}

Арендовать лот. Поля те же, что у quote, плюс необязательный max_price — потолок в TON: если цена выше, вернётся 409 со свежей котировкой и ничего не спишется.

пример
curl -X POST https://api.fragmentationx.net/v1/rent/gift \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nft_address":"EQA3U6j6Qacjd_2mePipwCSNSzXsUtWdw9zL5KBcsr9X-nae","days":4,"price_per_day":"0.002999","max_price":"0.2"}'

{
  "id": 2045,
  "kind": "rent_gift",
  "status": "queued",
  "currency": "TON",
  "amount": "0.11311596",
  "item": { "item_title": "Victory Medal #34285", "nft_address": "EQA3U6j6...", "days": 4 }
}

# через ~30 с GET /v1/orders/2045:
# "status": "done", "item": {..., "rent_until": "2026-10-31T18:41:04+00:00"}
ОтветПочему
422«Лот изменился или уже арендован» — цена, срок или адрес не совпадают с витриной (или лот уже кто-то взял). Обновите витрину и повторите
422«Этот лот сдаётся на срок от N до M дн.» — days вне диапазона лота
422«Изменился флаг sale_during_rent» — передайте значение из витрины
402Не хватает средств на балансе

Статусы те же, что у покупок. review у аренды значит: оплата ушла, но marketapp.org за 5 минут не показал аренду — заказ проверяется вручную. Так бывает, например, если лот кто-то успел арендовать раньше: после проверки деньги возвращаются на баланс.

POST

/rent/attach

Показать арендованный подарок или username в профиле Telegram. Работает для заказов rent_gift и rent_username в статусе done, пока не кончился срок аренды. Запускается в фоне — ответ 202 с id привязки и ссылкой login_url для владельца аккаунта.

ПолеОбязательноЗначит
order_idдаНомер заказа аренды
assign_toнетНазвание своего канала, если показать нужно в нём, а не в личном профиле
пример
curl -X POST https://api.fragmentationx.net/v1/rent/attach \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"order_id":2046}'

{
  "id": "EjNSh-GQsNN_QkES_3eaSA",
  "order_id": 2046,
  "status": "starting",
  "message": "Готовим вход на fragment.com.",
  "login_url": "https://api.fragmentationx.net/v1/rent/attach/EjNSh-GQsNN_QkES_3eaSA/open",
  "assigned_to": null
}

Что происходит дальше:

ШагЧто происходит
1Владелец аккаунта открывает login_url в Telegram (на телефоне или в Telegram Desktop; можно просто прислать ему ссылку сообщением или кнопкой бота). Откроется окно «Войти на fragment.com» — он нажимает «Log In». На это есть 5 минут; ссылку можно открывать сколько угодно раз, каждый раз она свежая. NFT привяжется к тому аккаунту, который нажал «Log In»
2После подтверждения сервис подключает контракт аренды к этой сессии Fragment как кошелёк
3NFT ставится в профиль (или в канал из assign_to) — как кнопка «Display on Telegram» на Fragment
4Только для username: Telegram добавляет его к аккаунту выключенным. Владелец включает его сам: Настройки → Имя пользователя → переключатель у арендованного username. Подарок показывается в профиле сразу
Один подарок Fragment разрешает привязывать к аккаунту не больше 3 раз в сутки — после этого придёт ошибка Fragment, повторите на следующий день. Анонимные номера так не привязываются (номером входят в Telegram, а не показывают его в профиле) — для rent_number вернётся 422.
GET

/rent/attach/{id}

Статус привязки. Опрашивайте раз в 2–3 секунды, пока не станет done или failed. В message всегда текст, который можно показать пользователю как есть.

starting waiting_confirmation connecting assigning done
СтатусЗначит
waiting_confirmationЖдём, пока владелец аккаунта откроет login_url и нажмёт «Log In». Через 5 минут без подтверждения — failed
connectingВход подтверждён, подключаем арендованный NFT к Fragment
assigningСтавим в профиль
doneГотово, в assigned_to — куда привязано. В GET /orders/{id} появляется attached_to. Для username в message — напоминание включить его в настройках Telegram
failedНе получилось, причина в message. Деньги здесь не списываются — можно просто запустить POST /rent/attach ещё раз
пример
GET /v1/rent/attach/EjNSh-GQsNN_QkES_3eaSA

{
  "id": "EjNSh-GQsNN_QkES_3eaSA",
  "order_id": 2046,
  "status": "done",
  "message": "@acwob добавлен к аккаунту, но Telegram добавляет его выключенным: включите его в Telegram — Настройки → Имя пользователя → @acwob.",
  "login_url": null,
  "assigned_to": "Etherlyt"
}

login_url открывается без токена — ключом служит сам длинный id, поэтому отдавайте ссылку только владельцу аккаунта: кто нажмёт «Log In», к тому NFT и привяжется. После завершения ссылка отвечает 410. Привязка живёт в памяти сервиса около часа; после перезапуска сервиса старый id вернёт 404 — результат при этом сохраняется в заказе (attached_to).

Найти подарок по названию коллекции

Вы знаете только человеческое название — «Plush Pepe», «plush pepe», «PLUSHPEPE» — а /gifts принимает именно slug. Три шага от названия до покупки:

1. найти slug коллекции
curl -H "Authorization: Bearer $TOKEN" https://api.fragmentationx.net/v1/gifts/collections

# ищите совпадение без учёта регистра и пробелов — название на Fragment
# не всегда совпадает со slug дословно ("Plush Pepes" -> "plushpepe"):
# "plush pepe".replace(" ","").lower() ~= "plushpepe"
# -> нашли {"name": "Plush Pepes", "slug": "plushpepe"}
2. посмотреть, что продаётся в этой коллекции
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.fragmentationx.net/v1/gifts?collection=plushpepe&sort=price_asc"

# [{"slug": "plushpepe-1", "num": "#1", "price": "5", ...}, ...]
# берём самый дешёвый: slug="plushpepe-1", price="5"
3. купить найденный экземпляр
curl -X POST https://api.fragmentationx.net/v1/gift \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"slug":"plushpepe-1","price":"5","username":"durov"}'
Отправить в collection само название («Plush Pepe», «plush pepe») нельзя — параметр ждёт ровно slug, а на что-то другое молча отвечает нефильтрованным списком всех коллекций, без ошибки. Всегда резолвьте название через /gifts/collections сначала.

Доставка подарков и username

В POST /gift и POST /username нужно указать получателя ровно одним из двух способов:

username

Стандартная передача Fragment «Transfer to Telegram» — предмет уходит на Telegram-аккаунт получателя внутри Fragment.

{"slug":"plushpepe-1","price":"5","username":"durov"}

to_address

Прямой ончейн-перевод TEP-62 на TON-кошелёк в обход Fragment — как только предмет куплен, он уходит сразу на указанный адрес.

{"slug":"plushpepe-1","price":"5","to_address":"UQ..."}

Оба способа стоят одинаково — комиссия за доставку заложена в цену вне зависимости от способа. Адрес в to_address принимается в любом формате (EQ…/UQ…, bounceable или нет) и не может совпадать с адресом сервиса. Заказ проходит через статусы queued → processing (покупка на Fragment, затем доставка) → done.

POST /number сюда не входит — у анонимных номеров есть только to_address, см. /number.