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.

Роли и ограничения участников

Для этих методов требуется SDK 0.8.0 или новее. Лидер разрешает лавке или боту управлять ролями и ограничениями в разделе «Интеграции гильдии». manage_roles разрешает создавать и удалять роли, менять их название, права и порядок, назначать роли участникам. manage_member_restrictions разрешает просмотр и изменение личных ограничений. После перевыпуска токена или смены лидера права нужно выдать заново.

Пять методов покрывают все действия с ролями и участниками.

from dataclasses import replace
from uuid import uuid4
from atraxis import AtraxisClient

with AtraxisClient("agk_example.redacted") as client:
    operation_key = str(uuid4())  # Сохраните для повтора этого действия.
    created = client.manage_guild_roles(
        {"action": "create", "name": "Хранитель"},
        idempotency_key=operation_key,
    )
    print(created.role)

    # Выберите игровой ID участника своей гильдии.
    member = client.get_guild_member(100001)
    if member.restrictions is not None:
        flags = replace(member.restrictions, matrix_claim=True, guild_teleport=True)
        updated = client.update_guild_member(
            member.player_id,
            {"role": "member", "restrictions": flags.to_dict()},
            expected_version=member.version,
            idempotency_key=str(uuid4()),
        )
        print(updated.version)

В manage_guild_roles поле action определяет остальные поля запроса.

Новая роль создаётся без прав и лимита. В update передавайте все настройки, которые должны действовать после сохранения. Чтобы сохранить права или лимит, передайте их текущие значения. Пустой список permissions снимает все права, а max_members=None снимает лимит. Удаление назначает выбранную роль всем участникам удаляемой роли и сохраняет их личные ограничения. Роли leader и member защищены от удаления.

В update_guild_member пропущенные поля сохраняются. {"restrictions": None} снимает все ограничения. Для установки передайте все шесть флагов, где True запрещает действие. Роль и ограничения сохраняются вместе. Для изменения обоих полей токену нужны оба разрешения. Смена роли сохраняет ограничения, если поле restrictions пропущено. Через API нельзя передать лидерство, изменить роль лидера или установить ему ограничения.

Ограничения в ответе равны None, если токен не может ими управлять или участник это лидер гильдии. При создании роли expected_version необязателен. Если передать его, сервер проверит версию. Для остальных действий с ролями используйте version из get_guild_roles, для участника — его version из списка или get_guild_member. При 412 обновите данные, проверьте изменения и отправьте новое действие с новой версией и новым ключом. Ответ 409 означает, что ключ уже использован для другого запроса. Для повтора после сетевого сбоя сохраняйте прежние аргументы и ключ.

Все пять методов доступны в AsyncAtraxisClient. В MCP им соответствуют пять инструментов. Инструменты записи доступны с --allow-writes и требуют явный idempotency_key. Для изменения существующих настроек обязателен expected_version.

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

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–64 переводов;
• 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. При ошибке записи AtraxisError.idempotency_key содержит ключ отправленного действия, включая ключ, созданный SDK. Для повтора используйте его вместе с прежними аргументами и версией. AtraxisAPIError.retry_after содержит значение заголовка Retry-After, если сервер его передал. Ошибки MCP помечаются isError и содержат статус, 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 передавайте строкой без изменений.

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

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

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

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

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

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

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

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

История возвращает одну целую операцию на команду или запрос. У операции есть operation_id, время, источник и transfers со всеми позициями в исходном порядке. Каждая позиция содержит index, стороны, актив, gross, fee, net и доступный снимок предмета. deposit_method различает guild_deposit и tagged_transfer, а source_identity сохраняет платформу и внешний ID отправителя. У исторических записей дополнительные сведения могут отсутствовать.

По умолчанию get_activity() возвращает 20 операций, максимум — 50. Для первоначальной сверки получите полный склад и сохраните его контрольную точку:

with AtraxisClient("agk_example.redacted") as client:
    warehouse = client.get_warehouse()
    last_operation_id = warehouse.activity_checkpoint

Для последующих проверок используйте iter_new_activity(). Он получает операции от старых к новым и проходит все страницы. Передачи, появившиеся во время чтения, попадут в следующую проверку. Если у склада ещё нет истории, activity_checkpoint равен None: его также можно передать в after_operation_id:

with AtraxisClient("agk_example.redacted") as client:
    for operation in client.iter_new_activity(after_operation_id=last_operation_id):
        process_operation(operation)  # учитывает все operation.transfers
        last_operation_id = operation.operation_id

Сохраняйте operation_id вместе с результатом учёта операции в своей базе. Для повторных запросов оплаты или выдачи используйте прежний idempotency_key заказа. Новый ключ обозначает новую оплату или выдачу.

get_activity() также поддерживает order="desc", order="asc" и cursor. Передачи, появившиеся во время чтения страниц, попадут в следующую проверку. Поле checkpoint страницы можно сохранять после обработки всех её продолжений по next_cursor. После каждой отдельной обработанной операции можно сохранять её operation_id и продолжать через after_operation_id после перезапуска.

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

Переход на SDK 0.9 и контракт API 2.0

Обновление меняет формат /activity. Вместо ActivityEvent используется ActivityOperation, содержащий ActivityTransfer. Замените after_event_id на after_operation_id, а сохранённую позицию — на ID полностью обработанной операции. Старые курсоры отклоняются с явной ошибкой. Сначала согласуйте обновление интеграции и сервера, затем возобновите обработку. Сохранённые ключи заказов продолжают защищать повтор оплаты и выдачи.

Ошибки отдельных переводов содержат error.problem.transfer_index с номером позиции от нуля. Ошибка сохраняет idempotency_key и request_id. Если сервер требует ждать больше 30 секунд, SDK возвращает 429 с исходным retry_after, чтобы расписание повтора контролировала интеграция.

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

pip install "atraxis-sdk[mcp]"

MCP позволяет Codex и Claude Code читать события и объявления, помогать с API и работать с вашей гильдией. Для событий и объявлений токен не нужен. С ATRAXIS_API_TOKEN помощник сможет читать данные гильдии. Для переводов, настройки валют, ролей и ограничений запустите MCP с --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.