תיעוד האורקל

1. איך זה עובד

1. ה-backend שלכם מבקש דוח חתום: GET https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10 (מפתח API עם ההיקף read:oracle; חיוב לכל דוח חתום).
2. העסקה שלכם מעבירה את הדוח והחתימה לחוזה המאמת, שבודק את חתימת ה-EIP-712, התוקף, הרשת ומפסק הזרם שלו, ואז שומר את המחיר.
3. באותה עסקה החוזה שלכם קורא את המחיר עם דרישת עדכניות. דפוס המשיכה הזה משתמש תמיד במחיר הנוכחי.

מחירים שמתבקשים דרך ה-API נדחפים גם on-chain אוטומטית מדי פעם, אבל לעולם אל תסתמכו על מחיר שמור בלי בדיקת עדכניות.

2. רשתות וחוזים

כתובת החותם: 0x83fa2d8836525251FAd214A78A72038D0864f877. רשתות הבדיקה מיועדות לבדיקות חינם ללא התחייבות לשירות.

3. פידים

לכל פיד יש מזהה קבוע: feedId = keccak256(symbol). המחירים משתמשים ב-8 ספרות אחרי הנקודה.

4. הדוח החתום

דומיין EIP-712: שם MarketAPI Oracle, גרסה 2, מזהה הרשת וכתובת המאמת. טיפוס:

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 ‏on-chain: ‏InvalidSignature (חותם, רשת או חוזה שגויים), ReportExpired, FutureTimestamp, InvalidPrice, InvalidStatus, NoPrice (לפיד אין עדיין מחיר), FeedTripped (מפסק זרם), MarketNotOpen ו-PriceTooOld (מ-getPriceNoOlderThan), IsPaused.

9. שיטות עבודה מומלצות

• קבלו את הדוח ממש לפני שליחת העסקה; דוחות פגים אחרי כדקה.
• קראו תמיד עם getPriceNoOlderThan וגיל מרבי שמתאים למוצר שלכם.
• טפלו במפורש בשווקים במצב CLOSED (סופי שבוע, חגים), למשל בסליקה בפתיחה הבאה.
• בדקו קודם ברשת הבדיקה, ואז שנו רק את כתובת החוזה ואת מזהה הרשת.
• שמרו מפתחות API בשרת שלכם, לעולם לא בדף אינטרנט.