Convert API

Med Convert API kan du växla mellan valutorna som finns i ditt handlarsaldo till aktuellt marknadspris — samma motor som driver fliken Swap i handlarens instrumentpanel, nu åtkomlig från din backend.

Hämta konverteringskurs

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

Utföra konvertering

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

Fel

Vid ett fel har svaret state: 1 och en error_code — delad av /v1/convert/price och /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."
  }
}

Automatisk konvertering av inkommande betalningar

Auto-konvertering är en projektinställning för inkommande fakturor och statiska plånbokskrediter. Den konfigureras i handlarens instrumentpanel, inte genom att lägga till fält i /v1/payment. Varje regel väljer en eller flera källvalutor och en målvaluta.

När konverteringen är klar kan betalningsinformation och handlar-webhooks inkludera:

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

Beloppsområdena är avsiktligt separata:

• payment_amount — vad som upptäcktes på kedjan i källbetalningsvalutan;
• merchant_amount — nettokällbeloppet som tillfaller handlaren före konvertering;
• convert.amount — beloppet som krediterats i convert.to_currency;
• convert.rate och convert.commission — det utförda konverteringsresultatet, inte ett pris du bör räkna om lokalt.

Automatisk konverteringsfel och fallback

Konvertering sker efter mottagande av blockchain-betalningen. Marknadstillgänglighet, minsta orderstorlekar, precisionbegränsningar, utbytes-timeouter och otillräcklig verkställbar likviditet kan fördröja eller förhindra konvertering.

• Insättningar under global/projektminimum kringgår konverteringsflödet och krediteras i källvaluta.
• Tillfälliga fel kan försökas igen asynkront.
• Stora eller icke-handelsbara insättningar kan återgå till ett källvalutakredit efter att återförsökspolicyn är uttömd.
• En betalning kan därför vara giltig även när den önskade målvalutakonverteringen inte genomfördes.

Din integration bör först spara den verifierade betalningen, och sedan stämma av den faktiska krediterade valutan från betalningsinformationen, den valfria convert-blocket och handlarens saldon. Blockera inte bekräftelsen av betalningswebhooken medan du väntar på dina egna analys- eller notificationssystem.

Automatiserade konverteringstest av godkännande

Testa åtminstone: lyckad direktkonvertering, bro-/flerstegs-konvertering, damm under minimum, tillfällig omförsök, återfall till källvaluta, underbetalning, överbetalning, duplicerat webhook, saknad convert och avstämning efter en tvetydig timeout.

Manuella konverteringskantfall

• /v1/convert/price är en indikativ förhandsvisning; marknadsrörelser kan ändra utfallet av exekveringen.
• amount_type: from fixar källsidans begäran, medan amount_type: to begär ett målbelopp. Byt inte betydelse vid presentation av bekräftelsegränssnitt.
• Ett par utan direkt marknad kan routas genom en mellanliggande valuta. Om endast ett ben slutförs, rapporterar partially_completed den mellanliggande krediten.
• Om ett execute-anrop överstiger tiden, förlikna innan du försöker igen. En marknadsorder kan genomföras även när dess HTTP-svar förloras.
• Behandla failed som ett tillstånd att förlikna, inte som tillåtelse att göra en lokal kompensationsbalanspost; plattformen äger debet-/återbetalningsredovisningen.