أوراكل أسعار للعقود الذكية: الفوركس والذهب والمؤشرات والأسهم على السلسلة

كيف يعمل

1. اجلب تقريرًا موقّعًا: GET /oracle/report بمفتاح الـ API الخاص بك.
2. أرسله ضمن معاملتك: يتحقق عقد التحقق الخاص بنا من التوقيع عبر ecrecover.
3. استخدم السعر المُتحقَّق منه، وارفضه إن كان أقدم مما يناسب حالة استخدامك.

التقارير بيانات EIP-712 مُنمَّطة PriceReport(bytes32 feedId,int256 price,uint64 timestamp,uint64 validUntil,uint8 marketStatus,uint32 spreadBps)، مرتبطة بسلسلة واحدة وعقد تحقق واحد (لا إعادة استخدام في مكان آخر)، ولا تُقبل إلا حتى validUntil، أي نحو دقيقة بعد التوقيع (لا يمكن تكديس التقارير المواتية). الأسعار هي متوسط العرض والطلب بـ 8 منازل عشرية؛ وspreadBps هو فارق العرض والطلب. حين ترسل تقريرًا في معاملتك الخاصة، تدفع ذلك الغاز. كما يخزّن المرحِّل الخاص بنا المصادر المطلوبة على السلسلة من حين لآخر (قراءتها مجانية)، لكن تحقق دائمًا من عمر السعر المخزَّن.

ساعات السوق

يذكر كل تقرير حالة السوق: OPEN (سعر حي لا يتجاوز عمره 60 ثانية)، أو CLOSED (السعر الرسمي الأخير قبل الإغلاق، وهو نفسه للجميع، ويُوقَّع في أي وقت ما دام السوق مغلقًا)، أو HALTED (التداول متوقف). لا تُعيد getPriceNoOlderThan إلا أسعار OPEN، فلا يمكن أبدًا أن يمر سعر إغلاق على أنه سعر حي. ينبغي للرموز المدعومة بأصول أن تسوّي الأوامر المقدَّمة أثناء إغلاق السوق بسعر OPEN التالي (التسعير الآجل، كما تفعل الصناديق وصناديق ETF).

قاطع الدارة

يمكن أن يكون لكل مصدر قفزة قصوى مسموح بها. لا تُخزَّن الحركة الأكبر: يتوقف المصدر حتى نفحصه ونعيد فتحه، فلا يصل سعر خاطئ أو متلاعب به إلى عقدك أبدًا.

المصادر

الشبكات

عنوان المُوقِّع: 0x83fa2d8836525251FAd214A78A72038D0864f877. قائمة قابلة للقراءة آليًا: /oracle/feeds.

التكامل

1. اجلب تقريرًا موقّعًا

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.marketapi.app/v1/oracle/report?symbols=EURUSD&chain_id=10"

يُعيد report (الصف المرمَّز بـ ABI) وsignature (65 بايت) لكل رمز. يحتاج مفتاحك إلى النطاق read:oracle.

2. تحقّق منه في عقدك

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);  // verifies, stores if newer
    function getPriceNoOlderThan(bytes32 feedId, uint256 maxAge)
        external view returns (int256 price, uint64 timestamp);   // OPEN and fresh only, else reverts
    function getPrice(bytes32 feedId) external view
        returns (int256 price, uint64 timestamp, uint8 marketStatus, uint32 spreadBps);   // incl. CLOSED
}

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

    function act(IMarketApiOracle.PriceReport calldata r, bytes calldata sig) external {
        oracle.submit(r, sig);                                       // reverts on a bad signature
        (int256 price, ) = oracle.getPriceNoOlderThan(EURUSD, 60);   // 8 decimals
        // ... use price ...
    }
}

يمكن للمستهلكين بأسلوب Chainlink قراءة المصدر عبر MarketApiFeedAdapter (latestRoundData()، AggregatorV3Interface).

الأسعار

5 رصيد لكل تقرير موقّع، يُدفع من رصيد الـ API المعتاد. وقراءة الأسعار المخزَّنة مسبقًا على السلسلة مجانية.

حالات استخدام مصادر أسعارنا على السلسلة

• الأصول المرمّزة وRWA: سعّر الأسهم المرمّزة والرموز المدعومة بالذهب والأصول الحقيقية الأخرى ببيانات أسعار تراعي ساعات السوق.
• إقراض DeFi والضمانات: قيّم الضمانات المدعومة بالعملات والسلع بأسعار حديثة قابلة للتحقق وبفحوصات حداثة آمنة للتصفية.
• الأصول الاصطناعية وصرف العملات على السلسلة: سوِّ مراكز الفوركس والمؤشرات والسلع الاصطناعية مقابل أسعار مرجعية موقّعة.
• العملات المستقرة والمدفوعات: حوّل بين العملات على السلسلة بأسعار EUR/USD وGBP/USD وغيرها الحية.

لماذا أوراكل سحب موقّع؟

تتحدّث أوراكلات الدفع وفق جدول، ويدفع أحدهم الغاز عن كل تحديث. أما مع أوراكل السحب فيجلب عقدك سعرًا حديثًا موقّعًا تشفيريًا في اللحظة التي يحتاجه فيها تمامًا: تكلفة أقل وبيانات أحدث والتحقق نفسه على السلسلة. وحالة السوق وفارق العرض والطلب وانتهاء الصلاحية جزء من كل تقرير موقّع.

موصى به: نمط السحب (أسعار حديثة دائمًا)

لا تعتمد على السعر المخزَّن مسبقًا على السلسلة. اجلب تقريرًا موقّعًا حديثًا وأرسله في المعاملة نفسها التي تستخدمه: فيرى عقدك دائمًا السعر الحالي، ولا تدفع إلا مقابل تحديثاتك.

// 1) off-chain: GET https://api.marketapi.app/v1/oracle/report?symbols=EURUSD&chain_id=CHAIN_ID  (header: Authorization: Bearer KEY)
// 2) on-chain: verify, store and use the report atomically
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 MyVault {
    IMarketApiOracle immutable oracle;
    bytes32 constant EURUSD = keccak256("EURUSD");
    constructor(IMarketApiOracle o) { oracle = o; }

    function settle(IMarketApiOracle.PriceReport calldata r, bytes calldata sig) external {
        oracle.submit(r, sig);                                         // ignored if an equal/newer price is stored
        (int256 price, ) = oracle.getPriceNoOlderThan(EURUSD, 60);    // reverts unless OPEN and fresh
        // ... use price (8 decimals)
    }
}

حقلا report وsignature في التقرير من الـ API هما بالضبط وسيطا submit. التقارير صالحة لنحو دقيقة، فاجلبها قبيل إرسال المعاملة مباشرة.