Oráculo de precios para contratos inteligentes: divisas, oro, índices y acciones on-chain

Cómo funciona

1. Obtén un informe firmado: GET /oracle/report con tu clave API.
2. Envíalo en tu transacción: nuestro contrato verificador comprueba la firma con ecrecover.
3. Usa el precio verificado; recházalo si es demasiado antiguo para tu caso de uso.

Los informes son datos tipados EIP-712 PriceReport(bytes32 feedId,int256 price,uint64 timestamp,uint64 validUntil,uint8 marketStatus,uint32 spreadBps), ligados a una cadena y a un contrato verificador (sin reutilización en otro sitio) y aceptados solo hasta validUntil, alrededor de un minuto tras la firma (no se pueden acumular informes favorables). Los precios son el punto medio entre compra y venta con 8 decimales; spreadBps es el diferencial compra-venta. Cuando envías un informe en tu propia transacción, pagas ese gas. Nuestro relayer también guarda on-chain de vez en cuando las fuentes con demanda (lectura gratuita), pero comprueba siempre la antigüedad de un precio guardado.

Horario de mercado

Cada informe indica el estado del mercado: OPEN (un precio en vivo, de como máximo 60 segundos), CLOSED (el último precio oficial antes del cierre, igual para todos, firmado en cualquier momento mientras el mercado está cerrado) o HALTED (negociación suspendida). getPriceNoOlderThan solo devuelve precios OPEN, así un precio de cierre nunca puede pasar por uno en vivo. Los tokens respaldados por activos deberían liquidar las órdenes dadas con el mercado cerrado al siguiente precio OPEN (forward pricing, como hacen los fondos y ETF).

Cortacircuitos

Cada fuente puede tener un salto máximo permitido. Un movimiento mayor no se guarda: la fuente se pausa hasta que la hayamos revisado y reabierto, así un precio erróneo o manipulado nunca llega a tu contrato.

Fuentes

Redes

Dirección del firmante: 0x83fa2d8836525251FAd214A78A72038D0864f877. Lista legible por máquina: /oracle/feeds.

Integrar

1. Obtén un informe firmado

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

Devuelve report (la tupla codificada en ABI) y signature (65 bytes) por símbolo. Tu clave necesita el ámbito read:oracle.

2. Verifícalo en tu contrato

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 ...
    }
}

Los consumidores al estilo Chainlink pueden leer una fuente mediante el MarketApiFeedAdapter (latestRoundData(), AggregatorV3Interface).

Precios

5 crédito(s) por informe firmado, pagado(s) con tu saldo normal de la API. Leer precios ya guardados on-chain es gratis.

Casos de uso de nuestras fuentes de precios on-chain

• Activos tokenizados y RWA: pon precio a acciones tokenizadas, tokens respaldados por oro y otros activos del mundo real con datos de precios que tienen en cuenta el horario de mercado.
• Préstamos DeFi y colateral: valora colateral respaldado por divisas y materias primas con precios frescos y verificables y comprobaciones de antigüedad seguras para las liquidaciones.
• Activos sintéticos y divisas on-chain: liquida posiciones sintéticas de divisas, índices y materias primas contra precios de referencia firmados.
• Stablecoins y pagos: convierte entre divisas on-chain con tipos EUR/USD, GBP/USD y otros en vivo.

¿Por qué un oráculo pull firmado?

Los oráculos push se actualizan según un calendario y alguien paga gas por cada actualización. Con un oráculo pull tu contrato obtiene un precio fresco y firmado criptográficamente justo cuando lo necesita: menor coste, datos más frescos y la misma verificación on-chain. El estado del mercado, el diferencial compra-venta y la caducidad forman parte de cada informe firmado.

Recomendado: el patrón pull (precios siempre frescos)

No confíes en el precio ya guardado on-chain. Obtén un informe recién firmado y envíalo en la misma transacción que lo usa: tu contrato siempre ve el precio actual y solo pagas tus propias actualizaciones.

// 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)
    }
}

Los campos report y signature del informe que da la API son exactamente los dos argumentos de submit. Los informes son válidos alrededor de un minuto, así que obténlos justo antes de enviar la transacción.