Docs · 03

Reading scores

The bestVenue interface, return values and the staleness rule.

Final scores are exposed by the read contract. Calls are view-only and free; there is no allowlist, API key or fee for reading.

Interface

enum MarketState { Open, PrePost, Closed, Halt }

interface IPerigee {
    function bestVenue(address token, uint256 size, MarketState state)
        external
        view
        returns (address venue, uint16 scoreBps, uint64 reportedAt);
}

Parameters

Name	Meaning
`token`	Stock Token address.
`size`	Trade notional in USDG base units (6 decimals). Mapped to a size bucket.
`state`	Market state to query. Callers usually pass the current state of the underlying market.

Return values

Name	Meaning
`venue`	The eligible venue with the lowest score for the cell. `address(0)` if no venue has ever been scored for it, or if `state` is `Halt`.
`scoreBps`	Attested execution cost versus the mid, in bps, floored at 1. `0` means no fresh score.
`reportedAt`	Timestamp of the block in which the source report became final.

Staleness rule

A score older than 48 hours (measured from reportedAt to block.timestamp) is returned with scoreBps = 0. Selection prefers fresh scores; if no fresh score exists for the cell, the call returns the venue from the most recent final report with scoreBps = 0.

Callers must treat scoreBps == 0 as "no data", not as zero cost.

Example

(address venue, uint16 scoreBps, uint64 reportedAt) =
    perigee.bestVenue(stockToken, amountUsdg, MarketState.Open);

if (venue == address(0) || scoreBps == 0) {
    // No fresh attested score: fall back to your own routing or skip.
    revert NoFreshScore();
}
if (scoreBps > maxAcceptableBps) revert CostTooHigh(scoreBps);
// ...execute on `venue`

Notes

A score describes past execution over one reporting day. It is not a quote and does not guarantee a fill price.
Certification status has no effect on selection. Certified and uncertified venues are ranked on the same terms.
Additional views for per-venue scores and Merkle-proof verification of any leaf are part of the read contract and will be documented with its deployment.