GraphQL API

Quick start

Every request is a POST with an operationName and a variables object. Raw query text is rejected — the GraphQL document for each operation lives on the server and is selected by name. Advanced clients may send operationId instead, but not together with operationName.

The beta endpoint is public and does not require an API key. It is still constrained to the persisted operations and variable caps listed below. Usehttps://graphql.borosexplorer.com as the canonical public URL.

curl -s https://graphql.borosexplorer.com \
  -H 'content-type: application/json' \
  --data '{"operationName":"MarketDirectory","variables":{"status":"live","limit":10,"offset":0}}'

Playground

Try any operation directly from this page. Pick a name, fill the variables, and run it against the live endpoint.

query ApiInfo {
  api_info(limit: 1) {
    api_name
    schema_version
    release_channel
    read_only
    public_unauthenticated
    generated_at
  }
}

Click Run to see a live response.

Operations

Every accepted operation is listed below with its root response key, variables, and bounds. Inputs use camelCase variable names such as marketId, fromTs, and toTs. Calls outside these bounds are rejected with a 400 before reaching the GraphQL backend. A ! suffix marks a required variable; = marks the default when omitted. Status filters accept live, pending, and expired.

Read models

Operations select from the models below. The public response root key is the key under data; the underlying view name is included for provenance.

Conventions

Conventions that hold across every operation:

• Names. Input variables use camelCase. Output fields mirror the underlying read models and are snake_case.
• Units. APR fields are decimals (0.0521 = 5.21%). Output time fields ending in _at are UTC ISO strings. Input window variables fromTs and toTsmust be Unix epoch seconds, not ISO strings or JavaScript milliseconds.
• Pagination. Row-returning operations that list a limit variable also accept offset. Offset pagination on live trade and liquidation ledgers is best-effort because new rows can land between requests. Trades are ordered by block_timestamp desc, id desc; liquidations by block_timestamp desc, block_number desc, log_index desc.
• Freshness. Use Freshness when you need a global staleness check without pulling market rows. It accepts no variables and returns the fixed source set.
• Caching. Successful identical operation + variables responses are cached for the TTL listed per operation. Cache state is exposed through the X-Boros-GraphQL-Cache response header.

Errors

Validation errors from this endpoint return { "error": { "message": "..." } }. Backend execution errors are normalized to the same envelope instead of exposing backend-specific paths.