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

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

> От API-ключа до пойманного webhook — за несколько минут

Этот гайд проведёт через полный цикл интеграции: получить API-ключ, подписать запрос,
создать депозит и поймать webhook об оплате. Все примеры используют реальную схему подписи,
проверенную против серверного гарда.

<Info>
  Базовый адрес в примерах — `https://wallet.your-exchange.com`. Замените его на base URL
  вашего инстанса (см. [Окружения](/environments)). Идентификатор ключа `api_id` в примерах —
  `pk_live_a1b2c3d4`, формат `orderId` — `order_1042`.
</Info>

<Steps>
  <Step title="Получите API-ключ">
    В личном кабинете создайте API-ключ для сайта. Вы получите пару:

    * `api_id` — публичный идентификатор ключа (уходит в заголовке `X-Api-Id`);
    * `api_secret` — секрет для подписи (показывается **один раз**, по сети не передаётся).

    Там же задайте `callback_url` (куда слать webhooks) и, при необходимости, белый список IP.

    <Warning>Сохраните `api_secret` в защищённом хранилище сразу. Повторно его показать
    нельзя — только перевыпустить (rotate), что сделает старый секрет недействительным.</Warning>
  </Step>

  <Step title="Соберите подпись">
    Каждый запрос подписывается `HMAC-SHA256`. Сообщение для подписи —
    `X-Timestamp + "." + raw_request_body`, ключ — ваш `api_secret`. Результат — строчный
    hex. Для запросов без тела (`GET`) тело — пустая строка, то есть сообщение принимает вид
    `"<timestamp>."` (timestamp, затем точка).

    <CodeGroup>
      ```javascript Node.js — хелпер подписи theme={null}
      import crypto from 'node:crypto';

      const BASE_URL  = 'https://wallet.your-exchange.com';
      const API_ID    = 'pk_live_a1b2c3d4';
      const API_SECRET = process.env.WALLET_API_SECRET; // никогда не хардкодьте

      function signedHeaders(body) {
        const ts  = Math.floor(Date.now() / 1000).toString();
        const raw = body ? JSON.stringify(body) : '';          // GET -> ''
        const signature = crypto
          .createHmac('sha256', API_SECRET)
          .update(`${ts}.${raw}`)                              // <ts>.<raw_body>
          .digest('hex');
        return {
          'X-Api-Id': API_ID,
          'X-Timestamp': ts,
          'X-Signature': signature,
          'Content-Type': 'application/json',
        };
      }
      ```

      ```bash cURL — подпись в shell theme={null}
      BASE_URL="https://wallet.your-exchange.com"
      API_ID="pk_live_a1b2c3d4"
      # API_SECRET берётся из окружения, в командную строку не пишем
      TS=$(date +%s)
      BODY='{"assetCode":"USDT_TRC20","orderId":"order_1042","expectedAmount":"100.50"}'
      SIG=$(printf '%s.%s' "$TS" "$BODY" \
        | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')
      ```
    </CodeGroup>

    Подробнее (Python, PHP, разбор ошибок подписи) — [Аутентификация](/authentication).
  </Step>

  <Step title="Создайте депозит">
    Вызовите `POST /v1/public/deposits`. В ответ придёт `uuid` депозита, адрес на оплату
    (`address`) и, для memo-сетей, `memo`.

    <CodeGroup>
      ```javascript Node.js theme={null}
      const body = {
        assetCode: 'USDT_TRC20',
        orderId: 'order_1042',
        expectedAmount: '100.50',
      };
      const res = await fetch(`${BASE_URL}/v1/public/deposits`, {
        method: 'POST',
        headers: signedHeaders(body),
        body: JSON.stringify(body), // те же байты, что подписали
      });
      const json = await res.json();
      if (!json.ok) throw new Error(`${json.error.code}: ${json.error.message}`);

      const { uuid, address, memo } = json.data;
      // address — адрес на оплату; memo — для memo-сетей (может быть null)
      ```

      ```bash cURL theme={null}
      curl -X POST "$BASE_URL/v1/public/deposits" \
        -H "X-Api-Id: $API_ID" \
        -H "X-Timestamp: $TS" \
        -H "X-Signature: $SIG" \
        -H "Content-Type: application/json" \
        -d "$BODY"
      ```
    </CodeGroup>

    ```json Ответ (пример) theme={null}
    {
      "ok": true,
      "data": {
        "uuid": "8f1c2e7a-2b1d-4c3e-9a5f-0c1d2e3f4a5b",
        "orderId": "order_1042",
        "assetCode": "USDT_TRC20",
        "network": "TRON",
        "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
        "memo": null,
        "status": "check"
      }
    }
    ```

    <Note>`orderId` и `expectedAmount` опциональны. Без `orderId` платформа сгенерирует
    уникальный. Если `expectedAmount` опущен — ожидаемой суммой становится минимум актива
    (`minDeposit`); чтобы принять любую сумму, передайте `expectedAmount: "0"`. Точный набор
    полей запроса и ответа — на странице [Депозиты](/deposits/overview).</Note>
  </Step>

  <Step title="Покажите адрес клиенту">
    Отобразите `data.address` (и `data.memo`, если он не `null`). Клиент отправляет крипту
    на этот адрес. Для memo-сетей оплата без указания memo не будет привязана к депозиту —
    выводите memo явно и заметно.
  </Step>

  <Step title="Поймайте оплату">
    **Webhook (рекомендуется).** Когда депозит подтверждён, платформа отправит на ваш
    `callback_url` событие `deposit.finalized`. Заголовок `X-Signature` webhook'а
    подписан вашим `callback_secret` — обязательно проверьте подпись. См.
    [Webhooks](/webhooks/overview).

    **Polling (запасной вариант).** Опросите статус депозита:
    `GET /v1/public/deposits/{uuid}` или
    `GET /v1/public/deposits/by-order-id/{orderId}`. Поле `status` дойдёт до `paid`,
    `paid_over` или `wrong_amount`. См. [Статусы депозитов](/deposits/statuses).

    ```bash cURL — проверка статуса (GET, тело пустое) theme={null}
    TS=$(date +%s)
    SIG=$(printf '%s.' "$TS" \
      | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')
    curl "$BASE_URL/v1/public/deposits/8f1c2e7a-2b1d-4c3e-9a5f-0c1d2e3f4a5b" \
      -H "X-Api-Id: $API_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"
    ```

    <Tip>Для GET-запроса тело пустое, поэтому подписывается строка `"<timestamp>."` —
    timestamp, затем точка.</Tip>
  </Step>
</Steps>

## Дальше

<CardGroup cols={2}>
  <Card title="Отправить выплату" icon="arrow-up" href="/payouts/overview" />

  <Card title="Валюты и сети" icon="coins" href="/currencies" />

  <Card title="Webhooks" icon="bell" href="/webhooks/overview" />

  <Card title="Коды ошибок" icon="triangle-exclamation" href="/errors" />
</CardGroup>