Convert API

Convert API를 사용하면 가맹점 잔액에 보유한 통화 간에 현재 시장 가격으로 환전할 수 있습니다 — 가맹점 대시보드의 환전(Swap) 탭을 구동하는 것과 동일한 엔진을 이제 백엔드에서 직접 호출할 수 있습니다.

환전 견적 조회

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

환전 실행

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

오류

실패 시 응답에는 state: 1과 error_code가 포함됩니다 — /v1/convert/price와 /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."
  }
}

들어오는 결제의 자동 변환

자동 변환은 들어오는 청구서 및 고정 지갑 크레딧에 대한 프로젝트 설정입니다. 이는 /v1/payment에 필드를 추가하여 구성하는 것이 아니라, 상인 대시보드에서 구성됩니다. 각 규칙은 하나 이상의 원본 통화와 목표 통화를 선택합니다.

변환이 완료되면, 결제 정보와 상인 웹훅에 다음이 포함될 수 있습니다:

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

금액 도메인은 의도적으로 분리되어 있습니다:

• payment_amount — 원본 결제 통화에서 온체인으로 감지된 금액;
• merchant_amount — 변환 전 상인에게 귀속되는 순 원본 금액;
• convert.amount — convert.to_currency에 크레딧된 금액;
• convert.rate 및 convert.commission — 실행된 변환 결과로, 로컬에서 다시 계산해야 하는 가격이 아닙니다.

자동 변환 실패 및 대체

변환은 블록체인 결제 수신 이후에 이루어집니다. 시장 가용성, 최소 주문 크기, 정밀도 제한, 거래소 시간 초과, 실행 가능한 유동성 부족 등으로 인해 변환이 지연되거나 불가능할 수 있습니다.

• 글로벌/프로젝트 최소 금액 이하의 입금은 변환 파이프라인을 우회하고 소스 통화로 크레딧됩니다.
• 일시적인 실패는 비동기적으로 재시도할 수 있습니다.
• 크거나 거래할 수 없는 예금은 재시도 정책이 소진된 후 원화 신용으로 되돌아갈 수 있습니다.
• 따라서 원하는 대상 통화 변환이 발생하지 않았더라도 결제는 유효할 수 있습니다.

통합 시 검증된 결제를 먼저 저장한 다음, 결제 정보, 선택적 convert 블록, 상인 잔액에서 실제로 적립된 통화를 조정해야 합니다. 자체 분석 또는 알림 시스템을 기다리는 동안 결제 웹후크의 확인을 차단하지 마십시오.

자동 변환 승인 테스트

적어도 다음을 테스트하십시오: 성공적인 직접 변환, 브리지/멀티 홉 변환, 최소값 이하의 먼지, 일시적 재시도, 소스 통화로의 대체, 부족지불, 초과지불, 중복 웹훅, 누락된 convert, 모호한 시간 초과 후의 조정.

수동 변환 엣지 케이스

• /v1/convert/price는 예시 미리보기이며, 시장 움직임에 따라 실행 결과가 변경될 수 있습니다.
• amount_type: from는 소스 측 요청을 수정하고, amount_type: to는 대상 측 금액을 요청합니다. 확인 UI를 표시할 때 의미를 바꾸지 마십시오.
• 직접 시장이 없는 페어는 중간 통화를 통해 라우팅할 수 있습니다. 한쪽만 완료되면 partially_completed는 중간 크레딧을 보고합니다.
• 실행 호출이 시간 초과되면 재시도하기 전에 조정하십시오. HTTP 응답이 손실되더라도 시장 주문은 실행될 수 있습니다.
• failed를 로컬 보상 잔액 항목을 적용할 권한으로가 아니라 조정할 상태로 취급하십시오; 플랫폼이 차변/환불 회계를 소유합니다.