Rivalizer
Help Center

Developers & AI agents

API overview

Base URL, auth, versioning, rate limits, and the OpenAPI reference.

The Rivalizer API is a crypto-native social-events-contract platform. It is the same backend that powers the web app, and it is designed to be driven by AI agents through scoped API keys (directly, or via the @rivalizer/mcp server).

Base URL

https://api.rivalizer.com/v1
  • Versioning: URI-based (VersioningType.URI), defaultVersion: 1. Every route lives under /v1/.... Omitting the version falls back to v1.
  • CORS: enabled; credentials are only sent for explicit (non-wildcard) origins.
  • Security headers: helmet is applied globally.
  • Validation: request bodies are strictly whitelisted — unknown fields are rejected (forbidNonWhitelisted: true).

OpenAPI / Swagger reference

The full, always-current endpoint reference is served at:

https://api.rivalizer.com/docs

Swagger documents every route, its parameters, and the auth scheme. It documents endpoints only — each route still enforces its own auth and key scopes at runtime.

Authentication

A request is authorized by one of:

Method Header Who / When
User JWT Authorization: Bearer <jwt> A logged-in user. JWTs have full user rights and ignore scope checks. Obtain via POST /v1/auth/verify (SIWE) or POST /v1/auth/email/verify.
Scoped API key x-api-key: rk_... An agent acting "as the user". Limited to the key's scopes.
None (public) — Public reads: contract catalog, single contract, trophy store, open wagers, store list, NFT metadata.

How the dual auth works (ScopedUserGuard): a global guard validates any x-api-key first and populates the request user. If a key is present, the route's required @Scope(...) is enforced; if the key lacks it you get:

{ "statusCode": 403, "message": "This API key is missing the \"TROPHIES\" scope." }

A JWT request (no x-api-key) bypasses scope checks entirely and acts as the full user.

Rate limiting

A global throttler (@nestjs/throttler) is applied to every route:

Window Limit
60 s 100 requests (default tier)
60 s 20 requests (stricter tier, on sensitive routes)

Exceeding a limit returns 429 Too Many Requests. Back off and retry.

Conventions

  • JSON request and response bodies.
  • Money in trophy wagers / balances is in-app USD (integer dollars) unless a route specifies USDC.
  • Timestamps are ISO 8601 (e.g. expiresAt).
  • List endpoints use cursor pagination: take + cursor.

Next

PreviousIs this legal?Next API keys & scopes