Oracle documentation

1. How it works

1. Your backend requests a signed report: GET https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10 (API key with the read:oracle scope; billed per signed report).
2. Your transaction passes the report and signature to the verifier contract, which checks the EIP-712 signature, the expiry, the chain and its circuit breaker, then stores the price.
3. In the same transaction your contract reads the price with a freshness requirement. This pull pattern always uses the current price.

Prices requested through the API are also pushed on-chain automatically from time to time, but never rely on a stored price without a freshness check.

2. Networks and contracts

Signer address: 0x83fa2d8836525251FAd214A78A72038D0864f877. Testnets are for free testing without service guarantees.

3. Feeds

Each feed has a permanent ID: feedId = keccak256(symbol). Prices use 8 decimals.

4. The signed report

EIP-712 domain: name MarketAPI Oracle, version 2, the chain ID and the verifier address. Type:

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

• price: mid price with 8 decimals.
• timestamp: time of the price (UTC seconds); validUntil: the report expires after about a minute.
• marketStatus: 1 OPEN, 2 CLOSED (official last price, e.g. at weekends), 3 HALTED.
• spreadBps: bid-ask spread in basis points; with several brokers it also reflects how far apart they are.

The API answer contains report (ABI-encoded) and signature (65 bytes): exactly the two arguments of submit.

5. Contract functions

• submit(PriceReport r, bytes sig) returns (bool): verify and store; ignored if an equal or newer price is stored.
• submitBatch(PriceReport[] rs, bytes[] sigs): several feeds in one transaction; invalid entries are skipped.
• getPrice(bytes32 feedId): latest stored price and timestamp; reverts while a feed has no price yet.
• getPriceNoOlderThan(bytes32 feedId, uint256 maxAge): reverts unless the market is OPEN and the price is fresh enough. Use this for trading actions.

Each feed has a circuit breaker: a jump larger than its limit pauses the feed until it is reviewed.

6. Solidity example (pull pattern)

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 example (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. Refusals and errors

• refused entries list symbols that were not signed, with a reason, for example no reliable price right now (STALE) or a closed market. They are not billed.
• oracle_unavailable (503): the signing service is briefly unavailable; retry with back-off.
• On-chain reverts: InvalidSignature (wrong signer, chain or contract), ReportExpired, FutureTimestamp, InvalidPrice, InvalidStatus, NoPrice (feed has no price yet), FeedTripped (circuit breaker), MarketNotOpen and PriceTooOld (from getPriceNoOlderThan), IsPaused.

9. Best practices

• Fetch the report right before sending the transaction; reports expire after about a minute.
• Always read with getPriceNoOlderThan and a maximum age suited to your product.
• Handle CLOSED markets explicitly (weekends, holidays), for example settle at the next open.
• Test on the testnet first, then change only the contract address and chain ID.
• Keep API keys on your server, never in a web page.