Convert API

La Convert API ti permette di scambiare le valute detenute nel saldo del tuo negozio al prezzo di mercato attuale — lo stesso motore che alimenta la scheda Swap nella dashboard del negozio, ora richiamabile dal tuo backend.

Ottenere una quotazione di conversione

{
  "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"

Eseguire una conversione

{
  "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"

Errori

In caso di errore, la risposta ha state: 1 e un error_code — condiviso da /v1/convert/price e /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."
  }
}

Conversione automatica dei pagamenti in arrivo

La conversione automatica è un'impostazione del progetto per le fatture in arrivo e i crediti del portafoglio statico. Viene configurata nel cruscotto del commerciante, non aggiungendo campi a /v1/payment. Ogni regola seleziona una o più valute di origine e una valuta di destinazione.

Al termine della conversione, le informazioni sul pagamento e i webhook del commerciante possono includere:

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

I domini dell'importo sono intenzionalmente separati:

• payment_amount — quanto è stato rilevato on-chain nella valuta di pagamento di origine;
• merchant_amount — l'importo netto di origine attribuibile al commerciante prima della conversione;
• convert.amount — l'importo accreditato in convert.to_currency;
• convert.rate e convert.commission — il risultato della conversione eseguita, non un prezzo che dovresti ricalcolare localmente.

Errore di conversione automatica e fallback

La conversione avviene a valle della ricezione del pagamento in blockchain. La disponibilità di mercato, le quantità minime d'ordine, i limiti di precisione, i timeout degli exchange e la liquidità eseguibile insufficiente possono ritardare o impedire la conversione.

• I depositi al di sotto del minimo globale o del progetto bypassano il flusso di conversione e accreditano la valuta di origine.
• I guasti transitori possono essere riprovati in modo asincrono.
• Depositi grandi o non commerciabili possono ritornare a un credito nella valuta di origine dopo che la politica di ritentativo è esaurita.
• Un pagamento può quindi essere valido anche quando la conversione nella valuta desiderata non è avvenuta.

La tua integrazione dovrebbe prima memorizzare il pagamento verificato, quindi riconciliare la valuta effettivamente accreditata dalle informazioni sul pagamento, dal blocco opzionale convert e dai saldi del commerciante. Non bloccare il riconoscimento del webhook del pagamento mentre si attendono i tuoi sistemi di analisi o notifiche.

Test di accettazione della conversione automatica

Testare almeno: conversione diretta riuscita, conversione tramite ponte/multi-hop, polvere sotto il minimo, tentativo transitorio, ritorno alla valuta di origine, sotto pagamento, sovrapagamento, webhook duplicato, convert mancante e riconciliazione dopo un timeout ambiguo.

Casi limite di conversione manuale

• /v1/convert/price è un'anteprima indicativa; il movimento del mercato può cambiare il risultato dell'esecuzione.
• amount_type: from fissa la richiesta lato sorgente, mentre amount_type: to richiede un importo lato destinazione. Non invertire il significato durante la presentazione dell'interfaccia di conferma.
• Una coppia senza un mercato diretto può essere instradata attraverso una valuta intermedia. Se viene completata solo una fase, partially_completed segnala il credito intermedio.
• Se una chiamata execute scade, riconciliare prima di riprovare. Un ordine di mercato può essere eseguito anche quando la sua risposta HTTP va persa.
• Trattare failed come uno stato da riconciliare, non come permesso di applicare una registrazione contabile compensativa locale; la piattaforma possiede la contabilità di addebito/rimborso.