# API: ресурс на адрес по ключу

> Заказ Energy и Bandwidth на любой адрес TRON из вашего кода: ключ API, котировка, заказ, статус.

Ваш код заказывает Energy и Bandwidth на любой адрес TRON тем же API, на котором работает кабинет. Заказ Direct держит
ресурс на адресе 1000 блоков (≈ 50 минут); цена фиксируется котировкой до заказа; оплата — с баланса организации.

| | |
|---|---|
| Адрес API | `https://cabinet-api.awesomefee.com/api/v1` |
| Ключ | заголовок `X-API-Key` или `Authorization: Bearer` с токеном OAuth |
| Организация | `org_…` в пути каждого запроса |
| Тела запросов и ответов | JSON |

## Шаг 0. В кабинете (человек, один раз)

1. Войдите в [кабинет](https://app.awesomefee.com/ru/app) и пополните баланс организации.
2. «API-ключи» → «Создать ключ». Для заказов нужно право `write`, для чтения — `read`. Секрет показывается один раз.
3. На том же экране — ID организации (`org_…`) и адрес API, у каждого кнопка копирования.

Передайте ключ и ID организации вашему коду (или ассистенту, который пишет код) как `KEY` и `ORG`.

**ИИ-агент без ключа** получает доступ по OAuth: он регистрируется с вашим email и показывает 6-значный код, вы вводите
код в кабинете и выбираете организацию и права. Приложения и MCP-клиенты используют authorization code с PKCE. Оба
способа описаны в [auth.md](/auth.md); доступ появляется среди ключей API с меткой «агент» и отзывается там же. Ключ
можно обменять на bearer-токен: `POST https://cabinet-api.awesomefee.com/api/v1/oauth/token` с `grant_type=client_credentials&client_secret=$KEY`.

## Шаг 1. Котировка

Цена объёма на 1000 блоков; котировка действует 30 секунд. `resource` — `ENERGY` или `BANDWIDTH`.

```bash
curl -s -X POST "https://cabinet-api.awesomefee.com/api/v1/orgs/$ORG/quotes" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","resource":"ENERGY","amount":65000}'
```

Ответ: `quote_id`, `price_sun` и `price_trx`, `available`, `expires_at`.

## Шаг 2. Заказ

Тело котировки плюс `quote_id`. Заголовок `Idempotency-Key` обязателен: повтор с тем же ключом возвращает тот же заказ
(`200`).

```bash
curl -s -X POST "https://cabinet-api.awesomefee.com/api/v1/orgs/$ORG/orders" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-11-16-0001" \
  -d '{"quote_id":"qt_…","address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","resource":"ENERGY","amount":65000}'
```

`202` — заказ принят: `order_id`, `status: ACCEPTED`.

## Шаг 3. Статус

```bash
curl -s "https://cabinet-api.awesomefee.com/api/v1/orgs/$ORG/orders/$ORDER" -H "X-API-Key: $KEY"
```

`ACCEPTED` → `PROVISIONING` → `DELIVERED`: ресурс на адресе, транзакция уходит без сжигания TRX. `PARTIAL` — доставлена
часть; `FAILED` — ничего не доставлено и не списано. Шаги заказа с txid: `GET /orgs/$ORG/orders/$ORDER/events`.

## Ресурс на ваших адресах всегда: Mate

Для постоянного потока адреса добавляются в Mate:

- `POST /orgs/{orgId}/addresses` — добавить адрес: `{"address":"T…","label":"payouts"}`;
- `PUT /orgs/{orgId}/addresses/{address}/scenario` — режим: `{"mode":"watch"}` или `{"mode":"serve"}`;
- `GET /orgs/{orgId}/addresses/{address}/usage` — расход по часам; `…/burns` — сожжённые TRX; `…/delegations` — наши
  делегации на адресе.

## Остальные вызовы по ключу

- `GET /orgs/{orgId}/orders` — заказы с фильтрами; `GET /orgs/{orgId}/orders/export.csv`.
- `GET /orgs/{orgId}/orders/{id}/reclaim-preview`, `POST /orgs/{orgId}/orders/{id}/reclaim` — досрочный возврат.
- `GET /orgs/{orgId}/balance`, `GET /orgs/{orgId}/balance/history`.
- `GET /tron/addresses/{address}/check`, `GET /tron/addresses/{address}/preview` — любой адрес: формат, активация,
  живые ресурсы, сожжённые за 24 ч TRX.
- `GET /orgs/{orgId}/api-limits`, `GET /orgs/{orgId}/api-usage` — лимиты и использование ключа.

## Ошибки

Ошибка — JSON `{"error":"<сообщение>","code":"<КОД>"}` с HTTP-статусом:

| Статус | Коды |
|---|---|
| 400 | `VALIDATION_ERROR`, `INVALID_ADDRESS`, `AMOUNT_BELOW_MIN`, `DURATION_FIXED` (Direct — только 1000 блоков) |
| 401 | нет ключа, ключ отозван или истёк |
| 402 | `INSUFFICIENT_BALANCE` |
| 403 | `FORBIDDEN_ROLE` (права ключа), `ADDRESS_NOT_ALLOWED` |
| 409 | `QUOTE_EXPIRED`, `IDEMPOTENCY_CONFLICT`, `NOT_RECLAIMABLE` |
| 429 | лимит ключа; подождите `Retry-After` |
| 503 | `NO_CAPACITY`, `UPSTREAM_UNAVAILABLE`; повторите через `Retry-After` |

Без аккаунта, с оплатой каждого вызова в USDC: [ИИ-агенты и x402](/docs/ru/agents/overview/).
