Atraxis Python SDK

Официальный компактный SDK для подключения лавок, ботов и учётных систем к гильдии Atraxis. Лидер выпускает приватный токен в разделе «Интеграции гильдии», а API определяет по нему нужную гильдию.

pip install atraxis-sdk

Требуется Python 3.10 или новее.

Быстрый старт

from atraxis import AtraxisClient, CurrencyTransfer

with AtraxisClient("agk_example.redacted") as client:
    for item in client.iter_warehouse():
        print(item.warehouse_item_id, item.name, item.quantity)

    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.net)


asyncio.run(main())

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

Related MCP server: MCP Coding Agents

Методы

• get_warehouse, iter_warehouse — склад гильдии;

• list_currencies, upsert_currency — внутренние валюты;

• get_balances — балансы игрока;

• transfer — единая операция из 1–10 переводов;

• get_activity, iter_activity — история операций гильдии.

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

Переводы

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; в них доступны безопасный problem response и request_id.

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

Локальный MCP для Codex и Claude Code

pip install "atraxis-sdk[mcp]"

Без токена MCP показывает только публичный контракт. С ATRAXIS_API_TOKEN появляются методы чтения. Изменяющие инструменты регистрируются только при явном --allow-writes; перевод через MCP всегда требует явно переданный idempotency_key.

Codex, безопасный read-only вариант с передачей уже установленной переменной окружения:

[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 только для локальной конфигурации, которой доверяете.

Контракт и разработка

Канонический контракт обслуживает Atraxis Backend. В репозитории находится только проверенный публичный snapshot для тестов и релизов:

python scripts/sync_openapi.py https://atraxisonline.com/api/developers/guild-commerce/openapi.json

Для локальной проверки допускается явный путь к YAML/JSON. Скрипт принимает только шесть публичных операций, относительный сервер и закрытые allowlist-схемы склада и активности.

python -m pip install -e ".[dev]"
ruff check .
mypy
pytest
python -m build

Лицензия

MIT.