ओरेकल दस्तावेज़

1. यह कैसे काम करता है

1. आपका बैकएंड हस्ताक्षरित रिपोर्ट माँगता है: GET https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10 (read:oracle स्कोप वाली API कुंजी; प्रति हस्ताक्षरित रिपोर्ट शुल्क)।
2. आपका ट्रांज़ैक्शन रिपोर्ट और हस्ताक्षर वेरिफ़ायर कॉन्ट्रैक्ट को देता है, जो EIP-712 हस्ताक्षर, समाप्ति, चेन और अपना सर्किट ब्रेकर जाँचता है, फिर कीमत संग्रहीत करता है।
3. उसी ट्रांज़ैक्शन में आपका कॉन्ट्रैक्ट ताज़गी की शर्त के साथ कीमत पढ़ता है। यह पुल पैटर्न हमेशा मौजूदा कीमत का उपयोग करता है।

API से माँगी गई कीमतें समय-समय पर अपने-आप ऑन-चेन भी भेजी जाती हैं, पर ताज़गी जाँचे बिना कभी संग्रहीत कीमत पर निर्भर न रहें।

2. नेटवर्क और कॉन्ट्रैक्ट

हस्ताक्षरकर्ता का पता: 0x83fa2d8836525251FAd214A78A72038D0864f877। टेस्टनेट बिना सेवा गारंटी के मुफ़्त परीक्षण के लिए हैं।

3. फ़ीड

हर फ़ीड का एक स्थायी ID है: feedId = keccak256(symbol)। कीमतें 8 दशमलव का उपयोग करती हैं।

4. हस्ताक्षरित रिपोर्ट

EIP-712 डोमेन: नाम MarketAPI Oracle, संस्करण 2, चेन ID और वेरिफ़ायर का पता। प्रकार:

PriceReport(bytes32 feedId,int256 price,uint64 timestamp,uint64 validUntil,uint8 marketStatus,uint32 spreadBps)

• price: 8 दशमलव के साथ मध्य कीमत।
• timestamp: कीमत का समय (UTC सेकंड); validUntil: रिपोर्ट लगभग एक मिनट बाद समाप्त हो जाती है।
• marketStatus: 1 OPEN, 2 CLOSED (आधिकारिक अंतिम कीमत, जैसे सप्ताहांत में), 3 HALTED।
• spreadBps: बेसिस पॉइंट में बिड-आस्क स्प्रेड; कई ब्रोकर होने पर यह यह भी दिखाता है कि वे आपस में कितने दूर हैं।

API उत्तर में report (ABI-एन्कोडेड) और signature (65 बाइट) होते हैं: ठीक submit के दो आर्ग्युमेंट।

5. कॉन्ट्रैक्ट फ़ंक्शन

• submit(PriceReport r, bytes sig) returns (bool): सत्यापित करें और संग्रहीत करें; अगर बराबर या नई कीमत संग्रहीत है तो अनदेखा।
• submitBatch(PriceReport[] rs, bytes[] sigs): एक ट्रांज़ैक्शन में कई फ़ीड; अमान्य प्रविष्टियाँ छोड़ दी जाती हैं।
• getPrice(bytes32 feedId): नवीनतम संग्रहीत कीमत और टाइमस्टैम्प; जब तक फ़ीड की कोई कीमत न हो, revert करता है।
• getPriceNoOlderThan(bytes32 feedId, uint256 maxAge): तब तक revert करता है जब तक बाज़ार OPEN न हो और कीमत पर्याप्त ताज़ा न हो। ट्रेडिंग कार्रवाइयों के लिए इसका उपयोग करें।

हर फ़ीड में सर्किट ब्रेकर है: उसकी सीमा से बड़ी छलाँग समीक्षा होने तक फ़ीड रोक देती है।

6. Solidity उदाहरण (पुल पैटर्न)

interface IMarketApiOracle {
    struct PriceReport { bytes32 feedId; int256 price; uint64 timestamp; uint64 validUntil; uint8 marketStatus; uint32 spreadBps; }
    function submit(PriceReport calldata r, bytes calldata sig) external returns (bool);
    function getPriceNoOlderThan(bytes32 feedId, uint256 maxAge) external view returns (int256 price, uint64 timestamp);
}

contract GoldVault {
    IMarketApiOracle immutable oracle;
    bytes32 constant XAUUSD = keccak256("XAUUSD");
    constructor(IMarketApiOracle o) { oracle = o; }

    function settle(IMarketApiOracle.PriceReport calldata r, bytes calldata sig) external {
        oracle.submit(r, sig);
        (int256 price, ) = oracle.getPriceNoOlderThan(XAUUSD, 60);   // reverts unless OPEN and at most 60 s old
        // ... use price (8 decimals)
    }
}

7. JavaScript उदाहरण (ethers v6)

const res = await fetch("https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10",
  { headers: { Authorization: `Bearer ${process.env.API_KEY}` } });
const { data, refused } = await res.json();
if (!data.length) throw new Error(refused[0]?.reason);            // e.g. market closed or stale
const r = data[0];
const report = ethers.AbiCoder.defaultAbiCoder().decode(
  ["tuple(bytes32,int256,uint64,uint64,uint8,uint32)"], r.report)[0];
await vault.settle(report, r.signature);                          // your contract calls oracle.submit(...)

8. अस्वीकृतियाँ और त्रुटियाँ

• refused प्रविष्टियाँ उन सिंबल को सूचीबद्ध करती हैं जिन पर हस्ताक्षर नहीं हुए, कारण के साथ, जैसे अभी कोई भरोसेमंद कीमत नहीं (STALE) या बंद बाज़ार। इनका शुल्क नहीं लगता।
• oracle_unavailable (503): साइनिंग सेवा थोड़ी देर के लिए उपलब्ध नहीं; बैक-ऑफ़ के साथ दोबारा कोशिश करें।
• ऑन-चेन revert: InvalidSignature (ग़लत हस्ताक्षरकर्ता, चेन या कॉन्ट्रैक्ट), ReportExpired, FutureTimestamp, InvalidPrice, InvalidStatus, NoPrice (फ़ीड की अभी कोई कीमत नहीं), FeedTripped (सर्किट ब्रेकर), MarketNotOpen और PriceTooOld (getPriceNoOlderThan से), IsPaused।

9. सर्वोत्तम तरीक़े

• ट्रांज़ैक्शन भेजने से ठीक पहले रिपोर्ट लें; रिपोर्ट लगभग एक मिनट बाद समाप्त हो जाती हैं।
• हमेशा getPriceNoOlderThan और अपने प्रोडक्ट के अनुकूल अधिकतम उम्र के साथ पढ़ें।
• CLOSED बाज़ारों (सप्ताहांत, छुट्टियाँ) को स्पष्ट रूप से संभालें, जैसे अगले ओपन पर सेटल करें।
• पहले टेस्टनेट पर परखें, फिर केवल कॉन्ट्रैक्ट का पता और चेन ID बदलें।
• API कुंजियाँ अपने सर्वर पर रखें, कभी किसी वेब पेज में नहीं।