# Simply.Exchange API

Единая платформа: **фиатный checkout**, **рынок**, **торговля (NEX)** и **выпуск кастомных токенов**. Все внешние рельсы работают под капотом Simply — интегратор видит один домен `api.simply.exchange`.

**Базовый URL:** `https://api.simply.exchange`  
**Версия:** `v1`  
**Документация:** `GET /docs` · `GET /`

---

## Принципы white-label

| Принцип | Описание |
|---------|----------|
| Один API | Fiat, Market, Trade, Token sale — один хост |
| Секреты мерчанта | Только на сервере Simply (фиатный контур) |
| Торговля | Клиент подписывает ордера в кошельке; Simply проксирует в NEX |
| Бренд | Hosted checkout и KYC — в контуре Simply |

**Методы:** `GET` (market, docs), `POST` (операции), `DELETE` (отмена ордера).  
**CORS:** `*` для партнёрских доменов.

---

## Аутентификация

### Fiat / Token sale (сервер)

Ключи мерчанта хранятся в Simply. Браузер вызывает только `api.simply.exchange` без секретов.

### Trade (кошелёк / MM)

После логина в Simply Exchange передайте заголовки:

| Заголовок | Назначение |
|-----------|------------|
| `X-Simply-Wallet-Address` | Адрес торгового аккаунта |
| `X-Simply-Wallet-Token` | Сессионный токен после логина |
| `X-Simply-Trading-Key` | Альтернатива: торговый ключ (MM, без вывода) |
| `X-Simply-Company-Id` | ID партнёра (по умолчанию `1`) |
| `X-Simply-Partner-Domain` | White-label домен (например `simply.exchange`) |

### Webhook (фиат)

`POST /v1/fiat/webhook` — подпись:

- `X-Simply-Payload` (base64)
- `X-Simply-Signature` (HMAC-SHA512)

---

## 1. Fiat API

| Метод | Путь | Описание |
|--------|------|----------|
| `POST` | `/v1/fiat/context` | Страна, валюта, лимиты, каталоги |
| `POST` | `/v1/fiat/quote` | Котировка фиат → крипто |
| `POST` | `/v1/fiat/checkout-link` | Ссылка на Simply Checkout |
| `POST` | `/v1/fiat/order-status` | Статус сделки |
| `POST` | `/v1/fiat/webhook` | Входящие события оплаты |

**Пример context**

```json
{ "countryCode": "US" }
```

**Пример checkout-link**

```json
{
  "countryCode": "US",
  "fiatAmount": 100,
  "fiatType": 1,
  "coinCode": "usdt",
  "network": "bep20",
  "walletAddress": "0x…",
  "merchantRecognitionId": "order_123"
}
```

Ответ: `data.link` / `data.kycUrl` / `data.url`.

### Direct swap (в checkout)

Для партнёров доступен сценарий **direct swap**: пользователь платит фиатом, под капотом происходит своп/маршрутизация в целевой актив, и на кошелёк покупателя уходит **итоговый токен** одной выплатой.

- UI: Hosted checkout в Simply (`/app/buy.html`, `/app/buy-lite.html`) или ваш white-label.
- API: используется текущий Fiat/Token sale контур; отдельные публичные методы для swap будут опубликованы в этом же домене `api.simply.exchange` по мере включения у партнёра.

---

## 2. Market API

Публичные рыночные данные Simply Exchange.

| Метод | Путь | Параметры |
|--------|------|-----------|
| `GET` или `POST` | `/v1/market/price` | `symbol` |
| `GET` или `POST` | `/v1/market/depth` | `symbol`, `depth` |
| `GET` или `POST` | `/v1/market/last-trades` | `symbol` |
| `GET` или `POST` | `/v1/market/pair` | `symbol` |
| `GET` или `POST` | `/v1/market/symbols` | `mask` (опц.) |
| `GET` или `POST` | `/v1/market/history` | `symbol`, `interval`, `startTime`, `endTime` |
| `GET` | `/v1/market/time` | — |

**Пример price**

```http
GET /v1/market/price?symbol=hrpt_usdtbnb
```

```json
{
  "status": 1,
  "data": {
    "symbol": "hrpt_usdtbnb",
    "last": "…",
    "bid": "…",
    "ask": "…",
    "ts": 1710000000
  }
}
```

---

## 3. Trade API (NEX)

Торговля: ордера off-chain (без газа), балансы, депозиты, MM-ключи.  
Тело ордера — **подписанное сообщение** (`encoding`, `message`, `signature`), как в SDK Simply Exchange.

| Метод | Путь | Описание |
|--------|------|----------|
| `POST` | `/v1/trade/orders` | Создать ордер (`orderPayload`: `{ encoding, message, signature }`) |
| `POST` | `/v1/trade/orders/cancel` | Отменить ордер (`cancelPayload` для DELETE тела) |
| `POST` | `/v1/trade/orders/cancel-many` | Массовая отмена |
| `POST` | `/v1/trade/orders/list` | Список ордеров (`symbol`, `limit`, `status`, …) |
| `POST` | `/v1/trade/orders/get` | Ордер по `orderId` |
| `POST` | `/v1/trade/balances` | Балансы аккаунта |
| `POST` | `/v1/trade/fills` | Последние сделки по паре (`symbol`) |
| `POST` | `/v1/trade/deposits/prepare` | Справочники `chains` + `assets` для депозита |
| `POST` | `/v1/trade/keys/list` | Торговые ключи кошелька |

**Создание ордера**

```json
{
  "orderPayload": {
    "encoding": "hex",
    "message": "…",
    "signature": "…"
  }
}
```

Подпись формируется на стороне клиента (кошелёк / ваша обёртка SDK).

**WebSocket:** `wss://ws.simply.exchange` — стримы котировок и ордербука (выдаётся при онбординге Trade).

---

## 4. Token sale API

Фиат → settlement asset на казначейство → on-chain выплата токена покупателю.

| Метод | Путь |
|--------|------|
| `POST` | `/v1/token-sale/quote` |
| `POST` | `/v1/token-sale/checkout-link` |

**Quote**

```json
{
  "countryCode": "US",
  "fiatAmount": 100,
  "fiatType": 1,
  "paymentMethod": 1,
  "tokenRecipient": "0x…"
}
```

**Ответ**

```json
{
  "status": 1,
  "data": {
    "orderId": "hrpt_…",
    "validUntil": 1710000000000,
    "tokenOut": "1234.56",
    "estSettlementAmount": 15.2,
    "pricingSource": "simply_market_x_fiat",
    "flow": "fiat_to_settlement_then_token_payout"
  }
}
```

TTL котировки ~60 с. Затем `checkout-link` с тем же `orderId` и полями quote.

Webhook `merchantRecognitionId` = `orderId` → автоматическая выплата токена.

---

## Reference UI

| Страница | URL |
|----------|-----|
| Купить крипто | https://simply.exchange/app/buy.html |
| Lite | https://simply.exchange/app/buy-lite.html |
| Token sale (HRPT) | https://simply.exchange/app/buy-hrpt.html |

---

## Ошибки

| HTTP | `error` |
|------|---------|
| 400 | `invalid_json_body`, `invalid_token_recipient`, `quote_expired` |
| 401 | `trade_auth_required` |
| 404 | `not_found`, `order_unknown` |
| 502 | `fiat_quote_failed`, `market_unavailable`, `price_unavailable` |
| 500 | `configuration_error` |

---

## Онбординг

1. Чеклист эмитента (токен, казначейство, география, `symbol` пары).  
2. Webhook → `https://api.simply.exchange/v1/fiat/webhook`.  
3. Staging: quote → checkout → тестовая выплата.  
4. Trade: заголовки кошелька + подписанные ордера через `/v1/trade/*`.

---

## Совместимость

Устаревшие пути `/onramp/*` и `/exchange/hrpt-buy/*` временно поддерживаются. Новые интеграции — только **`/v1/*`**.

Май 2026.