> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afkcrypto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

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)

## Сети

См. полный список в разделе [Поддерживаемые сети](/api-reference/supported-chains/). В поле `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`.

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

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

```json theme={null}
{
  "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` – Ошибка сервера

<Note>
  **Детали 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 помечен как неторгуемый вышестоящим провайдером, даже если пулы существуют в других местах.
</Note>

## Проверка

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

* 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.

## Связанные

<CardGroup cols={2}>
  <Card title="Поддерживаемые сети" icon="link-simple" href="/api-reference/supported-chains/" />

  <Card title="Политики и безопасность" icon="shield" href="/api-reference/policies-security/" />
</CardGroup>