Documentación del oráculo

1. Cómo funciona

1. Tu backend solicita un informe firmado: GET https://api.marketapi.app/v1/oracle/report?symbols=XAUUSD&chain_id=10 (clave API con el ámbito read:oracle; se cobra por informe firmado).
2. Tu transacción pasa el informe y la firma al contrato verificador, que comprueba la firma EIP-712, la caducidad, la cadena y su cortacircuitos, y luego guarda el precio.
3. En la misma transacción tu contrato lee el precio con un requisito de antigüedad. Este patrón pull usa siempre el precio actual.

Los precios solicitados a través de la API también se envían on-chain automáticamente de vez en cuando, pero nunca confíes en un precio guardado sin comprobar su antigüedad.

2. Redes y contratos

Dirección del firmante: 0x83fa2d8836525251FAd214A78A72038D0864f877. Las testnets son para pruebas gratuitas sin garantías de servicio.

3. Fuentes

Cada fuente tiene un ID permanente: feedId = keccak256(symbol). Los precios usan 8 decimales.

4. El informe firmado

Dominio EIP-712: nombre MarketAPI Oracle, versión 2, el ID de cadena y la dirección del verificador. Tipo:

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

• price: precio medio con 8 decimales.
• timestamp: hora del precio (segundos UTC); validUntil: el informe caduca al cabo de un minuto aproximadamente.
• marketStatus: 1 OPEN, 2 CLOSED (último precio oficial, p. ej. los fines de semana), 3 HALTED.
• spreadBps: diferencial compra-venta en puntos básicos; con varios brókers refleja también cuánto difieren entre sí.

La respuesta de la API contiene report (codificado en ABI) y signature (65 bytes): exactamente los dos argumentos de submit.

5. Funciones del contrato

• submit(PriceReport r, bytes sig) returns (bool): verifica y guarda; se ignora si hay guardado un precio igual o más reciente.
• submitBatch(PriceReport[] rs, bytes[] sigs): varias fuentes en una transacción; las entradas no válidas se omiten.
• getPrice(bytes32 feedId): último precio guardado y su marca de tiempo; revierte mientras una fuente aún no tenga precio.
• getPriceNoOlderThan(bytes32 feedId, uint256 maxAge): revierte salvo que el mercado esté OPEN y el precio sea lo bastante reciente. Úsala para acciones de trading.

Cada fuente tiene un cortacircuitos: un salto mayor que su límite pausa la fuente hasta que se revise.

6. Ejemplo en Solidity (patrón 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. Ejemplo en 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. Rechazos y errores

• Las entradas refused listan los símbolos que no se firmaron, con un motivo, por ejemplo sin precio fiable ahora mismo (STALE) o un mercado cerrado. No se cobran.
• oracle_unavailable (503): el servicio de firma no está disponible un momento; reintenta con espera progresiva.
• Reverts on-chain: InvalidSignature (firmante, cadena o contrato incorrectos), ReportExpired, FutureTimestamp, InvalidPrice, InvalidStatus, NoPrice (la fuente aún no tiene precio), FeedTripped (cortacircuitos), MarketNotOpen y PriceTooOld (de getPriceNoOlderThan), IsPaused.

9. Buenas prácticas

• Obtén el informe justo antes de enviar la transacción; los informes caducan al cabo de un minuto aproximadamente.
• Lee siempre con getPriceNoOlderThan y una antigüedad máxima adecuada a tu producto.
• Gestiona de forma explícita los mercados CLOSED (fines de semana, festivos), por ejemplo liquidando en la siguiente apertura.
• Prueba primero en la testnet y luego cambia solo la dirección del contrato y el ID de cadena.
• Guarda las claves API en tu servidor, nunca en una página web.