Обзор#

API Catapult обслуживает платформу деривативов на синтетические токены — торговлю и данные о токенах — через единую точку GraphQL для операций запрос/ответ и точку WebSocket для подписок в реальном времени.

Базовые эндпоинты#

Все HTTP-запросы выполняются методом POST с JSON-телом вида { "query": "...", "variables": { ... } }.

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

Аутентифицированные операции используют JWT-токен (bearer), передаваемый в заголовке Authorization:

Authorization: Bearer <your-jwt-token>

Токен — это JSON Web Token (JWT), по умолчанию действительный 730 дней (≈2 года) с момента выпуска — обновляйте его до истечения срока. Публичен только ping; все остальные операции требуют bearer-токен, а для чтения, например tokens и turboToken, дополнительно нужно разрешение tokens.read.

Создание API-ключа#

Сгенерируйте токен в панели управления аккаунтом на catapult.trade/settings/api-key (Настройки → API Key). Управлять аккаунтом можно на catapult.trade.

Соглашения#

• Идентификаторы — непрозрачные строки; не разбирайте их.
• Денежные значения — строково-кодированные целые числа типа String! (например, balanceUsdtDrops) — разбирайте их как BigInt, а не как float. Единственный пользовательский скаляр — DateTime.
• Метки времени используют скаляр DateTime (ISO-8601, UTC).
• Списочные запросы пагинируются по курсору через input.pagination: limit (по умолчанию 10) и afterCursor / beforeCursor.

Быстрый пример#

query Tokens {
  # полный PublicTokenListInput и поля токена см. на вкладке Reference
  tokens(input: { pagination: { limit: 5 } }) {
    items { id }
  }
}

OAuth для API-ключа#

Эта ссылка позволяет получить API-ключ пользователя для создания различных функций, например копитрейдинга. Пользователь выдаёт разрешения для своего API-ключа, и он передаётся на ваш callback URL из белого списка.

https://catapult.trade/settings/api-key?bot_id=<WHITELISTED_BOT_ID>

Замените <WHITELISTED_BOT_ID> на идентификатор вашего бота из белого списка.

Внесение бота в белый список#

Внесите своего бота в белый список, связавшись с нашей командой разработчиков:

[email protected]

Единицы и соглашения#

Прочитайте это первым — каждое денежное поле API зависит от этих соглашений.

USDT drops (*UsdtDrops)#

Все суммы в USDT — целые числа вида USDT × 1,000,000 (6 знаков после запятой) с суффиксом UsdtDrops. Они передаются как String! (строково-кодированные целые числа) — разбирайте их как BigInt, а не как float.

Преобразование: usdt = drops / 1e6 и drops = round(usdt × 1e6) — вычисляйте в BigInt.

Кредитное плечо (leverageX10)#

Плечо кодируется как плечо × 10. leverageX10: 125 означает 12.5×; 30 означает 3×.

Залог и номинал#

notional = collateral × leverage. Сумма, которую вы вносите, — это залог (collateral); номинальная стоимость позиции в USDT — это номинал (notional).

При открытии позиции сумма — это залог до вычета комиссии. tradeOpen принимает ровно одно из usdtDrops (в USDT) или amountWei (в токенах) — движок выводит номинал из неё и плеча. Это не номинал.

Балансы#

userBalance { balanceUsdtDrops, inPositionsBalanceUsdtDrops }:

Медиа токена (fileId)#

Изображение токена прикрепляется передачей fileId в tokenCreate. Получить его можно двумя способами:

1. Рандомайзер — tokenRandomizedPreset возвращает готовый fileId (а также имя, символ, режим и т. д.), который можно сразу передать в tokenCreate.
2. Своя загрузка — трёхшаговый процесс S3 presigned-POST:
   • fileUpload(input) → возвращает URL S3 presigned-POST и поля формы, которые клиент должен включить в multipart-POST.
   • Клиент отправляет (POST) изображение на этот URL S3 с этими полями формы.
   • fileFinalize(id) → отмечает загрузку завершённой после успешного S3 POST и возвращает публичный URL файла; используйте полученный файл как изображение токена.

Ограничения загрузки: только JPEG или PNG, максимум 5 МБ, минимум 314×314 px. Presigned POST должен завершиться в течение 15 секунд после вызова fileUpload, а загрузки ограничены 200 в час на IP.

Скоростные режимы токенов#

Каждый токен работает в одном из пяти скоростных режимов. Поле при создании/рандомизации — turboTokenMode; записи токенов содержат speedMode. SLOW и NORMAL — один и тот же режим под двумя именами.

Значения максимального плеча и времени жизни ниже — текущая конфигурация, которая может меняться на стороне сервера: считайте их актуальными значениями и сверяйтесь с живым запросом leverage-config.

Максимальное плечо — фиксированный лимит движка#

Максимальное плечо каждого режима — жёсткий лимит, применяемый движком; используйте значение из таблицы напрямую. Движок отклоняет любой ордер выше него.

Комиссии и размер позиции#

Комиссия за открытие (~1%)#

При открытии позиции взимается комиссия за открытие ~1% (0.01), вычитаемая из отправляемого вами залога:

collateral_post_fee = collateral_sent × (1 − fee)

Чтобы заблокированный залог точно составил notional / leverage, отправьте:

collateral_sent = (notional / leverage) / (1 − fee)

Лимит номинала на позицию#

На стороне сервера действует лимит номинала на позицию — сейчас 20,000 USDT на (токен, плечо, сторону). Превышение возвращает Maximum notional limit … exceeded. Сверяйте точное значение с живой конфигурацией; оно может зависеть от режима или плеча.

Максимально доступная позиция (номинал)#

Пусть fee = 0.01, free = balanceUsdtDrops / 1e6, inPos = inPositionsBalanceUsdtDrops / 1e6, capTotal — ваш необязательный общий лимит залога, capPos — лимит номинала на позицию (~20,000), L — плечо:

maxCollateralFromBalance = free × (1 − fee)
remainingTotalBudget     = capTotal − inPos          # если используете общий лимит
maxNewCollateral         = min(maxCollateralFromBalance, remainingTotalBudget)
maxNotionalAchievable    = maxNewCollateral × L
maxPositionNotional      = min(maxNotionalAchievable, capPos)

Залог к отправке = (maxPositionNotional / L) / (1 − fee).

Подводный камень округления. После деления на (1 − fee) наивное round(collateral × 1e6) превышает лимит на несколько drops, и открытие отклоняется. Округляйте вниз залог в drops (BigInt) до небольшого шага (например, 10 drops = 0.00001 USDT) перед отправкой. Вы теряете ничтожную долю цента и остаётесь в пределах лимита при любом плече.

Разобранный пример#

FLASH, 3×, комиссия 1%, лимит 20,000 номинала:

collateral_post_fee target = 20,000 / 3        = 6,666.67
collateral_sent            = 6,666.67 / 0.99 ≈ 6,734.01   (округлено вниз в drops)
→ заблокировано после комиссии ≈ 6,666.67, номинал ≈ 20,000

Коды состояния#

Ответы GraphQL возвращают HTTP 200 даже при сбое операции — анализируйте массив errors[] и поле extensions.code каждой ошибки. Проблемы транспортного уровня используют стандартные коды HTTP.

Коды состояния HTTP#

Сервис GraphQL возвращает ошибки аутентификации, прав доступа и лимитов внутри ответа как 200 (см. коды ошибок GraphQL). Транспортные 401 / 403 / 429 возникают только если вышестоящий шлюз/CDN отклоняет запрос до того, как он достигнет API.

Коды ошибок GraphQL#

Коды чувствительны к регистру; сопоставляйте точную строку. Доменные коды — в PascalCase (например, RateLimited); некоторые системные коды — в верхнем регистре через подчёркивание (например, UNAUTHENTICATED).

Структура ошибки#

{
  "errors": [
    { "message": "Token not found", "extensions": { "code": "NotFound" } }
  ],
  "data": null
}

Ограничения запросов#

Операции GraphQL используют единый лимит-бакет, привязанный к API-токену (jti) и IP: 600 запросов/мин и 60 мутаций/мин. При превышении лимита возвращается ответ HTTP 200, в errors[] которого содержится единственная ошибка с extensions.code = RateLimited. API не возвращает статус 429 и заголовок Retry-After; подсказки по времени повторной попытки передаются в extensions ошибки.

Лимиты HTTP (GraphQL)#

Лимиты WebSocket#

Лимиты WebSocket настраиваются на сервере, поэтому в проде они могут отличаться от этих значений по умолчанию. Лимиты применяются на соединение, а не на IP.

Заголовки ответа#

API не отправляет заголовки лимитов (X-RateLimit-*, Retry-After). Их может добавить вышестоящий шлюз; не полагайтесь на них.

Подводные камни и идемпотентность#

Чек-лист того, в чём интеграторы чаще всего ошибаются.

Деньги и размер#

• Drops — целые числа — BigInt от начала до конца; никогда не разбирайте *UsdtDrops как float.
• Отправляемая сумма открытия (usdtDrops или amountWei) — это залог до вычета комиссии, а не номинал.
• Лимит номинала применяется в drops; округляйте вниз залог, чтобы избежать превышения на несколько drops (см. «Комиссии и размер позиции»).
• Максимальное плечо — фиксированный лимит движка для каждого режима (см. «Скоростные режимы токенов») — используйте его напрямую.

Токены#

• Рандомайзер возвращает случайный rank (Competition | Private | Public). Принудительно ставьте Public, если токен должен быть в листинге / доступен для копи-трейдинга.
• tokenCreate всегда использует оплату с баланса — тип оплаты переопределить нельзя.
• На стороне сервера нет флага «активно» у tokens — фильтруйте на клиенте по endDate.

Открытие и закрытие#

• tradeOpen требует ровно одно из usdtDrops (в USDT) или amountWei (в токенах) — не оба и не ни одного.
• tradeClose закрывает открытую позицию через USER_SELL.

Тейк-профит / стоп-лосс (tradeLimit*)#

• tradeLimitCreate требует хотя бы один триггер (SL или TP).
• При обновлении явный null для стороны очищает её; опущенное поле сохраняется.
• tradeLimitUpdate отклоняет полностью пустой ввод (Validation failed: input=MissingValue) — используйте tradeLimitDelete для очистки.
• Удаления по одной стороне нет; tradeLimitDelete удаляет обе — TP и SL.

Подписки (WebSocket)#

• Аутентифицируйтесь в connection_init с payload: { Authorization: "Bearer <apiKey>" }.
• Подписка positions транслирует объединение PublicPositionEvent — PublicPositionOpenedEvent | PublicPositionClosedEvent | PublicPositionUpdatedEvent. Сопоставляйте по полю type, прежде чем читать поля конкретного события.
• PublicPositionClosedEvent содержит positionId, tokenId, type, closeType, closedAt, closePriceUsdtDrops, receivedAmountUsdtDrops, pnlUsdtDrops. Поля buyPriceUsdtDrops, collateralUsdtDrops, notionalUsdtDrops, leverageX10 принадлежат PublicPositionOpenedEvent, а не событию закрытия.
• События закрытия доставляются как минимум один раз и не воспроизводятся повторно. Закрытие, отправленное во время переподключения, пропускается новой подпиской — опрашивайте каждую открытую позицию при (пере)подписке, чтобы отловить пропущенные закрытия, и устраняйте дубликаты по positionId.

WebSocket API#

Данные в реальном времени передаются по WebSocket-соединению по протоколу GraphQL over WebSocket (graphql-transport-ws). Используйте его для операций subscription, например для обновлений цен в реальном времени.

Соединение#

Откройте WebSocket по адресу:

wss://public-api.catapult.trade/graphql

Согласуйте подпротокол graphql-transport-ws. После открытия сокета отправьте сообщение connection_init; сервер ответит connection_ack.

Жизненный цикл#

1. Клиент открывает сокет с подпротоколом graphql-transport-ws.
2. Клиент → {"type":"connection_init"}.
3. Сервер → {"type":"connection_ack"}.
4. Клиент → subscribe с уникальным id и документом GraphQL.
5. Сервер → одно или несколько сообщений next, затем complete.

Подписка#

{
  "id": "1",
  "type": "subscribe",
  "payload": {
    "query": "subscription($t: ID!) { priceTicks(tokenId: $t) { tokenId price } }",
    "variables": { "t": "<tokenId>" }
  }
}

Сообщение с данными#

{
  "id": "1",
  "type": "next",
  "payload": { "data": { "priceTicks": { "tokenId": "tok_123", "price": "0.0123" } } }
}

Отписка#

Отправьте сообщение complete, чтобы остановить одну подписку; закройте сокет, чтобы остановить все.

{ "id": "1", "type": "complete" }

Ошибки#

Ошибки уровня операции приходят как сообщение error для соответствующего id:

{ "id": "1", "type": "error", "payload": [{ "message": "Token not found" }] }

Соединения, не отправившие connection_init в течение 10 секунд, закрываются с кодом 4408 (тайм-аут инициализации соединения).