Skip to content

lukinism/iris-api-spec

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

21 Commits
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
spec.json
spec.json
 
 
spec.yaml
spec.yaml
 
 

Repository files navigation

📘 API Документация Iris. Актуальная версия: 0.5.

📑 Оглавление

📦 Методы Pocket

pocket/balance

💬 Ответ:

{
  "result": {
    "gold": integer,
    "sweets": float,
    "donate_score": integer,
    "tgstars": integer
  }
}

pocket/sweets/give

📤 Структура запроса:

Параметр Тип Описание
user_id integer ✅ ID пользователя, которому отправляются ириски
amount float ✅ Количество ирисок для отправки
comment string 💬 Комментарий к переводу
without_donate_score boolean ✅ Использовать донат очки к переводу
donate_score int ✅ Максимальное количество очков доната, которые будут использоваться в передаче ирисок

💬 Ответ:

{ "result": integer }

pocket/gold/give

📤 Структура запроса:

Параметр Тип Описание
user_id integer ✅ ID пользователя, которому отправляется голда
amount integer ✅ Количество голды для отправки
comment string 💬 Комментарий к переводу
without_donate_score boolean ✅ Использовать донат очки к переводу
donate_score int ✅ Максимальное количество очков доната, которые будут использоваться в передаче голды

💬 Ответ:

{ "result": integer }

pocket/donate_score/give

📤 Структура запроса:

Параметр Тип Описание
user_id integer ✅ ID пользователя, которому отправляются донат-очки
amount integer ✅ Количество очков для отправки
comment string 💬 Комментарий к переводу

💬 Ответ:

{ "result": integer }

pocket/sweets/history

📤 Структура запроса:

Параметр Тип Описание
offset integer 💬 Вернуть записи, где id ≥ offset
limit integer 💬 Количество записей в ответе

💬 Ответ:

{
  "result": [
    {
      "date": integer,
      "amount": float,
      "balance": float,
      "to_user_id": integer,
      "details": {
        "total": float,
        "amount": float,
        "fee": float,
        "donate_score": integer
      },
      "comment": string,
      "id": integer,
      "type": string,
      "peer_id": integer
    }
  ]
}

type может быть send, receive, trade, dividends, trade_sale_order, send_with, purchase_tgstars (ириски потрачены на конвертацию в тг-звёзды).

pocket/tgstars/give

📤 Структура запроса:

Параметр Тип Описание
amount integer ✅ Количество тг-звёзд для отправки
user_id integer ✅ ID получателя
comment string 💬 Комментарий к переводу

💬 Ответ:

{ "result": integer }

pocket/tgstars/history

📤 Структура запроса:

Параметр Тип Описание
offset integer 💬 Вернуть записи, где id ≥ offset
limit integer 💬 Количество записей (по умолчанию 200)

💬 Ответ (список записей):

{
  "result": [
    {
      "id": integer,
      "type": "send | receive | purchase",
      "date": integer,
      "amount": integer,
      "balance": integer,
      "peer_id": integer,
      "comment": string
    }
  ]
}

pocket/tgstars/buy

📤 Структура запроса:

Параметр Тип Описание
amount integer ✅ Количество тг-звёзд для покупки

💬 Ответ:

{ "result": integer }

pocket/tgstars/price

📤 Структура запроса:

Параметр Тип Описание
amount integer ✅ Количество тг-звёзд для оценки стоимости

💬 Ответ:

{
  "result": {
    "tgstars": integer,
    "sweets": integer
  }
}

pocket/gold/history

📤 Структура запроса:

Параметр Тип Описание
offset integer 💬 Минимальный ID записи
limit integer 💬 Количество записей

💬 Ответ:

{
  "result": [
    {
      "date": integer,
      "amount": integer,
      "balance": integer,
      "to_user_id": integer,
      "details": {
        "total": integer,
        "amount": integer,
        "fee": integer,
        "donate_score": integer
      },
      "comment": string,
      "id": integer,
      "type": string,
      "peer_id": integer
    }
  ]
}

pocket/donate_score/history

📤 Структура запроса:

Параметр Тип Описание
offset integer 💬 Минимальный ID записи
limit integer 💬 Количество записей

💬 Ответ:

{
  "result": [
    {
      "date": integer,
      "amount": integer,
      "balance": integer,
      "id": integer,
      "type": string,
      "peer_id": integer,
      "comment": string
    }
  ]
}

pocket/enable / pocket/disable / pocket/allow_all / pocket/deny_all

📤 Структура запроса:

(Параметры отсутствуют)

💬 Ответ:

{ "result": boolean }

pocket/allow_user

📤 Структура запроса:

Параметр Тип Описание
user_id integer ✅ ID пользователя, которому разрешено отправлять валюту

pocket/deny_user

📤 Структура запроса:

Параметр Тип Описание
user_id integer ✅ ID пользователя, которому запрещено отправлять валюту

👤 Методы User Info

user_info/reg

📤 Структура запроса:

Параметр Тип Описание
user_id integer ✅ ID пользователя, для получения даты регистрации

💬 Ответ:

{ "result": integer }

user_info/activity

📤 Структура запроса:

Параметр Тип Описание
user_id integer ✅ ID пользователя, для получения статистики активности

💬 Ответ:

{
  "result": {
    "total": integer,
    "week": integer,
    "month": integer,
    "day": integer
  }
}

user_info/spam

📤 Структура запроса:

Параметр Тип Описание
user_id integer ✅ ID пользователя, для проверки в базах спама/скама/игнора

💬 Ответ:

{
  "result": {
    "is_spam": boolean,
    "is_ignore": boolean,
    "is_scam": boolean
  }
}

user_info/stars

📤 Структура запроса:

Параметр Тип Описание
user_id integer ✅ ID пользователя, звёздность которого требуется получить

💬 Ответ:

{ "result": integer }

user_info/pocket

📤 Структура запроса:

Параметр Тип Описание
user_id integer ✅ ID пользователя, чей мешок требуется получить

💬 Ответ:

{
  "result": {
    "gold": integer,
    "coins": integer,
    "sweets": float,
    "stars": integer,
    "tgstars": integer
  }
}

🔄 Методы Updates

updates/getUpdates

📤 Структура запроса:

Параметр Тип Описание
offset integer ID последнего полученного события. Следующие события будут возвращены с id > offset.
limit integer Количество записей в ответе

💬 Ответ:

{
  "result": [
    {
      "id": 11,
      "type": "donate_score_log",
      "date": 1756286741,
      "object": { ... }
    }
  ]
}

📘 Описание полей:

Поле Тип Описание
id integer Уникальный идентификатор события
type string Тип события: sweets_log, gold_log, donate_score_log, tgstars_log
date integer Время события в формате UNIX (секунды)
object object Объект события. Совпадает по структуре с методами pocket/sweets/history, pocket/gold/history, pocket/donate_score/history, pocket/tgstars/history

💰 Методы Trade

trade/buy

📤 Структура запроса:

Параметр Тип Описание
price float ✅ Цена, которую вы готовы заплатить за 1 ед. голды
volume integer ✅ Количество голды для покупки

💬 Ответ (если сделка совершена):

{
  "result": {
    "done_volume": integer,
    "sweets_spent": float
  }
}

💬 Ответ (если нет предложений — создаётся заявка):

{
  "result": {
    "done_volume": integer,
    "sweets_spent": float,
    "new_order": {
      "volume": integer,
      "price": float,
      "id": integer
    }
  }
}

trade/sell

📤 Структура запроса:

Параметр Тип Описание
price float ✅ Цена, по которой вы хотите продать 1 ед. голды
volume integer ✅ Количество голды для продажи

💬 Ответ (моментальная продажа):

{
  "result": {
    "done_volume": integer,
    "sweets_received": float
  }
}

💬 Ответ (если нет покупателей — создаётся заявка):

{
  "result": {
    "done_volume": integer,
    "sweets_received": float,
    "new_order": {
      "volume": integer,
      "price": float,
      "id": integer
    }
  }
}

trade/cancel_price

📤 Структура запроса:

Параметр Тип Описание
price float ✅ Цена покупки (от 0.01 до 1_000_000)

💬 Ответ:

{
  "result": {
    "gold": integer,
    "sweets": float
  }
}

📘 Описание:

  • gold — количество возвращённых в мешок золотых ирисок.
  • sweets — количество возвращённых в мешок ирисок.

trade/cancel_all

📤 Структура запроса:

(Параметров нет)

💬 Ответ:

{
  "result": {
    "gold": integer,
    "sweets": float
  }
}

📘 Описание:

  • gold — количество возвращённых в мешок золотых ирисок.
  • sweets — количество возвращённых в мешок ирисок.

trade/cancel_part

📤 Структура запроса:

Параметр Тип Описание
id integer ID заявки на Ирис-бирже.
volume float Объём золотых ирисок для отмены. Если указанный объём равен или превышает объём выбранной заявки, то заявка полностью снимается.

💬 Ответ:

{
  "result": {
    "gold": integer,
    "sweets": float
  }
}

📘 Описание:

  • gold — количество возвращённых в мешок золотых ирисок.
  • sweets — количество возвращённых в мешок ирисок.

trade/deals

📤 Структура запроса:

Параметр Тип Описание
id integer ID сделки, начиная с которой нужно вернуть данные (по умолчанию 0 — последние сделки)
limit integer Максимум записей (0–200, по умолчанию 200)

💬 Ответ:

{
  "result": [
    {
      "id": integer,
      "group_id": integer,
      "date": integer,
      "price": float,
      "volume": integer,
      "type": string
    }
  ]
}

📘 Описание полей:

Поле Тип Описание
id integer Уникальный идентификатор сделки
group_id integer Идентификатор группы связанных сделок (0, если сделка одиночная)
date integer Время сделки в формате UNIX (секунды)
price float Цена, по которой была совершена сделка
volume integer Объём сделки
type string Тип сделки: buy — покупка, sell — продажа

trade/orderbook

📤 Структура запроса:
(Параметров нет)

💬 Ответ:

{
  "result": {
    "buy": [
      { "volume": integer, "price": float }
    ],
    "sell": [
      { "volume": integer, "price": float }
    ]
  }
}

🖼️ Методы NFT

nft/give

📤 Структура запроса:

Параметр Тип Описание
id integer ✅ ID нфт в системе Ириса
name string ✅ Название гифта из адреса t.me/nft/*. Например, PlusPepe-1
user_id integer ✅ Ид юзера, которому передаётся NFT
comment string 💬 Необязательный комментарий

💬 Ответ:

{
  "result": integer
}

nft/info

📤 Структура запроса:

Параметр Тип Описание
id integer ✅ ID нфт в системе Ириса
name string ✅ Название гифта из адреса t.me/nft/*. Например, PlusPepe-1

💬 Ответ:

{
  "result": {
    "number": integer,
    "symbol": {
      "emoji": string,
      "custom_emoji_id": string,
      "name": string,
      "id": integer,
      "rarity_per_mile": integer
    },
    "url_name": string,
    "background": {
      "name": string,
      "id": integer,
      "rarity_per_mile": integer
    },
    "owner_id": integer,
    "name": string,
    "model": {
      "emoji": string,
      "custom_emoji_id": integer,
      "name": string,
      "id": integer,
      "rarity_per_mile": integer
    },
    "id": integer
  }
}

nft/list

📤 Структура запроса:

Параметр Тип Описание
limit integer 💬 Количество записей в ответе
offset integer 💬 Вернуть записи, где id ≥ offset

💬 Ответ:

{
  "result": [
    {
      "date_add": integer,
      "number": integer,
      "symbol": {
        "emoji": string,
        "custom_emoji_id": string,
        "name": string,
        "id": integer,
        "rarity_per_mile": integer
      },
      "url_name": string,
      "background": {
        "name": string,
        "id": integer,
        "rarity_per_mile": integer
      },
      "name": string,
      "model": {
        "emoji": string,
        "custom_emoji_id": string,
        "name": string,
        "id": integer,
        "rarity_per_mile": integer
      },
      "id": integer
    }
  ]
}

nft/history

📤 Структура запроса:

Параметр Тип Описание
limit integer 💬 Количество записей в ответе
offset integer 💬 Вернуть записи, где id ≥ offset

💬 Ответ:

{
    "result": [
        {
            "date": integer,
            "nft_id": integer,
            "id": integer,
            "type": string,
            "peer_id": integer
        }
    ]
}

⚙️ Остальные методы

/iris_agents

📤 Структура запроса:

Параметр Тип Описание
token string Конкатенация {bot_id}_{iris_token}. Пример: 5293075118_SEibvWeRC19iRDk6SAwvu7TfzyOe4m6o

💬 Ответ:

{
  "result": [ integer, integer, ... ]
}

📘 Описание:

Возвращает массив int64 — идентификаторов Telegram-аккаунтов агентов Iris.

Пример:

{
  "result": [571497337, 6826112951, 7057861690, 1072639353, 6530053533, 956560198, 1135399536, 5484288853, 1082239406, 661079614]
}

/last_version

📤 Структура запроса:
(Параметров нет)

💬 Ответ:

{
  "result": "0.5"
}

📘 Описание:

Возвращает строку с текущей актуальной версией API Iris. Используется для проверки обновлений и совместимости клиентов.

🔗Дип - линки

📌 Общая информация о дип-линках

Дип-линки в Ирисе — это специальные Telegram-ссылки, которые позволяют вашему боту инициировать действия через Ирис с обязательным подтверждением со стороны пользователя.

Дип-линки используются для:

  • выставление счёта (ириски, голда, очки-доанат, tg-звёзды);
  • запроса разрешений на доступ к пользовательской информации.

Ссылка формируется вашим ботом и отправляется пользователю.
При переходе по дип-линку пользователь попадает в диалог с Ирисом, где видит описание запрашиваемого действия и должен явно подтвердить его.

🔒 Безопасность

  • Пользователь всегда видит, какое действие выполняется
  • Пользователь сам принимает решение о подтверждении
  • Бот не получает доступ к средствам или данным без согласия пользователя

👤 Типовой сценарий использования

  1. Ваш бот формирует дип-линк с параметрами операции
  2. Бот отправляет ссылку пользователю
  3. Пользователь переходит по ссылке
  4. Ирис показывает описание операции
  5. Пользователь нажимает кнопку «Подтвердить»
  6. Действие выполняется (перевод / выдача прав)

Передача ирисок, голды, очки-доната или тг-звёзд вашему боту

https://t.me/iris_cm_bot?start=give_bot{bot_id}_{amount}{_comment?} - передача ирисок

https://t.me/iris_cm_bot?start=givegold_bot{bot_id}_{amount}{_comment?} - передача голды

https://t.me/iris_cm_bot?start=givedonate_score_bot{bot_id}_{amount}{_comment?} - передача очков доната

https://t.me/iris_cm_bot?start=givetgstars_bot{bot_id}_{amount}{_comment?} - перевод тг-звёзд

📥 Параметры

Параметр Описание
bot_id ✅ ID вашего бота
amount ✅ Количество ирисок, голды, донат-очков или тг-звёзд для перевода
comment 💬 Необязательный комментарий

📝 Комментарий (comment)

  • Параметр является необязательным
  • Допустимые символы: a-zA-Z0-9_

⚠️ Пробелы и специальные символы запрещены

Информация о пользователе

https://t.me/iris_cm_bot?start=request_rights_{bot_id}_{rights} - запросить разрешения

📥 Параметры

Параметр Описание
bot_id ID вашего бота
rights Список запрашиваемых разрешений

📋 Формат параметра rights

Можно запрашивать одно или несколько разрешений одновременно, перечисляя их через символ _.

Пример

reg_spam_activity

🛂 Доступные разрешения

Разрешение Описание
reg Дата регистрации пользователя
spam Проверка на спам / игнор / скам
activity Статистика активности
stars Звёздность пользователя
pocket Содержимое мешка пользователя

⚠️ Ошибки API

Формат ошибки (ApiError):

{
  "error": {
    "code": 401,
    "description": "Invalid token"
  }
}

Пример с кодом 400:

{
  "error": {
    "code": 400,
    "description": "Required parameter \"{parameter}\" is absent"
  }
}

Коды и сообщения:

Код Сообщение Когда возвращается
400 Required parameter "{parameter}" is absent Не указан обязательный параметр
400 User is 0 or not a number Некорректный user_id
400 User denied receiving Переводы указанному пользователю запрещены
400 Длина текста слишком длинная comment > 128 символов
400 Ссылки на сторонние сайты в тексте запрещены В тексте обнаружены внешние ссылки
400 Обращения к пользователям в тексте запрещены Обнаружены обращения к пользователям
400 Слишком много смайлов в тексте >99 эмодзи в тексте
400 Price is 0, negative or not a number Неверно указана цена
400 Volume is 0, negative or not a number Неверно указан объём
400 ID is 0, negative or not a number Неверный id заявки
400 Tg stars is 0 or not a number Неверно указано количество тг-звёзд
400 Version is wrong Неверный номер версии в /v{номер версии}/...
401 Invalid token Токен не принадлежит указанному боту
403 Rights are not given Пользователь не дал разрешение на просмотр
404 Handler Not Found Метод не существует или указан с ошибкой
404 User not found Пользователь не найден
404 Order not found Заявка по id не найдена
404 No such bot ID не принадлежит боту
409 Not enough {currently}. Need {quantity} Недостаточно средств/ресурсов
429 Flood control Более 3 запросов за секунду

❗Объявленные правила и рекомендации по использованию API Ириса

❗ Логирование операций цифровых активов

Важным условием предоставления Iris Connect API является согласие предоставить по запросу администрации Ириса логи переводов активов запрашиваемого пользователя.

🕵️ Это требование связано с расследованием скам-цепочек, в которых мошенники могут использовать вашего бота для отмывания цифровых активов.

Под цифровыми активами понимаются:

  • ириски, вводимые в бота и выводимые из бота;
  • внутренняя валюта вашего бота;
  • предметы, скины, бонусы и другие игровые активы.

Минимальный набор логов:

  1. Кто ввёл ириски в бота, когда и в каком количестве
  2. Кому были переданы активы внутри бота
  3. Кто и когда вывел ириски из бота

❗ Не используйте «бесконечные» версии API

Указание условной «вечной последней версии» (например, /v100) является плохой практикой и может привести к непредсказуемым поломкам при изменениях в API. Использование несуществующих или «будущих» версий приводит к тому, что клиенты API могут внезапно перестать работать в неожиданных местах.

В связи с этим пользователям настоятельно рекомендуется указывать только реально существующие версии API.

При указании несуществующей версии API будет возвращена ошибка.

🔎 Проверка актуальной версии

Для получения текущей актуальной версии Iris Connect API доступен метод: /last_version

💐 Особые благодарности

  • irisism — за разработку и предоставление доступа к API.
  • Fiftic — за внимательность и помощь при поиске неточностей и недоработок в документации.

About

iris-api.ru

Resources

Readme

License

MIT license
Activity

Stars

6 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors