面向智能合约的价格预言机：外汇、黄金、指数和股票上链

运作方式

1. 获取签名报告：使用您的 API 密钥调用 GET /oracle/report。
2. 在您的交易中提交它：我们的验证合约使用 ecrecover 检查签名。
3. 使用已验证的价格；如果对您的用例来说太旧，则拒绝它。

报告是 EIP-712 类型化数据 PriceReport(bytes32 feedId,int256 price,uint64 timestamp,uint64 validUntil,uint8 marketStatus,uint32 spreadBps)，绑定到一条链和一个验证合约（无法在别处重放），且仅在 validUntil 之前被接受，约为签名后一分钟（无法囤积有利报告）。价格为买价和卖价的中间价，保留 8 位小数；spreadBps 为买卖价差。当您在自己的交易中提交报告时，由您支付该 Gas。需求较大的价格源也会由我们的中继器不定期存储到链上（可免费读取），但请始终检查已存储价格的时效。

交易时段

每份报告都注明市场状态：OPEN（实时价格，最多 60 秒前）、CLOSED（收盘前的官方最后价格，对所有人相同，在休市期间任何时间签名）或 HALTED（交易暂停）。getPriceNoOlderThan 只返回 OPEN 价格，因此收盘价永远不会被当作实时价格。资产支持代币应按下一个 OPEN 价格结算休市期间提交的订单（远期定价，与基金和 ETF 的做法相同）。

熔断机制

每个价格源都可设置允许的最大跳动幅度。超出幅度的变动不会被存储：价格源会暂停，直到我们检查并重新开启，因此错误或被操纵的价格永远不会到达您的合约。

价格源

网络

签名者地址：0x83fa2d8836525251FAd214A78A72038D0864f877。机器可读列表：/oracle/feeds。

集成

1. 获取签名报告

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.marketapi.app/v1/oracle/report?symbols=EURUSD&chain_id=10"

每个代码返回 report（ABI 编码的元组）和 signature（65 字节）。您的密钥需要 read:oracle 权限范围。

2. 在您的合约中验证

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);  // verifies, stores if newer
    function getPriceNoOlderThan(bytes32 feedId, uint256 maxAge)
        external view returns (int256 price, uint64 timestamp);   // OPEN and fresh only, else reverts
    function getPrice(bytes32 feedId) external view
        returns (int256 price, uint64 timestamp, uint8 marketStatus, uint32 spreadBps);   // incl. CLOSED
}

contract MyVault {
    IMarketApiOracle immutable oracle;
    bytes32 constant EURUSD = keccak256("EURUSD");
    constructor(IMarketApiOracle o) { oracle = o; }

    function act(IMarketApiOracle.PriceReport calldata r, bytes calldata sig) external {
        oracle.submit(r, sig);                                       // reverts on a bad signature
        (int256 price, ) = oracle.getPriceNoOlderThan(EURUSD, 60);   // 8 decimals
        // ... use price ...
    }
}

Chainlink 风格的调用方可通过 MarketApiFeedAdapter（latestRoundData()，AggregatorV3Interface）读取价格源。

价格方案

每份签名报告 5 额度，从您正常的 API 余额中扣除。读取已存储在链上的价格是免费的。

我们链上价格源的应用场景

• 代币化资产与 RWA：使用考虑交易时段的价格数据，为代币化股票、黄金支持代币及其他现实世界资产定价。
• DeFi 借贷与抵押品：使用新鲜、可验证的价格以及可防止错误清算的时效检查，为外汇和大宗商品支持的抵押品估值。
• 合成资产与链上外汇：以签名参考价格结算合成外汇、指数和大宗商品头寸。
• 稳定币与支付：使用实时 EUR/USD、GBP/USD 及其他外汇汇率在链上进行货币兑换。

为什么选择签名拉取式预言机？

推送式预言机按计划更新，每次更新都有人支付 Gas。使用拉取式预言机，您的合约在需要时才获取新鲜的、经加密签名的价格：成本更低、数据更新鲜，且链上验证不变。市场状态、买卖价差和到期时间都包含在每份签名报告中。

推荐：拉取模式（价格始终最新）

不要依赖链上已存储的价格。获取新签名的报告，并在使用它的同一笔交易中提交：您的合约始终看到当前价格，而您只需为自己的更新付费。

// 1) off-chain: GET https://api.marketapi.app/v1/oracle/report?symbols=EURUSD&chain_id=CHAIN_ID  (header: Authorization: Bearer KEY)
// 2) on-chain: verify, store and use the report atomically
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 MyVault {
    IMarketApiOracle immutable oracle;
    bytes32 constant EURUSD = keccak256("EURUSD");
    constructor(IMarketApiOracle o) { oracle = o; }

    function settle(IMarketApiOracle.PriceReport calldata r, bytes calldata sig) external {
        oracle.submit(r, sig);                                         // ignored if an equal/newer price is stored
        (int256 price, ) = oracle.getPriceNoOlderThan(EURUSD, 60);    // reverts unless OPEN and fresh
        // ... use price (8 decimals)
    }
}

API 返回报告中的 report 和 signature 字段正是 submit 的两个参数。报告有效期约一分钟，因此请在发送交易前即时获取。