Документация оракула

1. Как это работает

1. Ваш бэкенд запрашивает подписанный отчёт: GET https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10 (ключ API с областью read:oracle; оплата за каждый подписанный отчёт).
2. Ваша транзакция передаёт отчёт и подпись контракту-верификатору, который проверяет подпись EIP-712, срок действия, сеть и свой стоп-механизм, а затем сохраняет цену.
3. В той же транзакции ваш контракт читает цену с требованием актуальности. Эта pull-схема всегда использует текущую цену.

Цены, запрошенные через API, также время от времени автоматически отправляются on-chain, но никогда не полагайтесь на сохранённую цену без проверки актуальности.

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: спред bid-ask в базисных пунктах; при нескольких брокерах он также отражает расхождение между ними.

Ответ 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): откатывается, если рынок не OPEN или цена недостаточно свежая. Используйте её для торговых действий.

У каждого фида есть стоп-механизм: скачок больше его лимита приостанавливает фид до проверки.

6. Пример на Solidity (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. Пример на 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): сервис подписи ненадолго недоступен; повторите с увеличивающейся задержкой.
• Откаты on-chain: InvalidSignature (не тот подписант, сеть или контракт), ReportExpired, FutureTimestamp, InvalidPrice, InvalidStatus, NoPrice (у фида ещё нет цены), FeedTripped (стоп-механизм), MarketNotOpen и PriceTooOld (из getPriceNoOlderThan), IsPaused.

9. Рекомендации

• Получайте отчёт прямо перед отправкой транзакции; отчёты истекают примерно через минуту.
• Всегда читайте через getPriceNoOlderThan с максимальным возрастом, подходящим вашему продукту.
• Явно обрабатывайте рынки CLOSED (выходные, праздники), например исполняйте расчёт при следующем открытии.
• Сначала протестируйте в тестнете, затем меняйте только адрес контракта и ID сети.
• Храните ключи API на своём сервере, никогда не на веб-странице.