Documentation de l’oracle

1. Fonctionnement

1. Votre backend demande un rapport signé : GET https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10 (clé API avec la portée read:oracle ; facturé par rapport signé).
2. Votre transaction transmet le rapport et la signature au contrat vérificateur, qui contrôle la signature EIP-712, l’expiration, la chaîne et son coupe-circuit, puis enregistre le prix.
3. Dans la même transaction, votre contrat lit le prix avec une exigence de fraîcheur. Ce modèle pull utilise toujours le prix actuel.

Les prix demandés via l’API sont aussi poussés on-chain automatiquement de temps en temps, mais ne vous fiez jamais à un prix enregistré sans contrôle de fraîcheur.

2. Réseaux et contrats

Adresse du signataire : 0x83fa2d8836525251FAd214A78A72038D0864f877. Les testnets servent à des tests gratuits sans garantie de service.

3. Flux

Chaque flux a un ID permanent : feedId = keccak256(symbol). Les prix utilisent 8 décimales.

4. Le rapport signé

Domaine EIP-712 : nom MarketAPI Oracle, version 2, l’ID de chaîne et l’adresse du vérificateur. Type :

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

• price : prix médian avec 8 décimales.
• timestamp : heure du prix (secondes UTC) ; validUntil : le rapport expire au bout d’environ une minute.
• marketStatus : 1 OPEN, 2 CLOSED (dernier prix officiel, p. ex. le week-end), 3 HALTED.
• spreadBps : écart achat-vente en points de base ; avec plusieurs courtiers, il reflète aussi leur écart entre eux.

La réponse de l’API contient report (encodé en ABI) et signature (65 octets) : exactement les deux arguments de submit.

5. Fonctions du contrat

• submit(PriceReport r, bytes sig) returns (bool) : vérifier et enregistrer ; ignoré si un prix égal ou plus récent est enregistré.
• submitBatch(PriceReport[] rs, bytes[] sigs) : plusieurs flux en une transaction ; les entrées invalides sont ignorées.
• getPrice(bytes32 feedId) : dernier prix enregistré et horodatage ; échoue (revert) tant qu’un flux n’a pas encore de prix.
• getPriceNoOlderThan(bytes32 feedId, uint256 maxAge) : échoue sauf si le marché est OPEN et le prix assez frais. Utilisez-la pour les actions de trading.

Chaque flux a un coupe-circuit : un saut supérieur à sa limite met le flux en pause jusqu’à vérification.

6. Exemple Solidity (modèle pull)

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. Exemple 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. Refus et erreurs

• Les entrées refused listent les symboles qui n’ont pas été signés, avec un motif, par exemple aucun prix fiable pour le moment (STALE) ou un marché fermé. Elles ne sont pas facturées.
• oracle_unavailable (503) : le service de signature est brièvement indisponible ; réessayez avec un délai croissant.
• Revert on-chain : InvalidSignature (mauvais signataire, chaîne ou contrat), ReportExpired, FutureTimestamp, InvalidPrice, InvalidStatus, NoPrice (le flux n’a pas encore de prix), FeedTripped (coupe-circuit), MarketNotOpen et PriceTooOld (de getPriceNoOlderThan), IsPaused.

9. Bonnes pratiques

• Récupérez le rapport juste avant d’envoyer la transaction ; les rapports expirent au bout d’environ une minute.
• Lisez toujours avec getPriceNoOlderThan et un âge maximal adapté à votre produit.
• Gérez explicitement les marchés CLOSED (week-ends, jours fériés), par exemple en réglant à la prochaine ouverture.
• Testez d’abord sur le testnet, puis ne changez que l’adresse du contrat et l’ID de chaîne.
• Gardez les clés API sur votre serveur, jamais dans une page web.