Перейти к основному содержанию

​
title: ‘AFK API v1’ description: ‘AFK Crypto — API автоматизации некастодиальных кошельков’

​
Обзор

  • Базовый путь: /api/v1
  • Аутентификация: ключ API через заголовок x-api-key
  • Идемпотентность: write‑эндпоинты требуют заголовок Idempotency-Key (UUID)
  • Формат ответа: все ответы включают заголовок x-request-id для трассировки

​
Эндпоинты

  • GET /api/v1/wallets – Список кошельков пользователя
  • GET /api/v1/wallets/balances – Баланс кошелька вызывающего (по сети; используется кошелёк по умолчанию)
  • GET /api/v1/wallets/:address/balances – Баланс для конкретного принадлежащего адреса кошелька
  • GET /api/v1/tx/:id – Детали транзакции
  • POST /api/v1/send – Отправка нативных активов и токенов (EVM + Solana)
  • POST /api/v1/token/approve – Одобрение токенов ERC20 (только EVM)
  • POST /api/v1/contracts/send – Общая интеракция с контрактами (только EVM)
  • POST /api/v1/trade/quote – Котировки свапов (EVM + Solana)
  • POST /api/v1/trade/swap – Выполнение свапов (EVM + Solana)

​
Сети

См. полный список в разделе Поддерживаемые сети. В поле chain используйте slug (например, base, solana-devnet).

​
Лимитирование

  • Запись (включая POST /api/v1/trade/quote): 15 запросов в минуту на пользователя
  • Чтение: 60 запросов в минуту на пользователя
  • Ответ: HTTP 429 при превышении
  • Заголовки: Retry-After (секунды до следующего окна)

​
Идемпотентность (write)

  • Все изменяющие эндпоинты требуют Idempotency-Key.
  • Повтор с тем же телом возвращает исходный ответ 200.
  • Повтор с другим телом возвращает HTTP 409 с code: IDEMPOTENT_BODY_MISMATCH.
  • Повтор без сохранённого успешного ответа возвращает HTTP 409 с code: IDEMPOTENT_REPLAY.
  • Ключи ограничены аутентифицированным пользователем; путь эндпоинта записывается для трассировки.
  • Применяется к: POST /api/v1/send, POST /api/v1/token/approve, POST /api/v1/contracts/send, POST /api/v1/trade/swap.

​
Обработка ошибок

​
Формат ответа об ошибке

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}

​
Коды ошибок

  • UNAUTHORIZED – Отсутствует/неверная аутентификация или API-ключ (HTTP 401)
  • FORBIDDEN – Аутентифицирован, но не имеет разрешения на действие (HTTP 403)
  • NOT_FOUND – Ресурс не найден (HTTP 404)
  • RATE_LIMITED – Превышен лимит запросов (HTTP 429)
  • INVALID_INPUT – Недопустимые параметры запроса (HTTP 400)
  • WALLET_NOT_FOUND – Указанный кошелёк не найден
  • USER_NOT_LINKED – Пользователь не привязан к Privy
  • WALLET_NOT_DELEGATED – Кошелёк не делегирован серверному подписанту
  • WALLET_ID_REQUIRED – Отсутствует ID кошелька Privy
  • CHAIN_UNKNOWN – Неизвестная или неподдерживаемая сеть
  • INSUFFICIENT_FUNDS – У отправителя недостаточно средств для значения/комиссии
  • IDEMPOTENT_BODY_MISMATCH – Другое тело запроса с тем же ключом идемпотентности (HTTP 409)
  • IDEMPOTENT_REPLAY – Ключ идемпотентности уже использован (HTTP 409)
  • PRIVY_RPC_ERROR – Ошибка сервиса Privy RPC
  • SEND_FAILED – Не удалось отправить транзакцию
  • SERVICE_UNAVAILABLE – Необходимый сервис не настроен
  • QUOTE_FAILED – Ошибка сервиса котировок (HTTP 400)
  • INTERNAL_ERROR – Ошибка сервера
Детали QUOTE_FAILED:
  • Solana/Jupiter: Некоторые mint Solana не торгуются на Jupiter (кураторский список). В таких случаях API возвращает HTTP 400 с code: QUOTE_FAILED и сообщением об ошибке вроде: “Token not tradable on Jupiter”.
  • EVM/1inch: Если токен не поддерживается 1inch, API возвращает HTTP 400 с code: QUOTE_FAILED и сообщением вроде: “Token not tradable on 1inch”.
  • Это ожидаемое поведение, когда запрошенный выходной токен/mint помечен как неторгуемый вышестоящим провайдером, даже если пулы существуют в других местах.

​
Проверка

​
Форматы адресов

  • EVM: must match /^0x[a-fA-F0-9]{40}$/
  • Solana: must be a valid base58 public key

​
Общие параметры

  • Суммы (EVM): Только целочисленные строки (десятичные или 0x-hex). Должны быть неотрицательными. Для ERC20 и value должны помещаться в uint256.
  • Суммы (Solana): Целочисленные строки в базовых единицах. Суммы SPL должны помещаться в беззнаковый 64-битный диапазон.
  • Отправитель (from): Опционально. Если опущен, используется кошелёк пользователя по умолчанию для указанной сети.
  • Идемпотентность: Все эндпоинты записи требуют заголовок Idempotency-Key. Повторы с тем же телом возвращают исходный ответ.

​
Ключевое слово нативного токена

Торговые эндпоинты (/api/v1/trade/quote, /api/v1/trade/swap) принимают регистронезависимое ключевое слово NATIVE для fromToken/toToken:
  • EVM: NATIVE разрешается в 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
  • Solana: NATIVE разрешается в обёрнутый SOL mint So11111111111111111111111111111111111111112
  • Ответы возвращают разрешённые адреса (не NATIVE)
  • Эндпоинт отправки использует asset: "native" вместо адресов токенов для нативных переводов

​
Конвенции

  • Выбор сети: используйте slug chain (например, base, base-sepolia, solana-devnet).
  • Сопоставление‑сентинел Transaction.chainId в Solana: 0 = mainnet, -2 = testnet, -3 = devnet.
  • Идемпотентность: unique per user and key; repeats return the original response; mismatched bodies → 409.

​
Связанные

Поддерживаемые сети

Политики и безопасность