# Convert API

> अपने मर्चेंट बैलेंस से सीधे क्रिप्टोकरेंसी कन्वर्ट करें — लाइव प्राइस पाएं और मार्केट प्राइस पर एक्ज़िक्यूट करें।

Convert API आपको आपके मर्चेंट बैलेंस में मौजूद करेंसी के बीच वर्तमान मार्केट प्राइस पर एक्सचेंज करने देता है — वही इंजन जो मर्चेंट डैशबोर्ड के **Swap** टैब को चलाता है, अब आपके बैकएंड से कॉल किया जा सकता है।

> **WARNING:** Convert एंडपॉइंट्स आपकी **सामान्य API key** से साइन किए जाते हैं — वही key जो [Payment API](/docs/payments) रिक्वेस्ट के लिए इस्तेमाल होती है, Payout API key **नहीं**। कन्वर्ट को एक्ज़िक्यूट करने से आपका मर्चेंट बैलेंस तुरंत डेबिट और क्रेडिट हो जाता है, इसलिए इस key को उतनी ही सावधानी से संभालें जितनी किसी भी पैसा हिलाने वाली क्रेडेंशियल को।

## कन्वर्जन प्राइस पाना

वर्तमान मार्केट प्राइस पर एक कन्वर्जन के लिए एक इंडिकेटिव प्राइस देता है — इफेक्टिव रेट और परिणामी राशियाँ। कुछ भी डेबिट या रिज़र्व नहीं होता; एक्ज़िक्यूट करने से पहले जितनी बार चाहें कॉल करें।

`POST /v1/convert/price`

### रिक्वेस्ट पैरामीटर

| फ़ील्ड | टाइप | आवश्यक | विवरण | मान |
|--------|------|--------|-------|-----|
| `from_currency` | string | हाँ | सोर्स करेंसी | `BTC`, `ETH`, `USDT`, `USDC`, `TRX`, `BNB`, `GRAM`, `SOL`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `to_currency` | string | हाँ | टारगेट करेंसी। `from_currency` से अलग होनी चाहिए | `USDT`, `USDC`, `BTC`, `ETH`, `TRX`, `BNB`, `GRAM`, `SOL`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `amount` | decimal | हाँ | कन्वर्ट की जाने वाली राशि, `0` से अधिक |  |
| `amount_type` | string | हाँ | `amount` किस पक्ष को दर्शाता है | `from`, `to` |

> **INFO:** `amount_type=from` में ठीक `amount` जितनी `from_currency` खर्च होती है। `amount_type=to` में ठीक `amount` जितनी `to_currency` प्राप्त होती है।

**🟢 200 OK** · `application/json`

```json
{
  "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"
  }
}
```

#### रिस्पॉन्स फ़ील्ड्स

| फ़ील्ड | टाइप | विवरण |
|--------|------|-------|
| `success` | boolean | क्या प्राइस सफलतापूर्वक कैलकुलेट हुआ |
| `from_currency` | string | सोर्स करेंसी |
| `to_currency` | string | टारगेट करेंसी |
| `amount_type` | string | रिक्वेस्ट के `amount_type` को दोहराता है |
| `from_amount` | string | जो राशि `from_currency` में डेबिट होगी |
| `to_amount` | string | जो राशि `to_currency` में क्रेडिट होगी |
| `effective_rate` | string | इस प्राइस पर लागू रेट — `from_currency` की 1 यूनिट, `to_currency` में (इसमें पहले से ही प्लेटफ़ॉर्म की प्राइसिंग शामिल है) |
| `from_amount_usd` | string \| null | `from_amount` का USD समतुल्य |
| `to_amount_usd` | string \| null | `to_amount` का USD समतुल्य |

- यह प्राइस **केवल इंडिकेटिव** है — प्राइस लेने और एक्ज़िक्यूट करने के बीच मार्केट प्राइस बदल सकता है।
- यह कॉल किसी भी बैलेंस को डेबिट या रिज़र्व नहीं करती।

> Use your project UUID and the endpoint-appropriate API key from the merchant dashboard.

#### Interactive request: `POST /v1/convert/price`
  - `from_currency` (enum, required): BTC,ETH,USDT,USDC,TRX,BNB,GRAM,SOL,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `to_currency` (enum, required): USDT,USDC,BTC,ETH,TRX,BNB,GRAM,SOL,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `amount` (decimal, required)
  - `amount_type` (enum, required): from,to

## कन्वर्ट एक्ज़िक्यूट करना

वर्तमान मार्केट प्राइस पर एक कन्वर्जन एक्ज़िक्यूट करता है और आपका मर्चेंट बैलेंस अपडेट करता है। "प्राइस कन्फर्म करने" का कोई अलग स्टेप नहीं है — जिस राशि को कन्वर्ट करना है उसके साथ सीधे इस एंडपॉइंट को कॉल करें।

`POST /v1/convert`

> **INFO:** **आइडेम्पोटेंसी।** पहली कॉल के लगभग एक मिनट के अंदर बिल्कुल वही रिक्वेस्ट (वही `from_currency`, `to_currency`, `amount`, `amount_type`) दोहराने पर दूसरा कन्वर्जन बनाने के बजाय मौजूदा कन्वर्जन वापस मिलता है। इस समय-सीमा के बाद, वही रिक्वेस्ट एक नए कन्वर्जन के रूप में माना जाएगा — टाइमआउट पर बिना पिछला रिज़ल्ट चेक किए अंधाधुंध दोबारा कोशिश न करें।

> **WARNING:** यह एंडपॉइंट प्रति कॉलर **प्रति मिनट 10 रिक्वेस्ट** तक सीमित है — सामान्य API रेट लिमिट से सख्त — क्योंकि हर कॉल असली बैलेंस हिलाती है।

### रिक्वेस्ट पैरामीटर

| फ़ील्ड | टाइप | आवश्यक | विवरण | मान |
|--------|------|--------|-------|-----|
| `from_currency` | string | हाँ | सोर्स करेंसी | `BTC`, `ETH`, `USDT`, `USDC`, `TRX`, `BNB`, `GRAM`, `SOL`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `to_currency` | string | हाँ | टारगेट करेंसी। `from_currency` से अलग होनी चाहिए | `USDT`, `USDC`, `BTC`, `ETH`, `TRX`, `BNB`, `GRAM`, `SOL`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `amount` | decimal | हाँ | कन्वर्ट की जाने वाली राशि, `0` से अधिक |  |
| `amount_type` | string | हाँ | `amount` किस पक्ष को दर्शाता है | `from`, `to` |

**🟢 200 OK** · `application/json`

```json
{
  "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"
  }
}
```

#### रिस्पॉन्स फ़ील्ड्स

| फ़ील्ड | टाइप | विवरण |
|--------|------|-------|
| `id` | int | सिस्टम द्वारा दिया गया कन्वर्ट ऑर्डर ID |
| `type` | string | इस API के लिए हमेशा `manual` |
| `status` | string | वर्तमान स्टेटस (नीचे «कन्वर्ट स्टेटस» देखें) |
| `from_currency` | string | सोर्स करेंसी |
| `to_currency` | string | टारगेट करेंसी |
| `from_amount` | string | `from_currency` में डेबिट की गई राशि |
| `requested_from_amount` | string \| null | `amount_type = from` होने पर आपकी मूल रूप से अनुरोधित सोर्स राशि। `amount_type = to` होने पर `null` |
| `refund_amount` | string \| null | आंशिक निष्पादन के बाद आपको वापस की गई पूर्व-डेबिट राशि का हिस्सा। यदि ऑर्डर पूरी तरह पूरा हुआ तो `null` |
| `to_amount` | string | `to_currency` में क्रेडिट की गई राशि |
| `exchange_rate` | string | इस कन्वर्जन पर वास्तव में लागू की गई रेट — `from_currency` की 1 यूनिट, `to_currency` में (इसमें पहले से ही प्लेटफ़ॉर्म की प्राइसिंग शामिल है) |
| `fee_amount` | string | इस कन्वर्जन पर लिया गया प्लेटफ़ॉर्म फ़ीस, ट्रेड की दिशा के अनुसार `from_currency` या `to_currency` में। यह पहले से ही `exchange_rate` में शामिल है — पारदर्शिता के लिए दिखाया गया है |
| `from_amount_usd` | string \| null | `from_amount` का USD समतुल्य |
| `to_amount_usd` | string \| null | `to_amount` का USD समतुल्य |
| `processed_at` | string (ISO 8601) \| null | जब कन्वर्जन का निष्पादन पूरा हुआ। प्रोसेस होते समय `null` |
| `created_at` | string (ISO 8601) | जब कन्वर्ट ऑर्डर बनाया गया |

#### कन्वर्ट स्टेटस

| स्टेटस | विवरण |
|--------|-------|
| `pending` | बनाया गया, अभी तक मार्केट में नहीं भेजा गया |
| `processing` | बैलेंस लॉक किया गया, ऑर्डर मार्केट में रखा गया |
| `completed` | पूरी तरह एक्ज़िक्यूट हुआ — `to_amount` आपके बैलेंस में क्रेडिट हो चुका है |
| `failed` | एक्ज़िक्यूट नहीं हो सका — पहले डेबिट की गई कोई भी राशि अपने आप रिफ़ंड कर दी गई |
| `partially_completed` | केवल उन करेंसी पेयर्स के लिए जिनका कोई डायरेक्ट मार्केट नहीं है (एक इंटरमीडिएट करेंसी के ज़रिए रूट किया गया): पहला चरण पूरा हुआ लेकिन दूसरा विफल रहा। आपको `to_currency` की बजाय इंटरमीडिएट करेंसी क्रेडिट की जाती है — अपने मूल लक्ष्य तक पहुँचने के लिए वहाँ से फिर से कन्वर्ट करें |

#### Interactive request: `POST /v1/convert`
  - `from_currency` (enum, required): BTC,ETH,USDT,USDC,TRX,BNB,GRAM,SOL,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `to_currency` (enum, required): USDT,USDC,BTC,ETH,TRX,BNB,GRAM,SOL,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `amount` (decimal, required)
  - `amount_type` (enum, required): from,to

## एरर

विफल होने पर, रिस्पॉन्स में `state: 1` और एक `error_code` होता है — `/v1/convert/price` और `/v1/convert` दोनों में समान:

**🔴 422 / 400** · `application/json`

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

| `error_code` | HTTP स्टेटस | विवरण |
|--------------|-------------|-------|
| `validation_failed` | 422 | अमान्य या गुम पैरामीटर, या किसी बिज़नेस रूल के कारण अस्वीकृति (जैसे अपर्याप्त बैलेंस) — विवरण के लिए `errors` फ़ील्ड देखें |
| `amount_too_small` | 422 | `amount` इस करेंसी पेयर के लिए न्यूनतम ट्रेड योग्य साइज़ से कम है |
| `convert_unavailable` | 400 | अभी कन्वर्जन एक्ज़िक्यूट नहीं किया जा सका (मार्केट डेटा उपलब्ध नहीं है या दोनों करेंसी के बीच कोई रूट नहीं है) — कृपया थोड़ी देर बाद फिर से कोशिश करें |
| `internal_error` | 400 | रिक्वेस्ट प्रोसेस करते समय एक अप्रत्याशित इंटरनल सर्वर एरर हुआ |

## आगमन भुगतान का स्वचालित रूपांतरण

स्वचलित रूपांतरण इनकमिंग इनवॉइस और स्टेटिक-वॉलेट क्रेडिट्स के लिए एक परियोजना सेटिंग है। इसे मर्चेंट डैशबोर्ड में कॉन्फ़िगर किया जाता है, न कि `/v1/payment` में फ़ील्ड जोड़कर। प्रत्येक नियम एक या अधिक स्रोत मुद्राओं और एक लक्ष्य मुद्रा का चयन करता है।

जब रूपांतरण पूरा हो जाता है, तो भुगतान जानकारी और मर्चेंट वेबहुक्स में शामिल किया जा सकता है:

```json
{
  "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` — निष्पादित रूपांतरण परिणाम, कोई मूल्य नहीं जिसे आपको स्थानीय रूप से पुनः गणना करनी चाहिए।

> **WARNING:** `convert` की अनुपस्थिति अर्थपूर्ण है: रूपांतरण पूरा नहीं हुआ हो सकता है, उस स्रोत के लिए कॉन्फ़िगर नहीं किया गया हो सकता है, या स्रोत-मुद्रा क्रेडिट पर लौट गया हो सकता है। कभी भी `/exchange-rates` या सार्वजनिक बाजार मूल्य से लक्ष्य राशि की कल्पना न करें।

### ऑटो-कन्वर्ट विफलता और फॉलबैक

रूपांतरण ब्लॉकचेन भुगतान प्राप्त करने के बाद डाउनस्ट्रीम होता है। बाजार की उपलब्धता, न्यूनतम आदेश आकार, सटीकता सीमा, एक्सचेंज समय समाप्ति और अपर्याप्त निष्पादन योग्य तरलता रूपांतरण को विलंबित या अवरुद्ध कर सकते हैं।

- वैश्विक/परियोजना न्यूनतम से कम जमा राशि रूपांतरण पाइपलाइन को बाइपास करती है और स्रोत मुद्रा को क्रेडिट करती है।
- अल्पकालिक असफलताओं को असिंक्रोनस रूप से दोबारा प्रयास किया जा सकता है।
- बड़ी या गैर-व्यापारी योग्य जमा राशि को दोबारा प्रयास नीति समाप्त होने के बाद स्रोत-मुद्रा क्रेडिट में बदल दिया जा सकता है।
- इसलिए एक भुगतान मान्य हो सकता है भले ही इच्छित लक्ष्य-मुद्रा रूपांतरण नहीं हुआ हो।

आपका एकीकरण पहले सत्यापित भुगतान को सुरक्षित रूप से रखे, फिर भुगतान जानकारी, वैकल्पिक `convert` ब्लॉक, और व्यापारी बैलेंस से वास्तविक क्रेडिट की गई मुद्रा का मिलान करे। अपने खुद के विश्लेषण या सूचना प्रणालियों पर इंतजार करते समय भुगतान वेबहुक की स्वीकृति को अवरुद्ध न करें।

### ऑटो-कन्वर्ट स्वीकृति परीक्षण

कम से कम परीक्षण करें: सफल डायरेक्ट कन्वर्शन, ब्रिज/मल्टी-हॉप कन्वर्शन, न्यूनतम से नीचे धूल, अस्थायी पुनः प्रयास, स्रोत मुद्रा पर फॉलबैक, अत्यल्प भुगतान, अधिक भुगतान, डुप्लिकेट वेबहुक, गायब `convert`, और अस्पष्ट टाइमआउट के बाद सामंजस्य।

## मैनुअल कन्वर्शन एज केस

- `/v1/convert/price` एक संकेतक पूर्वावलोकन है; बाजार की गति निष्पादन परिणाम बदल सकती है।
- `amount_type: from` स्रोत-पक्ष का अनुरोध ठीक करता है, जबकि `amount_type: to` लक्ष्य-पक्ष की राशि का अनुरोध करता है। पुष्टि UI प्रस्तुत करते समय अर्थ को बदलें नहीं।
- एक जोड़ी जिसके पास डायरेक्ट मार्केट नहीं है, उसे मध्यवर्ती मुद्रा के माध्यम से मार्गित किया जा सकता है। यदि केवल एक लेग पूरा होता है, तो `partially_completed` मध्यवर्ती क्रेडिट की रिपोर्ट करता है।
- यदि एक execute कॉल समय समाप्त हो जाता है, तो पुनः प्रयास करने से पहले मेल करें। एक मार्केट ऑर्डर तब भी निष्पादित हो सकता है जब इसका HTTP उत्तर खो गया हो।
- `failed` को मिलान करने की स्थिति के रूप में मानें, स्थानीय मुआवजा बैलेंस एंट्री लागू करने की अनुमति के रूप में नहीं; प्लेटफ़ॉर्म डेबिट/रिफंड लेखांकन का स्वामित्व रखता है।