Atraxis Python SDK

Официальный Python SDK для API Atraxis. Читайте события и объявления игры, подключайте к гильдии своего бота, сайт или лавку: получайте содержимое склада, работайте с валютами и выдавайте ценности игрокам.

pip install atraxis-sdk

Требуется Python 3.10 или новее. Для событий и объявлений токен не нужен. Для работы с гильдией лидер выпускает токен в разделе «Интеграции гильдии». Храните его как пароль: он даёт доступ к складу, валютам и переводам вашей гильдии.

Публичные события и объявления

События и объявления доступны без токена:

from atraxis import AtraxisClient

with AtraxisClient() as client:
    for event in client.iter_events():
        print(event.title, event.status, event.ends_at)
    page = client.get_announcements()
    checkpoint = page.checkpoint
    for announcement in client.iter_new_announcements(after_id=checkpoint):
        print(announcement.text)

Эти методы доступны также в AsyncAtraxisClient. Токен нужен только для методов гильдии.

Для постоянного опроса вызывайте get_announcements(order="asc", after_id=checkpoint). Передавайте next_cursor, сохраняя те же фильтры и after_id, пока не обработаете все страницы; после этого сохраните последний checkpoint. История хранится 90 дней. Ответ 410 означает, что сохранённая позиция устарела: начните чтение без after_id и cursor. Лимит обоих публичных методов вместе — 300 запросов в минуту с IP; после 429 учитывайте Retry-After.

MCP-инструменты atraxis_get_events и atraxis_get_announcements доступны без ATRAXIS_API_TOKEN и без --allow-writes. Для инструментов гильдии настройте токен. OpenAPI: https://atraxisonline.com/api/developers/openapi.json.

Гильдии и лавки: быстрый старт

from atraxis import AtraxisClient, CurrencyTransfer

with AtraxisClient("agk_example.redacted") as client:
    warehouse = client.get_warehouse()
    for item in warehouse.items:
        print(item.warehouse_item_id, item.name, item.quantity)

        if item.instance and item.instance.kind == "equipment":
            print(item.instance.level, item.instance.quality, item.instance.combat_stats)

    result = client.transfer(
        [CurrencyTransfer.to_player("TOKEN", player_id=100001, amount=25)],
        idempotency_key="order-2026-09-12-0001",
    )
    print(result.operation_id)

Асинхронный клиент имеет те же методы:

import asyncio
from atraxis import AsyncAtraxisClient


async def main() -> None:
    async with AsyncAtraxisClient("agk_example.redacted") as client:
        async for event in client.iter_activity():
            print(event.occurred_at, event.kind, event.deposit_method, event.net)


asyncio.run(main())

Токен и адрес можно передать через ATRAXIS_API_TOKEN и ATRAXIS_API_BASE_URL. По умолчанию SDK обращается к основному серверу Atraxis. Токен не включается в repr, исключения или логи самого SDK.

Что умеет SDK

• get_events, iter_events — активные события;
• get_announcements, iter_announcements, iter_new_announcements — объявления и обновления ленты;
• get_warehouse, iter_warehouse — весь склад гильдии одним запросом;
• list_currencies, upsert_currency — внутренние валюты;
• resolve_player_identities — все подтверждённые ID одного игрока по игровому или платформенному ID;
• get_balances — балансы игрока;
• transfer — единая операция из 1–10 переводов;
• get_activity, iter_activity, iter_new_activity — история операций гильдии и последовательное получение новых записей.

Все суммы представлены в Python как int, а по сети передаются десятичными строками. Модели неизменяемы. Новые необязательные поля ответа не ломают клиент, но обязательные поля всегда проверяются.

У предмета на складе два идентификатора: item_id обозначает общий тип предмета, а warehouse_item_id — конкретную позицию, которую нужно передать при выдаче. Для уникальной позиции is_unique равен True, а instance содержит характеристики именно этого экземпляра: боевые параметры и улучшения экипировки, бонусы инструментов и удочек, умения щита, свойства улова, состояние артефакта или журнала. В condition указаны прочность и её единица — percent или points. Поля durability и max_durability сохранены для совместимости со старыми подключениями.

Переводы

from atraxis import CurrencyTransfer, ItemTransfer

parts = [
    ItemTransfer(warehouse_item_id=700001, player_id=100001, amount=1),
    CurrencyTransfer.issue("TOKEN", amount=100),
    CurrencyTransfer.retire("TOKEN", amount=10),
    CurrencyTransfer.to_player("TOKEN", player_id=100001, amount=25),
    CurrencyTransfer.from_player("TOKEN", player_id=100001, amount=5),
    CurrencyTransfer.between_players(
        "TOKEN",
        from_player_id=100001,
        to_player_id=100002,
        amount=3,
    ),
]

Передавайте в idempotency_key постоянный идентификатор перевода или заказа. Если ключ не задан, SDK создаст UUID и вернёт его в TransferResult.idempotency_key. Повторный POST внутри SDK использует тот же ключ.

Транспортные ошибки, 429, 502, 503 и 504 повторяются не более двух раз. При 429 учитывается Retry-After. Ошибки API представлены AtraxisAPIError; в них доступны ответ API и request_id. Для /activity доступно до 300 запросов в минуту с одного IP и 60 на гильдию. Остальные методы гильдии имеют отдельный лимит: до 100 запросов с IP и 60 на гильдию.

Полная интерактивная документация: https://atraxisonline.com/developers/api.

Кроссплатформенные идентификаторы

Лавке не нужно отдельно просить покупателя зарегистрировать ID в Telegram, VK или на другой платформе. Передайте любой известный идентификатор, и API вернёт игровой ID вместе со всеми текущими подтверждёнными привязками:

with AtraxisClient("agk_example.redacted") as client:
    identities = client.resolve_player_identities("telegram", "987654321")
    game_id = int(identities.by_platform["game"])

platform — game для игрового ID или код платформы из поля provider в /api/providers. Внешний player_id передавайте строкой без изменений.

Как пополняется склад и выдаются предметы

Свой склад пополняют на странице гильдии или через основной бот. В привязанном чате гильдии используйте Внести …. Участник с правом брать предметы со склада может там же использовать Забрать …. Обе команды принимают до 10 позиций через точку с запятой:

Внести Стабилизатор - 2 штуки; 1000 кредитов
Забрать Стабилизатор - 2 штуки; номер 4

Номер N относится к последнему списку соответствующего раздела склада в основном боте. Для выдачи нужны право брать предметы со склада и свободное место в сумке.

В любом чате Авроры, где работает обычное Передать, можно выбрать склад любой гильдии по её уникальному тегу:

Передать ТЕГ Стабилизатор - 2 штуки
Передать ТЕГ 1000 кредитов; номер 4 - 2 штуки

Укажите тег перед названием предмета, без скобок. Команда работает в чатах Авроры, кроме общего; членство в выбранной гильдии не требуется.

Через API их можно только выдавать со склада игрокам. Списать их у игрока через API нельзя.

Для учёта пополнений читайте iter_activity(). В новых операциях warehouse_deposit поле deposit_method равно guild_deposit для обычного пополнения, в том числе команды «Внести», и tagged_transfer для команды «Передать ТЕГ». Поле source уточняет канал: chat — чат Авроры, game — страница гильдии или основной бот. Поле source_identity содержит фактические platform и player_id, с которых пришло новое пополнение; у старых и системных записей оно отсутствует. Поле warehouse_item сохраняет характеристики конкретного экземпляра и количество в позиции до и после передачи, даже если позднее предмет исчезнет со склада. В старых записях это поле может отсутствовать. Новая выдача через Забрать … записывается как warehouse_withdrawal с source="chat"; метод iter_activity() получает её без отдельного SDK-вызова.

Для регулярного получения новых операций достаточно хранить один event_id. При первом подключении запрос без after_event_id возвращает историю от новых записей к старым. Если нужно начать следить только за будущими операциями, сохраните идентификатор самой новой записи:

with AtraxisClient("agk_example.redacted") as client:
    page = client.get_activity(page_size=1)
    last_event_id = page.items[0].event_id if page.items else None

При следующих проверках передавайте сохранённый идентификатор. iter_new_activity явно запрашивает порядок от старых к новым и проходит все страницы одной выборки. Сохраняйте новый идентификатор после успешной обработки каждой записи:

if last_event_id is not None:
    with AtraxisClient("agk_example.redacted") as client:
        for event in client.iter_new_activity(after_event_id=last_event_id):
            process(event)
            last_event_id = event.event_id

after_event_id только исключает указанную и более старые записи и не меняет сортировку. get_activity принимает order="desc" или order="asc"; cursor можно передавать вместе с after_event_id, если он получен для тех же параметров. available_since показывает начало истории, которая ещё доступна на сервере. Если сохранённая запись уже вышла за этот срок, API попросит начать без after_event_id и сохранить новый идентификатор. У старых и системных пополнений deposit_method может отсутствовать. Налоговые начисления учитываются отдельно и в этой истории операций не возвращаются.

Для первоначальной сверки вызовите get_warehouse(): метод возвращает весь склад без пагинации. В ответе доступен activity_checkpoint. Передайте его в iter_new_activity, чтобы затем получать операции, появившиеся после этой сверки. Налоги и системные механики могут менять склад без записи в истории передач, поэтому периодически запрашивайте склад заново.

Подключение к Codex и Claude Code

pip install "atraxis-sdk[mcp]"

MCP позволяет Codex и Claude Code читать события и объявления, помогать с API и работать с вашей гильдией. Для событий и объявлений токен не нужен. С ATRAXIS_API_TOKEN помощник сможет читать данные гильдии. Команды, которые меняют валюты или передают ценности, доступны только после запуска с --allow-writes; для каждого перевода потребуется idempotency_key.

Codex в режиме только для чтения, с уже установленной переменной окружения:

[mcp_servers.atraxis]
command = "atraxis-mcp"
env_vars = ["ATRAXIS_API_TOKEN"]

Или через CLI:

codex mcp add atraxis --env ATRAXIS_API_TOKEN="$ATRAXIS_API_TOKEN" -- atraxis-mcp

Claude Code:

claude mcp add --transport stdio --env ATRAXIS_API_TOKEN="$ATRAXIS_API_TOKEN" atraxis -- atraxis-mcp

Готовые конфигурации без токенов лежат в examples/mcp. Чтобы разрешить изменения, добавьте --allow-writes в args только на своём устройстве и только для помощника, которому доверяете.

Лицензия

MIT.