HYBRID-CHAINDEVELOPERS
DOCUMENTATIONv2
GET

Arena administration

List live evidence events

/api/v2/admin/arena/events
AUTHENTICATIONBearer token · arena:admin:readAUTHORITATIVE OWNERarena-engineCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

Resume the authenticated tenant's ordered Arena evidence feed without replaying already observed records or exposing private engine authority.

WHEN THIS CALL IS USEFUL

Call this after an Arena overview or prior event page when an operator needs the next bounded set of match, market, wager, adjudication, or proof-assurance events.

OUTCOME · Observe evidence continuity

What changes

Read-only. Cursor use does not acknowledge, mutate, adjudicate, publish, settle, or retain a new Arena event.

WHY IT MATTERS

  • Supports incremental operational monitoring without duplicate event delivery.
  • Preserves tenant and request-target integrity across resumable reads.

ISOLATION + AUTHORITY

Gateway reauthorizes both scopes, binds the exact ordered private request target into a one-use signature, and verifies the engine's actor and tenant echoes before returning data.

BEFORE YOU CALL

  • A validated Hybrid Identity bearer with both admin:read and arena:admin:read.
  • The exact opaque after cursor returned for the same tenant and a limit from 1 through 100.

WHAT TO DO NEXT

  • Persist only the returned next cursor for the same filter context.
  • Refresh the overview when an event indicates a phase, market, payout, or assurance change.

AGENT GUIDANCE

  • Return the opaque afc1 cursor unchanged and never construct one from an event sequence.
  • Keep elapsed_ms, limit, and cursor bounded; a cursor from another tenant or simulation position must fail closed.
  • Use event commitments for audit continuity, not as a claim of chain publication, settlement, or financial finality.
MACHINE CONTRACT

The exact deployed parameters, schemas, responses, security requirements, and Hybrid-Chain agent metadata are authoritative at this operation's production OpenAPI JSON Pointer. The readable tables below add integration guidance; the deployed OpenAPI controls if guidance and the machine contract ever differ.

Open the authoritative production contract ↗

EXTENDED INTEGRATION GUIDANCE

Readable request and response reference

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE
AuthorizationheaderRequired

Bearer tokenCredential containing arena:admin:read authority.EXAMPLEBearer hc_live_…

elapsed_msqueryOptional

integer · int64 · nullableDeterministic D0 simulation position in milliseconds, from 0 through 24000.Schema range: 0 to 24000EXAMPLE12000

afterqueryOptional

string · nullableOpaque tenant-bound cursor returned by the preceding event page.

limitqueryOptional

integer · 1–200 · nullableMaximum records returned, from 1 through 100. Defaults to 50.Schema range: 1 to 100EXAMPLE50

X-Request-IDheaderOptional

stringOptional caller correlation identifier. The gateway emits the effective value on the response.

RESPONSES

Status and payload examples

200Read-only resumable Arena evidence feed. Cursors are opaque, tenant-bound, and validated again by the Arena engine; records remain synthetic until canonical game ingestion and Hybrid proof publication are enabled.Read completed · JSON RESPONSE+
{
  "data": "example-data",
  "success": true
}
INTEGRATION DECISION
CALLER ACTION
Accept the returned representation or receipt, then persist only the returned next cursor for the same filter context.
RETRY SAFETY
Repeat only when the integration needs a fresher authoritative projection.
STATE RECONCILIATION
Use returned identifiers and versions as the comparison point for later reads. Refresh the Arena overview and event feed for the same tenant, then verify match lifecycle, evidence sequence, settlement state, payout totals, and viewer counts before retrying a monitoring request.
401Bearer credential is missing, expired, or invalid.Authentication required · JSON RESPONSE+
{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}
INTEGRATION DECISIONinvalid_credentials
CALLER ACTION
Discard the rejected credential, complete the documented authentication or reassertion flow, and rebuild any request signature with fresh timestamps and nonces.
RETRY SAFETY
Retry only with a newly valid credential and fresh replay-protection values. Do not replay an expired signature.
STATE RECONCILIATION
Authentication failed before an authoritative read was returned for tenant-scoped Arena match, participant, audience, wager, event, evidence, settlement, and payout projections.
ESCALATE WHEN
Escalate when tenant binding, administrator scopes, event continuity, evidence finality, settlement totals, or payout projections remain inconsistent after a fresh read.
403The principal lacks the required scope, role, tenant, or step-up authority.Authority or policy denied · JSON RESPONSE+
{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}
INTEGRATION DECISIONinvalid_credentials
CALLER ACTION
Verify the exact scope, tenant or workspace membership, owner boundary, step-up purpose, feature policy, and resource eligibility. Never broaden authority automatically.
RETRY SAFETY
Do not retry until the missing authority or policy condition has been deliberately resolved with least privilege.
STATE RECONCILIATION
Confirm the caller and resource resolve to the same authority boundary for tenant-scoped Arena match, participant, audience, wager, event, evidence, settlement, and payout projections.
ESCALATE WHEN
Escalate when tenant binding, administrator scopes, event continuity, evidence finality, settlement totals, or payout projections remain inconsistent after a fresh read.
422The elapsed position, limit, or cursor shape is invalid.Request must change · JSON RESPONSE+
{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}
INTEGRATION DECISIONinvalid_credentials
CALLER ACTION
Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY
Do not retry the same invalid request. A corrected read may be sent as a new attempt.
STATE RECONCILIATION
Compare the submitted values with the documented constraints before another call. Refresh the Arena overview and event feed for the same tenant, then verify match lifecycle, evidence sequence, settlement state, payout totals, and viewer counts before retrying a monitoring request.
ESCALATE WHEN
Escalate when tenant binding, administrator scopes, event continuity, evidence finality, settlement totals, or payout projections remain inconsistent after a fresh read.
502Arena returned a malformed or authority-mismatched event feed.Dependency unavailable or outcome uncertain · JSON RESPONSE+
{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}
INTEGRATION DECISIONinvalid_credentials
CALLER ACTION
Treat the failure as transient and preserve the last known good representation without presenting it as fresh.
RETRY SAFETY
Retry with bounded exponential backoff and jitter; stop after the integration's failure budget is exhausted.
STATE RECONCILIATION
Refresh the Arena overview and event feed for the same tenant, then verify match lifecycle, evidence sequence, settlement state, payout totals, and viewer counts before retrying a monitoring request.
ESCALATE WHEN
Escalate when tenant binding, administrator scopes, event continuity, evidence finality, settlement totals, or payout projections remain inconsistent after a fresh read.
503The authoritative service or read model is unavailable.Dependency unavailable or outcome uncertain · JSON RESPONSE+
{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}
INTEGRATION DECISIONinvalid_credentials
CALLER ACTION
Treat the failure as transient and preserve the last known good representation without presenting it as fresh.
RETRY SAFETY
Retry with bounded exponential backoff and jitter; stop after the integration's failure budget is exhausted.
STATE RECONCILIATION
Refresh the Arena overview and event feed for the same tenant, then verify match lifecycle, evidence sequence, settlement state, payout totals, and viewer counts before retrying a monitoring request.
ESCALATE WHEN
Escalate when tenant binding, administrator scopes, event continuity, evidence finality, settlement totals, or payout projections remain inconsistent after a fresh read.

OPERATIONAL NOTES

Security and lifecycle guarantees

  • Authenticate an administrator through Identity, require both admin:read and arena:admin:read, and page through tenant-scoped read-only Arena evidence events with an opaque cursor. The Gateway narrows authority before signing the private Arena request; it never forwards the user's bearer to the engine.
  • The Rust gateway validates the public contract and routes only to the authoritative owner; clients never address internal services directly.
  • The tables and examples are derived from the current gateway source OpenAPI. Re-fetch the deployed OpenAPI before execution; deployment status is shown separately on this page.
  • Only parameters present in the OpenAPI operation are accepted; undocumented query keys fail closed with HTTP 422.
DOCUMENTATION STATUS

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-09-11T06:35:11.572Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation ↗Return to the V2 directory ↗