Урок 1.1 — Как проходить курс
Добро пожаловать в мир Crypto Pay API! Этот урок — ваш навигатор по курсу. Мы расскажем, как устроен курс, что такое aiosend и Crypto Pay API, и как получить максимум пользы от обучения.
Приветствие
Привет, друг! 👋
Если ты читаешь эти строки — ты уже сделал первый и самый важный шаг: решил научиться работать с Crypto Pay API с помощью Python. Это решение откроет перед тобой двери в мир криптовалютных платежей, Telegram-ботов и финансовой автоматизации. Каждый день через @CryptoBot проходят миллионы транзакций, и теперь у тебя есть возможность стать частью этой экосистемы.
Этот курс создан, чтобы максимально упростить твой вход в тему. Я помню, как сам когда-то разбирался с документацией Crypto Pay API и думал: «Почему нет нормальной Python-обёртки, которая скрыла бы всю рутину HTTP-запросов и JSON?» — и тут я наткнулся на aiosend. Библиотека, написанная vovchic17, выросла из личного проекта в полноценный инструмент с тысячами установок. В этом курсе я делюсь всеми знаниями, которые помогут тебе освоить работу с этой библиотекой.
В этом курсе нет «воды». Каждая минута твоего времени — это конкретные знания, которые ты сразу можешь применить на практике. Мы не будем просто пересказывать документацию — мы будем понимать, как работает Crypto Pay API изнутри, почему aiosend устроен именно так, и как писать красивый, профессиональный, production-ready код для приёма криптовалютных платежей.
К концу курса ты сможешь создавать полноценные платёжные решения на Python: от простого инвойса для доната до сложной системы с вебхуками, балансами, массовыми переводами и интеграцией с популярными Telegram-библиотеками (aiogram, pyTelegramBotAPI, python-telegram-bot, Pyrogram, Telethon). И всё это — с помощью одной библиотеки: aiosend.
Что такое Crypto Pay API
Crypto Pay API — это официальный API платежной системы @CryptoBot (на английском — @send). @CryptoBot — это популярный Telegram-бот, созданный командой @CryptoBot, который позволяет пользователям отправлять и получать криптовалюты прямо внутри Telegram. С 2021 года он обслуживает миллионы транзакций, а его API используется тысячами разработчиков по всему миру.
Поддерживаемые криптовалюты: USDT, TON, BTC, ETH, LTC, BNB, TRX, USDC (и JET для тестовой сети). А также множество фиатных валют для номинации счетов: USD, EUR, RUB, BYN, UAH, GBP, CNY, KZT, UZS, GEL, TRY, AMD, THB, INR, BRL, IDR, AZN, AED, PLN, ILS.
Crypto Pay API предоставляет разработчикам следующие возможности:
API работает на основе простых HTTP-запросов. Ты отправляешь GET или POST-запрос на сервер https://pay.crypt.bot/api/ (или https://testnet-pay.crypt.bot/api/ для тестовой сети), передаёшь токен в заголовке Crypto-Pay-API-Token, и получаешь JSON-ответ. Звучит просто, но есть множество нюансов: правильное формирование заголовков, обработка ошибок (а их у API немало), управление асинхронностью, таймауты, повторные попытки при сбоях — именно здесь на помощь приходит aiosend.
🔍 Как это работает «под капотом»
Когда ты вызываешь await cp.create_invoice(100, "USDT"), aiosend:
1. Берёт твой токен и формирует HTTP-заголовок Crypto-Pay-API-Token: 1234:abc...
2. Определяет сеть (MAINNET или TESTNET) по токену
3. Формирует POST-запрос к https://pay.crypt.bot/api/createInvoice с JSON-телом {"amount": 100, "asset": "USDT"}
4. Отправляет запрос через aiohttp (асинхронно)
5. Получает JSON-ответ, проверяет поле ok
6. Десериализует result в Pydantic-модель Invoice
7. Возвращает тебе готовый объект Invoice
⚠️ Важно понимать
Crypto Pay API — это не блокчейн и не криптовалютная биржа. Ты не отправляешь транзакции напрямую в сеть Bitcoin или Ethereum. Вместо этого ты работаешь через централизованный сервис @CryptoBot, который управляет кошельками пользователей и берёт на себя все сложности блокчейн-транзакций. Это похоже на платёжный шлюз вроде Stripe или PayPal, но для криптовалют: ты создаёшь счёт, пользователь платит через бота, а API уведомляет тебя об успешной оплате. Все внутренние перемещения средств между кошельками @CryptoBot происходят мгновенно и без комиссий сети.
Что такое aiosend
aiosend — это современная Python-библиотека (обёртка) для Crypto Pay API, опубликованная на PyPI под лицензией MIT. Она создана, чтобы разработчики могли работать с API @CryptoBot без необходимости вручную формировать HTTP-запросы, разбирать JSON-ответы и обрабатывать ошибки. Библиотека написана на чистом Python с использованием pydantic для моделей данных и aiohttp для асинхронных HTTP-запросов.
Название библиотеки составлено из двух частей: "aio" (асинхронный ввод-вывод, от asyncio) и "send" (отсылка/перевод — основная функция сервиса). Хотя библиотека полностью поддерживает и синхронный режим работы, её главная сила и предназначение — в асинхронной работе с asyncio.
Ключевые возможности aiosend:
✅ Асинхронный и синхронный режимы
Работай как с async/await (через asyncio), так и в классическом синхронном стиле (через .sync). Выбирай под свою задачу: для Telegram-ботов — async, для простых скриптов — sync.
✅ Полная типизация (Type Hints)
Все методы и модели полностью аннотированы типами. Pydantic-модели обеспечивают валидацию данных на лету. MyPy-совместимость, автодополнение в любой современной IDE (VS Code, PyCharm). Минимум ошибок на пустом месте.
✅ Invoice и Check Polling
Встроенные механизмы опроса статуса оплат без необходимости настраивать вебхуки и иметь публичный сервер. Просто создаёшь инвойс, подписываешься на событие, и aiosend сам проверяет, не оплачен ли он.
✅ Вебхуки (Webhook)
Полноценная поддержка вебхуков на базе aiohttp. Получай уведомления об оплатах мгновенно, без задержек опроса. Требуется публичный HTTPS-сервер.
✅ Magic Filters из aiogram 3.x
Мощные и знакомые фильтры для событий. Фильтруй оплаты по сумме, активу, пользователю и любым другим полям с помощью простого и выразительного синтаксиса.
✅ Dependency Injection (DI)
Внедрение зависимостей для удобной интеграции с другими библиотеками. Особенно полезно при работе с aiogram 3.x — ты можешь получать экземпляр CryptoPay прямо в хендлерах.
✅ Shortcut Methods
Сокращённые методы на объектах: invoice.update(), invoice.delete(), invoice.poll(), invoice.qr, check.get_image(). Удобно и интуитивно.
✅ Поддержка всех методов API
Все 13 официальных методов Crypto Pay API реализованы и задокументированы. Полная функциональность «из коробки».
Библиотека опубликована на PyPI (https://pypi.org/project/aiosend/) с открытым исходным кодом под лицензией MIT. Исходный код доступен на GitHub (https://github.com/vovchic17/aiosend), а полная документация — на Read the Docs (https://aiosend.readthedocs.io/). Версия на момент написания курса — 3.0.x (поддерживает Python 3.10+).
💡 Почему aiosend, а не requests напрямую?
Ты, конечно, можешь использовать requests или aiohttp для работы с Crypto Pay API напрямую. Но aiosend берёт на себя всю рутину: сериализацию/десериализацию, обработку ошибок (все 20+ типов ошибок API), управление HTTP-сессией, таймауты, автозакрытие соединений. Твой код становится в 5-10 раз короче и понятнее. Сравни сам:
# Без aiosend — 20+ строк кода, ручная обработка всего
import requests
TOKEN = "your_token"
url = "https://pay.crypt.bot/api/getMe"
headers = {"Crypto-Pay-API-Token": TOKEN}
try:
response = requests.get(url, headers=headers, timeout=30)
response.raise_for_status()
data = response.json()
if data["ok"]:
app = data["result"]
print(f"App name: {app['name']}")
print(f"App ID: {app['app_id']}")
else:
error = data.get("error", {})
print(f"API Error {error.get('code')}: {error.get('name')}")
except requests.exceptions.Timeout:
print("Request timed out")
except requests.exceptions.RequestException as e:
print(f"Network error: {e}")
# С aiosend — 4 строки, всё под капотом
from aiosend import CryptoPay
cp = CryptoPay(token="TOKEN")
app = cp.sync.get_me()
print(f"App name: {app.name}")Разница колоссальная. И это только для простейшего метода getMe. Для более сложных методов (createInvoice с десятком опциональных параметров) разница в объёме кода становится ещё более впечатляющей.
Кроме того, aiosend предоставляет дополнительные удобства, которых нет в голом API:
- Автоматическое определение сети — по формату токена библиотека сама понимает, MAINNET это или TESTNET
- Валидация параметров — если ты передашь неверный актив (например, "XYZ"), pydantic выдаст ошибку ДО отправки запроса
- Удобные enum's —
Asset,Fiat,InvoiceStatus,CheckStatusи другие вместо строк-констант - Контекстный менеджер —
async with CryptoPay(...) as cpдля автоматического закрытия сессии - Интеграция с популярными библиотеками — готовые примеры для aiogram 3.x, 2.x, pyTelegramBotAPI, PTB, Pyrogram, Telethon
Как устроен курс
Курс разделён на 9 модулей, каждый из которых посвящён конкретной теме работы с aiosend и Crypto Pay API. Внутри каждого модуля — несколько последовательных уроков. Идти нужно строго по порядку: каждый урок опирается на знания из предыдущего. Даже если тема кажется знакомой — всё равно прочитай урок, в нём могут быть важные детали.
Полная структура курса:
- Модуль 1. Введение — как проходить курс, установка aiosend, получение токена, первое приложение (3 урока)
- Модуль 2. Работа со счетами (Invoices) — создание, удаление, получение списков, фильтрация, статусы инвойсов
- Модуль 3. Чеки (Checks) — создание, активация, управление чеками, привязка к пользователям
- Модуль 4. Переводы (Transfers) — отправка средств пользователям, idempotency через spend_id, комиссии, лимиты
- Модуль 5. Баланс и курсы — получение баланса, курсов валют, статистики приложения, работа с курсами обмена
- Модуль 6. Обработка ошибок — APIError, APITimeoutError, WrongNetworkError, DeserializationError, best practices обработки
- Модуль 7. События и вебхуки — invoice polling, check polling, webhook, filters, routers, конфигурация polling
- Модуль 8. Интеграция с Telegram-ботами — aiogram 3.x, aiogram 2.x, pyTelegramBotAPI, python-telegram-bot, Pyrogram, Telethon
- Модуль 9. Продвинутые темы — Dependency Injection, Shortcut Methods, Type Hints, Warnings, Best Practices, production-разработка, деплой
Каждый урок устроен по единому шаблону:
🎯 Рекомендуемый темп обучения
Оптимально проходить 1 урок в день. Урок занимает примерно 40-60 минут: 15-20 минут теории с примерами, 15 минут практики с кодом (набрать и запустить примеры), 10 минут на тест, 15-20 минут на практическую задачу. Не торопись — дай знаниям улечься. Между уроками полезно делать паузу хотя бы в несколько часов, а лучше — до следующего дня.
⚠️ Предупреждение о последовательности
Не перескакивай через уроки! Каждый модуль логически продолжает предыдущий. Например, чтобы понять вебхуки из Модуля 7, нужно сначала разобраться с инвойсами из Модуля 2. А для Модуля 8 (интеграция с ботами) требуется понимание всех предыдущих тем. Исключение — если ты уже знаком с темой конкретного урока, можешь пробежать его по диагонали, но обязательно выполни практическую задачу.
Подробное содержание модулей
Давай подробно разберём каждый модуль, чтобы ты понимал, чему именно научишься:
Модуль 1: Введение (3 урока)
Установка Python и aiosend, получение API-токена, знакомство с MAINNET и TESTNET, создание первого скрипта, структура проекта, работа с .env-файлами. Результат: ты сможешь подключиться к Crypto Pay API и получить информацию о своём приложении.
Модуль 2: Работа со счетами (Invoices)
Создание инвойсов в криптовалюте и фиате, настройка параметров (описание, скрытое сообщение, кнопка после оплаты, срок действия), удаление инвойсов, получение списка с фильтрацией по статусу, активу, дате. Разберём все нюансы: лимиты, комиссии, expired-статус.
Модуль 3: Чеки (Checks)
Создание чеков с привязкой к конкретному пользователю (по ID или username), активация чеков, удаление, получение списка. Разберём формат bot_check_url, хэши, статусы. Научимся генерировать изображения чеков.
Модуль 4: Переводы (Transfers)
Отправка средств пользователям, механизм idempotent requests (spend_id), комментарии к переводам, отключение уведомлений. Лимиты и комиссии. Получение истории переводов.
Модуль 5: Баланс, курсы и статистика
Получение баланса по каждому активу (available/onhold), курсы обмена валют, список поддерживаемых валют с их свойствами, статистика инвойсов (конверсия, объём, пользователи).
Модуль 6: Обработка ошибок
Все типы исключений aiosend: APIError (код + имя ошибки), APITimeoutError, WrongNetworkError, DeserializationError, CryptoPayError. Практические паттерны обработки, retry-логика, graceful degradation.
Модуль 7: События и вебхуки
Роутеры и наблюдатели событий, invoice polling (периодический опрос), check polling, webhook (настройка HTTP-сервера), фильтры по типу события и данным, payload-данные. Настройка интервалов polling.
Модуль 8: Интеграция с Telegram-ботами
Готовые примеры интеграции aiosend с популярными библиотеками: aiogram 3.x (рекомендуемый вариант), aiogram 2.x, pyTelegramBotAPI (синхронный и асинхронный), python-telegram-bot, Pyrogram, Telethon.
Модуль 9: Продвинутые темы
Dependency Injection (провайдеры, DI-контейнер), Shortcut Methods на типах, Type Hints и Literal-типы, Wrong Network Warning (предупреждение о неверной сети), AiohttpSession, Best Practices, подготовка к production (логирование, мониторинг, деплой).
Правила прохождения курса
Чтобы получить максимальную пользу от курса, следуй этим простым, но важным правилам:
📖 Правило 1: Читай внимательно
Не пролистывай текст. Каждый абзац написан с определённой целью — объяснить концепцию, предостеречь от ошибки или дать полезный совет. Если что-то непонятно — перечитай ещё раз. Если всё равно непонятно — загугли, загляни в документацию aiosend, открой официальную документацию Crypto Pay API. Программирование — это навык понимания, а не запоминания. Понимание приходит через многократное осмысление.
⌨️ Правило 2: Код — руками
Недостаточно просто читать примеры кода. Ты должен сам набирать каждый пример в своём редакторе. Мышцы пальцев запоминают синтаксис. Когда ты сам напишешь cp = CryptoPay(token="TOKEN"), await cp.get_me(), await cp.create_invoice(100, "USDT") — эти конструкции останутся с тобой навсегда. Если просто прочитаешь — забудешь через час. Не копируй из буфера обмена — набирай вручную, строка за строкой.
🧩 Правило 3: Решай задачи
В конце каждого урока есть практическая задача. Реши её обязательно. Если не получается — вернись к теории, разбери примеры, попробуй ещё раз. Не смотри в решение сразу (если оно есть) — дай себе время подумать. Минимум 15-20 минут самостоятельных попыток. Именно в моменте «я не знаю, как это сделать» происходит рост программиста. Преодоление этого барьера — и есть обучение.
🐢 Правило 4: Никакой спешки
Не пытайся пройти курс за один день или даже за неделю. Это марафон, а не спринт. В курсе 9 модулей и десятки уроков. Оптимальный темп — 1 урок в день. Между уроками делай перерывы, дай мозгу «переварить» информацию. Если чувствуешь, что устал — остановись, отдохни, вернись завтра. Качественное усвоение материала важнее скорости прохождения. Лучше пройти 1 урок и всё понять, чем 5 уроков и ничего не запомнить.
🧪 Правило 5: Экспериментируй
Не бойся менять код из примеров. Что будет, если передать неверный токен? А если создать инвойс без суммы? А если указать несуществующий актив? А если передать отрицательную сумму? Специально «ломай» код — так ты поймёшь границы библиотеки и научишься читать ошибки. Программист, который не боится экспериментировать, учится в 10 раз быстрее. Создай отдельную песочницу для экспериментов и пробуй всё, что придёт в голову.
⚠️ Важное предупреждение
Программирование — это трудно. Будут моменты, когда ты захочешь всё бросить, когда код не работает, а ошибка непонятна. Это нормально. Так бывает у всех — от новичка до senior-разработчика с 20-летним стажем. Разница только в том, что опытный программист не паникует, а спокойно ищет причину: читает ошибку, проверяет входные данные, гуглит, отлаживает. Этому ты тоже научишься в процессе курса. И помни: у aiosend есть комьюнити-чат в Telegram, где всегда помогут советом.
🤝 Правило 6: Задавай вопросы
Если что-то непонятно — не молчи. Программирование — это коллективная деятельность. Вопросы можно задавать:
— В Telegram-чате aiosend (aiosend.t.me)
— На Stack Overflow с тегом [aiosend]
— В комментариях к уроку (если они есть)
При формулировке вопроса описывай: что хотел сделать, что сделал, какой результат ожидал, какой результат получил, приложи код и текст ошибки. Хорошо сформулированный вопрос — это 50% ответа.
Формат уроков
Каждый урок в этом курсе представляет собой HTML-страницу с хорошо структурированным содержимым. Вот из каких элементов состоит типичный урок:
🔷 Шапка урока (Header)
Градиентный заголовок с указанием модуля, номера урока, названия и кратким описанием. Цвет градиента соответствует модулю: сине-индиго (from-blue-600 to-indigo-500) для Модуля 1.
🔷 Информационные блоки
Разделы с иконками и заголовками (h2). Каждый раздел раскрывает одну концепцию. Внутри — объяснения, маркированные списки, нумерованные инструкции.
🔷 Примеры кода (Code Blocks)
Каждый пример в тегах <pre><code> с меткой сверху (например, "Python · Пример создания инвойса"). Код можно скопировать и запустить. Комментарии в коде объясняют ключевые строки.
🔷 Info-боксы (Tip / Warning)
Цветные блоки с левой рамкой: зелёные (💡 советы и рекомендации), жёлтые (⚠️ предупреждения), синие (🔍 технические детали), фиолетовые (🎯 цели).
🔷 Таблицы и сетки
Сравнение корректных и некорректных примеров (✅/❌) в двухколоночной сетке. Таблицы для структурирования параметров, кодов ошибок, типов данных.
🔷 Практическая задача
Финальное задание, которое требует написать код. Задача проверяет понимание всех концепций урока. Выполнение обязательно для закрепления материала.
💡 Как работать с кодом в уроках
В каждом уроке ты будешь видеть блоки кода на Python, Bash (команды терминала), JSON (примеры ответов API). Мы рекомендуем создать структуру директорий для курса: aiosend-course/module-01/ и внутри — папку для каждого урока. Так ты всегда сможешь вернуться к своим экспериментам и решениям задач.
import asyncio
from aiosend import CryptoPay
async def main() -> None:
# Создаём экземпляр клиента с нашим токеном
cp = CryptoPay(token="1234:ABCdefghijklmnop") # замени на свой токен!
# Вызываем метод getMe() — получаем информацию о приложении
app = await cp.get_me()
# Выводим основные поля объекта App
print(f"Название приложения: {app.name}")
print(f"ID приложения: {app.app_id}")
print(f"Платёжный бот: @{app.payment_processing_bot_username}")
if __name__ == "__main__":
# Запускаем асинхронную функцию
asyncio.run(main())from aiosend import CryptoPay
# Синхронный режим — используем .sync
cp = CryptoPay(token="1234:ABCdefghijklmnop")
app = cp.sync.get_me()
print(f"Название приложения: {app.name}")
print(f"ID приложения: {app.app_id}")Ожидаемый результат после курса
После прохождения этого курса ты:
От создания простых инвойсов до полноценной системы оплат с вебхуками, фильтрацией событий и интеграцией с Telegram-ботами.
async/await, event loop, корутины, конкурентность — перестанешь бояться этих терминов и начнёшь использовать их на практике.
Важнейший навык: 90% времени программист читает документацию, а не пишет код. Crypto Pay API — отличный пример хорошо задокументированного API.
Telegram-боты, веб-сайты, мобильные приложения — любой проект можно монетизировать через Crypto Pay.
Поймёшь, как обрабатывать ошибки, управлять состоянием, настраивать вебхуки, работать с балансами и конкурентными запросами.
pip, venv, dotenv, asyncio, pydantic, aiohttp — твой джентльменский набор для работы с API.
Но самое главное — ты поймёшь, как думает разработчик API-интеграций. Это не набор фактов, а особый способ мышления: понимание протоколов (HTTP, REST), умение читать JSON, знание HTTP-статусов (200, 400, 401, 500), способность отлаживать сетевые запросы с помощью curl или Postman. Этот навык останется с тобой навсегда и пригодится при работе с любым API — не только Crypto Pay.
Что ты сможешь создавать после курса
Вот лишь несколько примеров реальных проектов, которые ты сможешь реализовать:
🤖 Telegram-магазин с оплатой в криптовалюте
Пользователь выбирает товар в боте, получает инвойс на оплату, оплачивает USDT/TON/BTC через @CryptoBot, бот подтверждает оплату через polling/webhook и выдаёт товар (цифровой или информацию для доставки).
💸 Криптокошелёк с функцией переводов
Приложение, которое может отправлять средства пользователям, проверять баланс по каждому активу, вести историю входящих и исходящих транзакций.
🎁 Раздача чеков (Airdrop)
Создание сотен или тысяч чеков для массовой раздачи криптовалюты участникам сообщества. Автоматическая генерация, логирование, мониторинг активаций.
📊 Панель аналитики платежей
Сбор статистики по оплатам через getStats, построение графиков конверсии, отслеживание объёмов в USD, уникальных пользователей.
🔄 Криптообменник с конвертацией
Сервис, который принимает оплату в одной криптовалюте и автоматически конвертирует в другую (через swap_to). Пользователь платит в USDT, а получает TON.
🔐 Система донатов/подписок
Интеграция с Telegram-каналом или ботом: пользователи отправляют донаты или оплачивают подписку, после оплаты получают доступ к закрытому контенту.
Полезные ссылки
Вот ресурсы, которые пригодятся тебе на всём пути обучения. Сохрани этот список — ты будешь обращаться к нему постоянно:
aiosend.readthedocs.io — первоисточник по библиотеке. Установка, API (методы, типы, enums, ошибки), клиент (тулы, шорткаты, DI), события (роутеры, вебхуки, polling), примеры интеграции. Читай, когда хочешь углубиться в детали конкретного метода.
send.t.me — основной бот для работы с криптовалютами в Telegram. Через него пользователи оплачивают инвойсы, активируют чеки и получают переводы. Также доступен в веб-версии и как Telegram Mini App.
@CryptoTestnetBot — тестовая версия @CryptoBot. Используй её для разработки и отладки. Тестовые монеты можно получить через кран (faucet) внутри бота.
aiosend.t.me — чат сообщества пользователей и разработчиков библиотеки. Задавай вопросы, делись опытом, получай помощь от автора (@vovchic17) и других разработчиков. Здесь же публикуются новости о новых версиях.
pypi.org/project/aiosend — страница пакета на Python Package Index. Актуальная версия, зависимости (aiohttp, certifi, magic-filter, pydantic), история изменений (changelog).
github.com/vovchic17/aiosend — исходный код библиотеки. Можно читать, форкать, предлагать улучшения через Pull Requests, сообщать об ошибках через Issues.
help.send.tg/en/articles/10279948-crypto-pay-api — полное описание всех методов, типов, ошибок. Полезно, когда хочешь понять, что именно вызывает aiosend под капотом, или проверить актуальность параметров.
stackoverflow.com — если у тебя ошибка, с вероятностью 99% кто-то уже сталкивался с ней. Копируй текст ошибки в Google и добавляй "aiosend" или "Crypto Pay API".
docs.python.org — если нужно освежить знания Python: asyncio, dotenv, pip, venv, исключения.
⚠️ Совет по работе с документацией
Ошибки в aiosend выглядят понятно: APIError: INVOICE_NOT_FOUND. Скопируй название ошибки (INVOICE_NOT_FOUND) в документацию Crypto Pay API — и ты сразу поймёшь, что пошло не так. Умение читать ошибки и документацию — это суперсила разработчика. Не игнорируй её, не паникуй — анализируй.
Общие рекомендации по работе с API
Работа с любым API (в том числе Crypto Pay) требует соблюдения базовых принципов. Вот что нужно знать и помнить:
📡 HTTP-методы: GET vs POST
Crypto Pay API использует GET-запросы для методов, которые не требуют параметров (getMe, getBalance, getExchangeRates, getCurrencies), и POST — для методов, требующих передачи данных (createInvoice, createCheck, transfer, deleteInvoice, getInvoices с фильтрами). aiosend скрывает эту деталь, но полезно понимать, какие запросы отправляются «под капотом» — это поможет при отладке.
🔑 Аутентификация через токен
Для доступа к API используется токен, который передаётся в HTTP-заголовке Crypto-Pay-API-Token. Токен выдаётся при создании приложения в @CryptoBot (@CryptoTestnetBot). Токен — это секрет! Никогда не публикуй его в открытом коде, не коммить в Git, не передавай третьим лицам. Используй .env-файлы или переменные окружения.
📊 Коды ответов HTTP
200 OK — успешный запрос, тело ответа содержит JSON.
400 Bad Request — неверные параметры (например, не указан обязательный параметр).
401 Unauthorized — неверный или отсутствующий токен.
500 Internal Server Error — ошибка на стороне сервера @CryptoBot. В этом случае нужно повторить запрос позже.
🌐 Сети: MAINNET и TESTNET
Crypto Pay API работает в двух независимых сетях:
— MAINNET (реальные деньги, бот @CryptoBot, URL: https://pay.crypt.bot/api/)
— TESTNET (тестовые монеты, бот @CryptoTestnetBot, URL: https://testnet-pay.crypt.bot/api/)
Для разработки и тестирования всегда используй TESTNET. Переключение на MAINNET происходит автоматически при смене токена. aiosend определяет сеть по токену.
⚠️ Rate Limiting
Crypto Pay API имеет ограничения на количество запросов (rate limiting). Если ты отправляешь слишком много запросов за короткое время, API может вернуть ошибку 429 Too Many Requests. В aiosend встроена защита от этого, но в production-решениях рекомендуется добавить собственную retry-логику с экспоненциальной задержкой.
Как работать с ошибками
Ошибки — это нормальная часть разработки. Вот как комфорно с ними работать в контексте aiosend:
INVOICE_NOT_FOUND, NOT_ENOUGH_BALANCE, ASSET_NOT_FOUND.
⚠️ Что делать, если код не работает?
1. Прочитай ошибку — в ней часто уже написана причина. Не игнорируй красный текст!
2. Проверь токен — правильный ли он? Не истёк ли? Тот ли бот (Testnet/Mainnet)?
3. Проверь сеть — MAINNET или TESTNET? Вызов transfer в TESTNET вызовет WrongNetworkError.
4. Проверь параметры — не передаёшь ли ты несуществующий актив? Не превышен ли лимит суммы?
5. Загугли текст ошибки — скопируй в Google с добавлением "aiosend" или "crypto pay api".
6. Спроси в Telegram-чате — комьюнити aiosend активно и дружелюбно.
7. Перечитай теорию урока — возможно, упустил важную деталь.
8. Отдохни — иногда решение приходит после перерыва.
from aiosend import CryptoPay
from aiosend.errors import APIError, APITimeoutError
cp = CryptoPay(token="TOKEN")
try:
app = cp.sync.get_me()
print(f"App: {app.name}")
except APIError as e:
print(f"API error {e.code}: {e.name}")
except APITimeoutError:
print("Request timed out, try again later")
except Exception as e:
print(f"Unexpected error: {e}")Часто задаваемые вопросы (FAQ)
❓ Нужен ли опыт программирования для этого курса?
Желательно базовое знание Python: переменные, функции, импорты, установка пакетов через pip. Если ты совсем новичок — рекомендую сначала пройти любой базовый курс Python (хотя бы неделю-две), а потом возвращаться к aiosend.
❓ Нужно ли знать асинхронное программирование?
Нет, мы разберём основы async/await в уроке 1.3. Но если ты уже знаком с asyncio — это плюс.
❓ Можно ли использовать синхронный режим вместо async?
Да, aiosend поддерживает оба режима. Для простых скриптов и тестов удобен синхронный (cp.sync.get_me()), для Telegram-ботов и production — асинхронный.
❓ Сколько времени занимает курс?
При темпе 1 урок в день — примерно 6-8 недель. Можно быстрее (2 урока в день), но качество усвоения может снизиться.
❓ Нужен ли свой сервер для вебхуков?
Для изучения — нет, достаточно polling (опрос API). Для production — да, нужен сервер с HTTPS и публичным IP/доменом.
❓ Что если я застряну на задаче?
Не паникуй. Перечитай теорию, разбери примеры. Попробуй упростить задачу. Если ничего не помогает — напиши в Telegram-чат aiosend с описанием проблемы и кодом.
Что важно запомнить
Практическая задача
Задание: Изучить официальную документацию aiosend
Твоя задача — открыть официальную документацию aiosend и выполнить следующие шаги:
- Перейди на сайт aiosend.readthedocs.io и внимательно ознакомься со структурой документации.
- Найди раздел Installation — выпиши, какие 8 способов установки поддерживаются (минимум 5).
- Найди раздел API → Methods — выпиши все 12 методов, которые поддерживает aiosend. Для каждого кратко запиши, что он делает.
- Найди раздел API → Types — изучи структуру объекта App. Какие поля (атрибуты) у него есть? Запиши их названия.
- Найди раздел Client → Tools — выпиши дополнительные методы (tools), которые не входят в официальный API.
- Найди раздел Integration examples — посмотри пример интеграции с aiogram 3.x. Просто прочитай, не пытайся запустить.
- Создай текстовый файл
aiosend_overview.txtв папке проекта и запиши туда краткую сводку (10-15 предложений) о том, что ты узнал из документации.
Это задание не требует написания кода — оно приучает тебя работать с документацией. Умение читать документацию — важнейший навык программиста, возможно, даже важнее умения писать код. Удели этому заданию минимум 20-30 минут.
Урок 1.1: Как проходить курс
9 вопросов