Vito API और खरीद

Silver या उससे ऊपर की सदस्यता ज़रूरी है — आवेदन करने के लिए भी और हर प्रमाणित कॉल के लिए भी। अगर कुंजी के मालिक की सदस्यता समाप्त हो जाए, तो दोबारा सदस्यता लेने तक प्रोजेक्ट फ़्रीज़ रहता है।

एक REST API जो आपके ऐप्लिकेशन को Discord के भीतर से किसी उपयोगकर्ता के Vito बैलेंस के साथ काम करने देता है — उसे पढ़ना, उससे राशि लेना, उसमें जोड़ना, या उपयोगकर्ताओं के बीच स्थानांतरित करना। सभी एंडपॉइंट JSON लौटाते हैं और /v1 के अंतर्गत वर्ज़न किए गए हैं।

Vito कभी असली पैसे में नहीं बदलता और न ही उससे आता है। यह केवल Vetox बैलेंस के बीच ही चलता है।

पहुँच प्राप्त करना

पहुँच हर प्रोजेक्ट के लिए अलग से दी जाती है। चारों चीज़ें चाहिए:

सक्रिय सदस्यता, Silver या उससे ऊपर

हर कॉल पर जाँची जाती है, सिर्फ़ स्वीकृति के समय नहीं।

स्वीकृत डेवलपर आवेदन

आपके डैशबोर्ड के Vito API पेज से भेजा जाता है। Vetox टीम इसकी समीक्षा हाथ से करती है।

स्वीकार की गई API डेवलपर शर्तें

आवेदन भेजते समय ही स्वीकार की जाती हैं।

आपके प्रोजेक्ट को जिन scopes की ज़रूरत है

आपके विवरण के आधार पर Vetox टीम द्वारा दिए जाते हैं।

आप क्या बना रहे हैं और कुंजी कैसे संभालेंगे, यह ठोस रूप से लिखें। अस्पष्ट आवेदन ही अस्वीकार होते हैं।

Scopes

Scope	अनुमति देता है
`balance:read`	किसी उपयोगकर्ता का Vito बैलेंस पढ़ना
`deduct:create`	किसी उपयोगकर्ता के बैलेंस से राशि लेना
`credit:create`	अपने ही बैलेंस से किसी उपयोगकर्ता को Vito देना
`transfer:create`	दो उपयोगकर्ताओं के बीच Vito स्थानांतरित करना
`transactions:read`	अपने प्रोजेक्ट के लेनदेन देखना और पढ़ना

प्रमाणीकरण

अपनी गुप्त कुंजी Bearer टोकन के रूप में भेजें:

Authorization: Bearer vito_live_xxxxxxxxxxxxxxxx

दो वैकल्पिक परतें प्रोजेक्ट को और मज़बूत बनाती हैं:

IP अनुमति सूची — कॉल को कुछ निश्चित सर्वर IP तक सीमित करती है
दर सीमाएँ — प्रति-प्रोजेक्ट सीमाएँ, जो मालिक की सदस्यता श्रेणी के साथ बढ़ती हैं

कुंजियाँ, रोटेशन और भंडारण

आपकी कुंजी और हस्ताक्षर सीक्रेट ठीक एक बार दिखाए जाते हैं। स्वीकृति के बाद उन्हें API कुंजी टैब में देखने के लिए आपके पास 7 दिन की अवधि होती है। Vetox सिर्फ़ एक हैश रखता है और उन्हें दोबारा नहीं दिखा सकता — यह अवधि चूक गए तो नई कुंजी के लिए रोटेशन करना होगा।

इसे केवल सर्वर पर रखें — जिसके पास यह है, वह आपके उपयोगकर्ताओं से राशि ले सकता है
रोटेशन API कुंजी टैब से करें। पुरानी कुंजी 24 घंटे की छूट अवधि तक काम करती रहती है, ताकि आप बिना रुकावट तैनाती कर सकें
webhook हस्ताक्षर सीक्रेट अलग से रोटेट होता है और उसकी अपनी 24 घंटे की अतिव्यापी अवधि होती है
लीक होने पर तुरंत रोटेशन करें

किसी उपयोगकर्ता से राशि लेना

अकेली कुंजी किसी उपयोगकर्ता के Vito को हिला नहीं सकती। हर कटौती के लिए उपयोगकर्ता को vetox.io पर अपने वॉलेट PIN से मंज़ूरी देनी होती है — न आपके ऐप के भीतर, न Discord के भीतर।

आपका ऐप POST /v1/deduct कॉल करता है

उपयोगकर्ता, राशि, मूल guildId और वस्तु के विवरण के साथ।

Vito एक confirmUrl लौटाता है

एक लंबित पुष्टि, जो 10 मिनट तक वैध रहती है। उपयोगकर्ता को DM भी जाता है।

उपयोगकर्ता अपने PIN से मंज़ूरी देता है

vetox.io पर।

Vito निपटान करता है और सूचित करता है

बैलेंस से कटौती होती है, लेनदेन दर्ज होता है, और यदि आपने कॉन्फ़िगर किया है तो हस्ताक्षरित webhook भेजा जाता है।

आपका ऐप सत्यापित करके पूरा करता है

हस्ताक्षर जाँचें, फिर सामग्री खोलें या वस्तु सौंपें।

अपनी कार्रवाई केवल confirmation.completed पर पूरी करें — कभी भी /deduct की प्रतिक्रिया पर नहीं। उस समय कटौती अंतिम नहीं होती।

अनुरोध पैरामीटर — `/v1/deduct`

फ़ील्ड	आवश्यक	टिप्पणी
`discordId`	हाँ	उपयोगकर्ता का Discord ID — 17–20 अंकों का snowflake
`amount`	हाँ	धनात्मक पूर्णांक
`guildId`	हाँ	वह Discord सर्वर जहाँ से कटौती शुरू होती है। हर कटौती किसी सर्वर से ही आनी चाहिए
`reason`	नहीं	अधिकतम 256 अक्षर। उपयोगकर्ता को दिखता है और webhook में लौटाया जाता है
`merchantRef`	नहीं	आपका अपना संदर्भ, अधिकतम 128 अक्षर। webhook को अपने रिकॉर्ड से मिलाने के लिए
`product`	नहीं	`{ type, name, description?, imageUrl? }` — पुष्टि पेज और DM में दिखता है
`imageUrl`	नहीं	`https://` होना चाहिए
`metadata`	नहीं	अधिकतम 10 स्ट्रिंग कुंजी/मान जोड़े, ज्यों के त्यों आगे भेजे जाते हैं

किसी उपयोगकर्ता को Vito देना

POST /v1/add किसी उपयोगकर्ता को आपके अपने बैलेंस से Vito देता है — इनाम या धनवापसी के लिए। guildId और product को छोड़कर वही फ़ील्ड जो /deduct में हैं।

कटौती के विपरीत, जोड़ने में कोई पुष्टि चरण नहीं होता — निपटान तुरंत हो जाता है। इसके लिए credit:create scope और पर्याप्त बैलेंस चाहिए, वरना कॉल 402 VITO_INSUFFICIENT_OWNER_FUNDS लौटाता है।

शुल्क

हर कटौती प्लेटफ़ॉर्म शुल्क घटाकर आपको निपटाई जाती है — वही दर सूची जो ऐप के भीतर Vito स्थानांतरण पर लागू होती है, और आधार आपकी सदस्यता श्रेणी है:

आपकी सदस्यता	शुल्क
Normal, Silver, Gold	7%
Platinum	6%
Diamond	5%

5 Vito या उससे कम की राशि पर कोई शुल्क नहीं, और /v1/add से दी गई राशि पर कभी शुल्क नहीं लगता।

Webhooks

सेटिंग्स टैब में एक या अधिक https कॉलबैक URL जोड़ें। जब भी कोई पुष्टि अंतिम स्थिति तक पहुँचती है, Vito एक हस्ताक्षरित POST भेजता है।

webhooks तभी भेजे जाते हैं जब आपके प्रोजेक्ट में कॉलबैक URL और हस्ताक्षर सीक्रेट दोनों हों। सीक्रेट (whsec_…) को API कुंजी टैब से एक ही बार देखा जा सकता है।

हस्ताक्षर सत्यापित करना

हर डिलीवरी के साथ X-Vito-Signature हेडर आता है:

X-Vito-Signature: ts=<unix>;h1=<hex>

हर डिलीवरी के साथ दो और हेडर आते हैं — X-Vito-Event-Id को डुप्लिकेट हटाने की कुंजी बनाएँ, क्योंकि पुनः प्रयास वही id दोबारा भेजता है:

हेडर	इसमें होता है
`X-Vito-Event-Id`	इस ईवेंट का स्थिर id — हर पुनः प्रयास में एक जैसा
`X-Vito-Event-Type`	जैसे `confirmation.completed`

हस्ताक्षर सीक्रेट के रोटेशन के दौरान हेडर में एक से अधिक हस्ताक्षर आते हैं, सबसे नया पहले:

X-Vito-Signature: ts=<unix>;h1=<नया>;h1=<पुराना>

यदि कोई भी h1 मेल खाए तो डिलीवरी स्वीकार करें। केवल पहला पढ़ने वाला सत्यापक नया सीक्रेट तैनात करने तक हर webhook अस्वीकार करेगा — और यही 24 घंटे की अतिव्यापी अवधि के पूरे उद्देश्य को व्यर्थ कर देता है।

अपने हस्ताक्षर सीक्रेट से <ts>:<rawBody> पर HMAC दोबारा निकालें और स्थिर समय में तुलना करें।

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const parts = header.split(';');
  const ts = parts.find(p => p.startsWith('ts='))?.slice(3);
  const sigs = parts.filter(p => p.startsWith('h1=')).map(p => p.slice(3));
  if (!ts || sigs.length === 0) return false;

  // Reject anything older than ~5 minutes — replay protection.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = Buffer.from(
    crypto.createHmac('sha256', secret).update(`${ts}:${rawBody}`).digest('hex'),
  );

  // Any matching signature is valid — a rotation emits several.
  return sigs.some(sig => {
    const actual = Buffer.from(sig);
    // timingSafeEqual throws when the lengths differ, so check first.
    return (
      actual.length === expected.length && crypto.timingSafeEqual(actual, expected)
    );
  });
}

कच्चे बॉडी के आधार पर सत्यापित करें — किसी भी JSON पार्सिंग या मिडलवेयर द्वारा उसे बदले जाने से पहले।

ईवेंट

पाँच ईवेंट प्रकार, सभी एक ही पेलोड संरचना साझा करते हैं। परिणाम data.status में होता है।

ईवेंट	अर्थ
`confirmation.completed`	मंज़ूर हुआ और कटौती हुई। `transactionId` साथ आता है। अपनी कार्रवाई यहीं पूरी करें
`confirmation.failed`	पूरा नहीं हो सका — बैलेंस कम या आंतरिक त्रुटि। `failureReason` साथ आता है
`confirmation.expired`	10 मिनट में पुष्टि नहीं हुई। कोई Vito नहीं हिला
`confirmation.cancelled`	उपयोगकर्ता ने रद्द कर दिया। कोई Vito नहीं हिला
`credit.completed`	मालिक द्वारा वित्तपोषित `/add` का निपटान हुआ। तुरंत चलता है — कोई पुष्टि चरण नहीं

webhooks को बढ़ते अंतराल के साथ 5 बार दोहराया जाता है। जल्दी 2xx लौटाएँ और अपनी पूर्ति असिंक्रोनस रूप से करें।

त्रुटि कोड

हर प्रतिक्रिया एक लिफ़ाफ़े में आती है। सफलता में data होता है और विफलता में error — दोनों कभी साथ नहीं:

{
  "success": false,
  "error": {
    "type": "Forbidden",
    "message": "API key lacks the required scope for this operation.",
    "code": "VITO_INSUFFICIENT_SCOPE"
  },
  "requestId": "…",
  "timestamp": 1735161600000
}

हर कोड के आगे VITO_ लगा होता है। पूरी स्ट्रिंग से मिलान करें — खाली RATE_LIMITED या FORBIDDEN कभी प्रतिक्रिया में नहीं आता।

कोड	स्थिति	अर्थ
`VITO_VALIDATION_ERROR`	400	कोई फ़ील्ड नदारद है या उसका प्रारूप ग़लत है
`VITO_INVALID_AMOUNT`	400	`amount` धनात्मक पूर्णांक नहीं है
`VITO_AMOUNT_LIMIT_EXCEEDED`	400	आपकी प्रति-लेनदेन सीमा से ऊपर
`VITO_DAILY_VOLUME_EXCEEDED`	400	यह कॉल आपकी दैनिक मात्रा सीमा तोड़ देगी
`VITO_SELF_TRANSFER`	400	भेजने वाला और पाने वाला एक ही उपयोगकर्ता है
`VITO_INVALID_API_KEY`	401	कुंजी नदारद, ग़लत प्रारूप में, रद्द या अज्ञात है
`VITO_INSUFFICIENT_FUNDS`	402	उपयोगकर्ता के पास कटौती के लिए पर्याप्त राशि नहीं
`VITO_INSUFFICIENT_OWNER_FUNDS`	402	`/add` के लिए आपका बैलेंस बहुत कम है
`VITO_INSUFFICIENT_SCOPE`	403	इस एंडपॉइंट के लिए ज़रूरी scope कुंजी में नहीं है
`VITO_IP_NOT_ALLOWED`	403	कॉल करने वाला IP अनुमति सूची में नहीं है
`VITO_OWNER_MEMBERSHIP_INACTIVE`	403	मालिक की सदस्यता समाप्त — दोबारा सदस्यता लेने तक फ़्रीज़
`VITO_GUILD_NOT_ALLOWED`	403	`guildId` प्रोजेक्ट की अनुमत सर्वर सूची में नहीं है
`VITO_TOS_NOT_ACCEPTED`	403	डेवलपर शर्तें स्वीकार नहीं की गईं, या नया संस्करण लंबित है
`VITO_PROJECT_FROZEN`	403	फ़्रीज़ — आमतौर पर मालिक की सदस्यता समाप्त होने के कारण
`VITO_PROJECT_SUSPENDED`	403	Vetox टीम ने निलंबित किया
`VITO_PROJECT_BANNED`	403	Vetox टीम ने प्रतिबंधित किया
`VITO_USER_BLACKLISTED`	403	उपयोगकर्ता Vito संचालन से वंचित है
`VITO_ACCOUNT_LOCKED`	403	असफल PIN प्रयासों के बाद उपयोगकर्ता का वॉलेट लॉक है
`VITO_USER_NOT_FOUND`	404	उस Discord ID के लिए कोई Vito खाता नहीं
`VITO_CONFIRMATION_NOT_FOUND`	404	अज्ञात पुष्टि टोकन
`VITO_IDEMPOTENCY_CONFLICT`	409	वही `Idempotency-Key`, पर अलग बॉडी
`VITO_IDEMPOTENCY_IN_PROGRESS`	409	एक जैसा अनुरोध अभी चल रहा है — थोड़ी देर बाद दोहराएँ
`VITO_CONFIRMATION_ALREADY_PROCESSED`	409	वह पुष्टि पहले ही अंतिम स्थिति तक पहुँच चुकी है
`VITO_KEY_ROTATION_IN_PROGRESS`	409	एक रोटेशन पहले से चल रहा है
`VITO_CONFIRMATION_EXPIRED`	410	10 मिनट की अवधि बीत चुकी है
`VITO_RATE_LIMITED`	429	गति घटाकर दोबारा कोशिश करें
`VITO_INTERNAL_ERROR`	500	हमारी ओर से अप्रत्याशित गड़बड़ी

दर सीमाएँ

मालिक की सदस्यता	प्रति मिनट	प्रति घंटा
कोई नहीं	60	1,000
Silver या Gold	180	5,000
Platinum या Diamond	600	15,000

आपकी प्रति-मिनट सीमा की आधी, कम से कम 30, एक प्रति-IP सीमा भी लागू होती है।

भारी लोड में लिखने वाले एंडपॉइंट बंद होकर विफल होते हैं — दोहरे ख़र्च का जोखिम लेने के बजाय कटौती अस्वीकार कर दी जाती है। पढ़ने वाले एंडपॉइंट खुले होकर विफल होते हैं। अस्वीकृत लेखन को “हुआ ही नहीं” मानकर दोबारा भेजें।

पुनः प्रयासों को सुरक्षित ढंग से डुप्लिकेट-मुक्त रखने के लिए Idempotency-Key हेडर भेजें।

एंडपॉइंट

एंडपॉइंट	Scope
`GET /v1/auth/verify`	कोई भी
`POST /v1/auth/rotate-key`	कोई भी
`GET /v1/balance/:discordId`	`balance:read`
`POST /v1/deduct`	`deduct:create`
`POST /v1/add`	`credit:create`
`POST /v1/transfer`	`transfer:create`
`GET /v1/transactions` और `/:id`	`transactions:read`
`GET /v1/webhooks/events`	`transactions:read`

सीमाएँ

पुष्टियाँ 10 मिनट बाद समाप्त हो जाती हैं — बिना पुष्टि वाले अनुरोधों को छोड़ा हुआ मानें
amount धनात्मक पूर्णांक होना चाहिए
metadata अधिकतम 10 कुंजियों तक सीमित है
प्रति-लेनदेन और दैनिक सीमाएँ Vetox टीम तय करती है; वे सेटिंग्स टैब में केवल-पढ़ने के रूप में दिखती हैं

सुरक्षा जाँच-सूची

सीक्रेट सर्वर पर ही रखें

API कुंजी और हस्ताक्षर सीक्रेट का क्लाइंट कोड में कोई स्थान नहीं। कोई भी लीक हो तो तुरंत रोटेट करें।

हर webhook सत्यापित करें

कच्चे बॉडी के आधार पर हस्ताक्षर जाँचें और ~5 मिनट से पुरानी डिलीवरी अस्वीकार करें।

निपटान केवल completed पर

/deduct की प्रतिक्रिया देखकर कभी सामान न सौंपें — कटौती confirmation.completed पर ही अंतिम होती है।

न्यूनतम अधिकार

केवल वही scopes माँगें जो आप सचमुच उपयोग करते हैं, और IP अनुमति सूची चालू रखें।

समस्या निवारण

हर कॉल अनधिकृत लौटाती है

मालिक की सदस्यता समाप्त हो चुकी है। यह हर कॉल पर दोबारा जाँची जाती है।

मेरी कुंजी खो गई

इसे वापस नहीं पाया जा सकता — केवल हैश संग्रहीत होता है। नई पाने के लिए रोटेट करें।

रोटेशन के बाद webhook हस्ताक्षर विफल हो रहे हैं

24 घंटे की अतिव्यापी अवधि में दोनों सीक्रेट स्वीकार करें।

कोई कटौती कभी पूरी नहीं होती

उपयोगकर्ता ने मंज़ूरी नहीं दी। पुष्टियाँ 10 मिनट बाद समाप्त हो जाती हैं।

कोई webhook नहीं आता

प्रोजेक्ट को कॉलबैक URL और हस्ताक्षर सीक्रेट दोनों चाहिए। किसी एक के होने पर कुछ भी नहीं भेजा जाता।

मैंने जितना काटा उससे कम Vito आया

यह निपटान शुल्क है। बचने के लिए 5 Vito या उससे कम की राशि लें, या इसे अपनी क़ीमत में जोड़ें।

402 VITO_INSUFFICIENT_OWNER_FUNDS

/v1/add आपके अपने बैलेंस से जाता है, शून्य से नहीं बनता। बैलेंस भरें।

Vito

बैलेंस, PIN और शुल्क।

भुगतान अनुरोध

जब आप राशि लेते हैं तो उपयोगकर्ता को क्या दिखता है।

मुख्य

उपयोगिताएँ

Vito

लीडरबोर्ड

Vito API और खरीद

पहुँच प्राप्त करना

Scopes

प्रमाणीकरण

कुंजियाँ, रोटेशन और भंडारण

किसी उपयोगकर्ता से राशि लेना

अनुरोध पैरामीटर — `/v1/deduct`

किसी उपयोगकर्ता को Vito देना

शुल्क

Webhooks

हस्ताक्षर सत्यापित करना

ईवेंट

त्रुटि कोड

दर सीमाएँ

एंडपॉइंट

सीमाएँ

सुरक्षा जाँच-सूची

समस्या निवारण

Vito

भुगतान अनुरोध

​पहुँच प्राप्त करना

​Scopes

​प्रमाणीकरण

​कुंजियाँ, रोटेशन और भंडारण

​किसी उपयोगकर्ता से राशि लेना

​अनुरोध पैरामीटर — /v1/deduct

​किसी उपयोगकर्ता को Vito देना

​शुल्क

​Webhooks

​हस्ताक्षर सत्यापित करना

​ईवेंट

​त्रुटि कोड

​दर सीमाएँ

​एंडपॉइंट

​सीमाएँ

​सुरक्षा जाँच-सूची

​समस्या निवारण

Vito

भुगतान अनुरोध

पहुँच प्राप्त करना

Scopes

प्रमाणीकरण

कुंजियाँ, रोटेशन और भंडारण

किसी उपयोगकर्ता से राशि लेना

अनुरोध पैरामीटर — `/v1/deduct`

किसी उपयोगकर्ता को Vito देना

शुल्क

Webhooks

हस्ताक्षर सत्यापित करना

ईवेंट

त्रुटि कोड

दर सीमाएँ

एंडपॉइंट

सीमाएँ

सुरक्षा जाँच-सूची

समस्या निवारण