Convert API

Convert API pozwala wymieniać waluty przechowywane w saldzie Twojego sklepu po aktualnej cenie rynkowej — ten sam mechanizm, który obsługuje zakładkę Swap w panelu sklepu, teraz dostępny z poziomu Twojego backendu.

Pobieranie wyceny konwersji

{
  "state": 0,
  "result": {
    "success": true,
    "from_currency": "BTC",
    "to_currency": "USDT",
    "amount_type": "from",
    "from_amount": "0.01000000",
    "to_amount": "947.86690000",
    "effective_rate": "94786.69000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87"
  }
}

curl -X POST https://api.2328.io/api/v1/convert/price \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Realizacja konwersji

{
  "state": 0,
  "result": {
    "id": 12345,
    "type": "manual",
    "status": "completed",
    "from_currency": "BTC",
    "to_currency": "USDT",
    "from_amount": "0.01000000",
    "requested_from_amount": "0.01000000",
    "refund_amount": null,
    "to_amount": "947.86690000",
    "exchange_rate": "94786.69000000",
    "fee_amount": "0.00000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87",
    "processed_at": "2026-01-20T15:30:24Z",
    "created_at": "2026-01-20T15:30:22Z"
  }
}

curl -X POST https://api.2328.io/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Błędy

W przypadku niepowodzenia odpowiedź ma state: 1 oraz error_code — wspólne dla /v1/convert/price i /v1/convert:

🔴 422 / 400 · application/json

{
  "state": 1,
  "error_code": "amount_too_small",
  "errors": {
    "amount": "Amount is too small for this conversion. Please increase the amount and try again."
  }
}

Automatyczna konwersja wpływających płatności

Auto-konwersja jest ustawieniem projektu dla wpływających faktur i kredytów w portfelach statycznych. Konfiguruje się ją w panelu sprzedawcy, a nie przez dodawanie pól do /v1/payment. Każda reguła wybiera jedną lub więcej walut źródłowych i walutę docelową.

Po zakończeniu konwersji informacje o płatności i webhooks sprzedawcy mogą obejmować:

{
  "payment_amount": "0.14800000",
  "merchant_amount": "0.146520000000000000",
  "payer_currency": "XMR",
  "convert": {
    "to_currency": "USDT",
    "commission": "0.09000000",
    "rate": "323.21000000",
    "amount": "47.262015740000000000"
  }
}

Zakresy kwot są celowo oddzielne:

• payment_amount — co zostało wykryte na łańcuchu w walucie płatności źródłowej;
• merchant_amount — netto kwota źródłowa przypisana sprzedawcy przed konwersją;
• convert.amount — kwota zaksięgowana w convert.to_currency;
• convert.rate i convert.commission — wynik wykonanej konwersji, a nie cena, którą powinieneś przeliczać lokalnie.

Nieudana automatyczna konwersja i przejście do

Konwersja następuje po otrzymaniu płatności w blockchain. Dostępność na rynku, minimalne wielkości zamówień, ograniczenia dokładności, limity czasowe wymiany i niewystarczająca wykonalna płynność mogą opóźnić lub uniemożliwić konwersję.

• Wpłaty poniżej minimalnej wartości globalnej/projektowej omijają proces konwersji i są księgowane w walucie źródłowej.
• Przejściowe awarie mogą być ponawiane asynchronicznie.
• Duże lub niehandlowalne wpłaty mogą zostać przepięte na kredyt w walucie źródłowej po wyczerpaniu polityki ponawiania.
• Płatność może być zatem ważna nawet wtedy, gdy żądana konwersja na walutę docelową nie nastąpiła.

Twoja integracja powinna najpierw zapisać zweryfikowaną płatność, a następnie uzgodnić faktycznie uznaną walutę z informacji o płatności, opcjonalnego bloku convert oraz sald handlowca. Nie blokuj potwierdzenia webhooka płatności podczas oczekiwania na własne systemy analityczne lub powiadomień.

Testy akceptacji automatycznej konwersji

Przetestuj co najmniej: pomyślna bezpośrednia konwersja, konwersja pośrednia/wieloetapowa, pył poniżej minimum, tymczasowa ponowna próba, powrót do waluty źródłowej, niedopłata, nadpłata, zduplikowany webhook, brak convert oraz uzgodnienie po niejednoznacznym przekroczeniu limitu czasu.

Ręczne przypadki krawędziowe konwersji

• /v1/convert/price to poglądowa wskazówka; ruchy na rynku mogą zmienić wynik wykonania.
• amount_type: from naprawia żądanie po stronie źródłowej, podczas gdy amount_type: to żąda kwoty po stronie docelowej. Nie zamieniaj znaczenia przy prezentowaniu interfejsu potwierdzenia.
• Para bez bezpośredniego rynku może być skierowana przez walutę pośrednią. Jeśli tylko jedna część zostanie zakończona, partially_completed raportuje kredyt pośredni.
• Jeśli wywołanie execute przekroczy limit czasu, przeprowadź uzgadnianie przed ponowną próbą. Zlecenie rynkowe może zostać zrealizowane nawet wtedy, gdy jego odpowiedź HTTP zostanie utracona.
• Traktuj failed jako stan do uzgodnienia, a nie jako pozwolenie na zastosowanie lokalnej wpisu kompensacyjnego; platforma zarządza księgowością debetów/zwrotów.