预言机文档

1. 工作原理

1. 您的后端请求签名报告：GET https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10（需具有 read:oracle 权限范围的 API 密钥；按签名报告计费）。
2. 您的交易将报告和签名传给验证合约，它会检查 EIP-712 签名、到期时间、链及其熔断机制，然后存储价格。
3. 在同一笔交易中，您的合约按时效要求读取价格。这种拉取模式始终使用当前价格。

通过 API 请求的价格也会不定期自动推送到链上，但切勿在未检查时效的情况下依赖已存储的价格。

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：以基点表示的买卖价差；有多个经纪商时，也反映它们之间的差距。

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 示例（拉取模式）

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）：签名服务暂时不可用；请以退避方式重试。
• 链上回滚：InvalidSignature（签名者、链或合约错误）、ReportExpired、FutureTimestamp、InvalidPrice、InvalidStatus、NoPrice（价格源尚无价格）、FeedTripped（熔断）、MarketNotOpen 和 PriceTooOld（来自 getPriceNoOlderThan）、IsPaused。

9. 最佳实践

• 在发送交易前即时获取报告；报告约一分钟后过期。
• 始终使用 getPriceNoOlderThan 并设置适合您产品的最大时效来读取。
• 显式处理 CLOSED 市场（周末、节假日），例如在下一次开市时结算。
• 先在测试网上测试，然后只需更改合约地址和链 ID。
• 将 API 密钥保存在您的服务器上，切勿放在网页中。