Introduction

The 2QUIC Marketplace exposes a REST API for browsing validators, booking SWQoS leases, paying them via Solana Pay, and minting the short-lived signing JWTs your SDK presents to the TEE. The contract is an OpenAPI 3.1 document generated directly from the handler code via utoipa. It is committed at docs/openapi.json in the repository and served live by the API itself:

curl https://api.swqos.dev/v1/openapi.json

A CI drift gate regenerates the spec on every build, so the document always matches the deployed handlers.

Base URLs

Versioning

Every route lives under the /v1 path prefix (the path is /v1/..., not /api/v1/...). Successful responses also carry the envelope version "1.0" in meta.version.

Response envelope

Every successful JSON response wraps its payload in the same envelope:

{
  "data": { },
  "meta": {
    "request_id": "01JXF8Z3V0Q2YT5M9W4R7K2D6E",
    "version": "1.0"
  }
}

• data carries the endpoint-specific payload.
• meta.request_id is a ULID unique to the request. Include it in support requests and bug reports.

Errors do not use the envelope. They are flat RFC 7807 Problem Details documents served with Content-Type: application/problem+json, and the type field is a stable URI ending in a slug you can switch on. The full slug catalogue lives on the errors page.

Pagination

List endpoints use opaque cursors. The page and its cursor nest inside the envelope's data:

{
  "data": {
    "data": [ ],
    "next_cursor": "opaque-cursor-or-null"
  },
  "meta": {
    "request_id": "01JXF8Z3V0Q2YT5M9W4R7K2D6E",
    "version": "1.0"
  }
}

Pass next_cursor back as the cursor query parameter to fetch the next page. A null cursor means you reached the end. Limits are per endpoint: GET /v1/validators accepts limit 1 to 50 (default 20), the admin audit log accepts 1 to 200 (default 50). A bad value returns 400 invalid-limit, and a cursor the server did not mint returns 400 invalid-cursor.

Idempotency

Exactly three endpoints require an Idempotency-Key header:

• POST /v1/leases
• POST /v1/leases/{id}/extend
• POST /v1/validators/{id}/leases/{lease_id}/revoke

The key must be a 26-character Crockford-base32 ULID. Generate a fresh one per logical operation and reuse the same one on retries:

curl -X POST https://api.swqos.dev/v1/leases \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Idempotency-Key: 01JXF8Z3V0Q2YT5M9W4R7K2D6E" \
  -H "Content-Type: application/json" \
  -d '{"validator_id": "...", "epoch_start": 820, "epoch_count": 5}'

Keys are scoped per user, method, path, and key, and the replay cache is Redis-backed. The exact semantics:

Only 200/201 responses enter the 24-hour replay cache. Error responses never get cached, so a failed booking can always be retried with the same key.

Rate limits

Limits are enforced fleet-wide with a Redis token bucket, per endpoint class:

Limited routes always return X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. On deny you get a 429 rate-limit-exceeded problem document plus a Retry-After header. GET /v1/health and GET /v1/openapi.json are exempt.

Endpoint inventory

The tables below mirror the live router. The machine-readable version of the same inventory is the OpenAPI document at GET /v1/openapi.json.

Public (no authentication)

The Solana Pay endpoints take no bearer token. The unguessable ULID memo issued at booking is the capability.

Trader (bearer token: Clerk session or API token)

Full request and response contracts on the trader endpoints page.

Validator

Full contracts on the validator endpoints page. Registration and payout-wallet changes authenticate with a signed Ed25519 challenge (nonce, timestamp, and signature over the request fields), not a bearer token. Everything else uses the bearer schemes above.

Admin

Five staff-only routes exist under /v1/admin/ (validator suspend, validator takedown, lease revoke, audit log, reputation recompute). They authenticate with a Clerk session whose organization role grants staff access, and takedown requires the Admin tier. They are operational tooling and are not documented further here.

Next steps