MemGift Mint API

Base URL:
https://api-memgift.bincore.site

Авторизация:
Во всех приватных запросах передавайте токен:
Authorization: Bearer <API_ACCESS_TOKEN>

API можно вызывать с других сайтов и хостов. CORS включён.

Endpoints:

GET /health
Проверка, что API работает. Токен не нужен.

GET /docs
Эта документация. Токен не нужен.

POST /v1/mint
Создать NFT в GetGems коллекции.
API не проверяет наличие подарка на MemGift аккаунте и создаёт NFT по данным из запроса.

GET /v1/mint/{request_id}
Проверить статус создания NFT.

Инструкция: как заминтить NFT-подарок

1. Подготовьте данные подарка:
- owner_address: TON-кошелёк получателя NFT.
- gift_key: технический ключ подарка, например Serphira, PepCream, Gargonna.
- gift_title: отображаемое имя подарка.
- number: номер подарка.
- model: имя модели и ссылка на модель.
- background: имя фона, цвета фона и при необходимости ссылка на фон.
- symbol: имя символа и ссылка на символ.

2. Если хотите, чтобы API сам собрал итоговую PNG-картинку NFT, передайте:
- render_image: true

В этом случае API возьмёт model + background + symbol, соберёт превью и сам подставит image в запрос к GetGems.

3. Если у подарка анимированная модель, дополнительно передайте:
- lottie или lottie_url или animation_url

Для Gargonna, WhorGirl и TonWheel можно передавать ссылку на Lottie JSON. Если render_image=true, статичная PNG всё равно будет собрана отдельно для image, а анимация уйдёт в lottie.

4. Отправьте POST /v1/mint.

Если нужно только проверить тело запроса без реального минта, передайте dry_run=true.

5. После ответа:
- status=validated - запрос валиден, но реальный mint не запускался, потому что dry_run=true.
- status=processing - NFT уже создаётся.
- status=success - NFT готов, в ответе будут address и url.
- status=failed - произошла ошибка.

6. Если не хотите отдельно опрашивать статус, передайте:
- wait_ready: true
- wait_timeout: количество секунд ожидания, максимум 120

Тогда API сам подождёт готовность NFT в рамках POST-запроса.

Быстрый сценарий минта обычного NFT-подарка:
1. Соберите request_id, который ещё не использовался.
2. Передайте owner_address, gift_key, gift_title, number.
3. Передайте model/background/symbol.
4. Передайте render_image=true, если хотите, чтобы API сам собрал итоговое изображение.
5. Получите request_id и дождитесь status=success.

Быстрый сценарий минта анимированного NFT-подарка:
1. Передайте те же поля, что и для обычного подарка.
2. Добавьте lottie_url с ссылкой на JSON-анимацию модели.
3. При необходимости оставьте render_image=true, чтобы API отдельно собрал статичную preview-картинку для GetGems.
4. Дождитесь status=success и заберите url готового NFT.

Статусы:
validated - запрос проверен, но реальный mint не запускался, если dry_run=true.
processing - запрос принят, NFT создаётся.
success - NFT создан.
failed - создание не удалось.

Минимальный POST /v1/mint:
{
  "request_id": "serphira-530-001",
  "owner_address": "UQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "gift_key": "Serphira",
  "gift_title": "Serphira",
  "number": 530,
  "render_image": true,
  "model": {
    "name": "Default",
    "image": "https://example.com/model.svg",
    "drop_rate": "10%"
  },
  "background": {
    "name": "Red",
    "image": "https://example.com/background.png",
    "center": "#875353",
    "around": "#734040",
    "drop_rate": "5%"
  },
  "symbol": {
    "name": "Star",
    "image": "https://example.com/symbol.svg",
    "drop_rate": "3%"
  }
}

Пример ответа:
{
  "ok": true,
  "request_id": "serphira-530-001",
  "status": "processing",
  "getgems_status": "pending",
  "name": "Serphira #530",
  "address": null,
  "url": null,
  "error": null
}

Пример успешного ответа:
{
  "ok": true,
  "request_id": "serphira-530-001",
  "status": "success",
  "getgems_status": "ready",
  "name": "Serphira #530",
  "address": "EQ...",
  "url": "https://getgems.io/...",
  "error": null
}

Поля запроса:
request_id: уникальный id запроса, 6-120 символов. Лучше всегда передавать свой.
owner_address или wallet_address: TON/GRAM адрес получателя, начинается с UQ или EQ.
gift_key: технический ключ подарка.
gift_title или gift_name: название подарка.
number, seq или gift_number: номер подарка.
image или image_url: статичная PNG/JPG картинка NFT для GetGems. Не передавайте GIF в image.
lottie, lottie_url или animation_url: ссылка на Lottie JSON для анимированной модели, если нужно.
render_image: true, чтобы API сам собрал статичную PNG картинку из model + background + symbol и заменил image.
Для Gargonna, WhorGirl и TonWheel API ищет Lottie JSON рядом с model.image: .svg меняется на .json. Можно сразу передать model.image с .json.
model.name: название модели.
model.image: ссылка на модель.
model.drop_rate: редкость модели.
background.name: название фона.
background.image: ссылка на фон, если есть.
background.center: основной цвет фона в формате #875353.
background.around: внешний цвет фона в формате #734040.
background.drop_rate: редкость фона.
symbol.name: название символа.
symbol.image: ссылка на символ.
symbol.drop_rate: редкость символа.
description: описание NFT, необязательно.
name: полное имя NFT, необязательно. По умолчанию gift_title + номер.
attributes: дополнительные атрибуты массивом [{"trait_type":"...", "value":"..."}].
wait_ready: true, если нужно подождать готовность прямо в POST-запросе.
wait_timeout: сколько секунд ждать, максимум 120.
dry_run: true, чтобы проверить запрос без реального минта.

Пример curl:
curl -X POST "https://api-memgift.bincore.site/v1/mint" \
  -H "Authorization: Bearer <API_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "pepcream-777-001",
    "owner_address": "UQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "gift_key": "PepCream",
    "gift_title": "Pep Cream",
    "number": 777,
    "render_image": true,
    "model": {"name": "Vanilla", "image": "https://example.com/model.svg", "drop_rate": "12%"},
    "background": {"name": "Green", "center": "#7DCB8A", "around": "#315C3A", "drop_rate": "6%"},
    "symbol": {"name": "Clover", "image": "https://example.com/symbol.svg", "drop_rate": "2%"}
  }'

Пример browser fetch:
fetch("https://api-memgift.bincore.site/v1/mint", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_ACCESS_TOKEN>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    request_id: "test-001",
    owner_address: "UQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    gift_key: "Serphira",
    gift_title: "Serphira",
    number: 530,
    image: "https://example.com/final.png",
    model: {"name": "Default", "image": "https://example.com/model.svg"},
    background: {"name": "Red", "center": "#875353", "around": "#734040"},
    symbol: {"name": "Star", "image": "https://example.com/symbol.svg"}
  })
})

Важно:
Не используйте один request_id для разных NFT.
Повторный запрос с тем же request_id и тем же телом вернёт текущий статус.
Повторный запрос с тем же request_id, но другим телом вернёт ошибку conflict.