Orakel-Dokumentation

1. Wie es funktioniert

1. Ihr Backend fordert einen signierten Bericht an: GET https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10 (API-Schlüssel mit dem Scope read:oracle; Abrechnung pro signiertem Bericht).
2. Ihre Transaktion übergibt Bericht und Signatur an den Verifier-Vertrag, der die EIP-712-Signatur, den Ablauf, die Chain und seinen Circuit Breaker prüft und dann den Kurs speichert.
3. In derselben Transaktion liest Ihr Vertrag den Kurs mit einer Aktualitätsanforderung. Dieses Pull-Muster verwendet immer den aktuellen Kurs.

Über die API angeforderte Kurse werden außerdem von Zeit zu Zeit automatisch on-chain übertragen, aber verlassen Sie sich nie ohne Aktualitätsprüfung auf einen gespeicherten Kurs.

2. Netzwerke und Verträge

Signer-Adresse: 0x83fa2d8836525251FAd214A78A72038D0864f877. Testnets dienen zum kostenlosen Testen ohne Dienstgarantien.

3. Feeds

Jeder Feed hat eine dauerhafte ID: feedId = keccak256(symbol). Kurse verwenden 8 Dezimalstellen.

4. Der signierte Bericht

EIP-712-Domain: Name MarketAPI Oracle, Version 2, die Chain-ID und die Verifier-Adresse. Typ:

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

• price: Mittelkurs mit 8 Dezimalstellen.
• timestamp: Zeitpunkt des Kurses (UTC-Sekunden); validUntil: Der Bericht läuft nach etwa einer Minute ab.
• marketStatus: 1 OPEN, 2 CLOSED (offizieller letzter Kurs, z. B. am Wochenende), 3 HALTED.
• spreadBps: Geld-Brief-Spanne in Basispunkten; bei mehreren Brokern spiegelt sie auch wider, wie weit diese auseinanderliegen.

Die API-Antwort enthält report (ABI-codiert) und signature (65 Byte): genau die beiden Argumente von submit.

5. Vertragsfunktionen

• submit(PriceReport r, bytes sig) returns (bool): verifizieren und speichern; wird ignoriert, wenn ein gleicher oder neuerer Kurs gespeichert ist.
• submitBatch(PriceReport[] rs, bytes[] sigs): mehrere Feeds in einer Transaktion; ungültige Einträge werden übersprungen.
• getPrice(bytes32 feedId): letzter gespeicherter Kurs und Zeitstempel; bricht ab (revert), solange ein Feed noch keinen Kurs hat.
• getPriceNoOlderThan(bytes32 feedId, uint256 maxAge): bricht ab, außer der Markt ist OPEN und der Kurs frisch genug. Verwenden Sie dies für Handelsaktionen.

Jeder Feed hat einen Circuit Breaker: Ein Sprung über seinem Limit pausiert den Feed, bis er geprüft ist.

6. Solidity-Beispiel (Pull-Muster)

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-Beispiel (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. Ablehnungen und Fehler

• refused-Einträge listen Symbole, die nicht signiert wurden, mit Grund, zum Beispiel derzeit kein verlässlicher Kurs (STALE) oder ein geschlossener Markt. Sie werden nicht berechnet.
• oracle_unavailable (503): Der Signierdienst ist kurz nicht verfügbar; wiederholen Sie mit Backoff.
• On-Chain-Reverts: InvalidSignature (falscher Signer, falsche Chain oder falscher Vertrag), ReportExpired, FutureTimestamp, InvalidPrice, InvalidStatus, NoPrice (Feed hat noch keinen Kurs), FeedTripped (Circuit Breaker), MarketNotOpen und PriceTooOld (von getPriceNoOlderThan), IsPaused.

9. Bewährte Vorgehensweisen

• Rufen Sie den Bericht direkt vor dem Senden der Transaktion ab; Berichte laufen nach etwa einer Minute ab.
• Lesen Sie immer mit getPriceNoOlderThan und einem zu Ihrem Produkt passenden Höchstalter.
• Behandeln Sie CLOSED-Märkte ausdrücklich (Wochenenden, Feiertage), zum Beispiel durch Abrechnung zur nächsten Eröffnung.
• Testen Sie zuerst im Testnet und ändern Sie danach nur Vertragsadresse und Chain-ID.
• Bewahren Sie API-Schlüssel auf Ihrem Server auf, nie in einer Webseite.