Public API

The public API serves the Sealroom registry, indexed from the chain, and builds the transactions your wallet signs. It never holds keys or submits transactions for you.

Base URL

<api-url>

All routes are under /v1, except /health. Requests and responses are JSON. The contract version is 1.0.0, reported in every response.

Response envelope

Every response has the same shape:

{ "ok": true, "data": { }, "meta": { } }

{ "ok": false, "error": { "code": "NOT_FOUND", "message": "Resource not found.", "retryable": false }, "meta": { } }

meta describes the read:

Formats

Use big-integer arithmetic for amounts.

Health

GET /health returns status (ok), mode (live), contractVersion, database and chain (connected or degraded).

Parameters

GET /v1/parameters returns the settings the program and services run with. Single settings have the form { "status": "set", "value": …, "source": "chain" }.

Summary

GET /v1/summary returns operators, attestedNodes, models, openLanes, totalDistributed (base units) and openDisputes.

Resources

Every record from the chain has an id (its account address) and a chain reference with the slot, transaction signature and observedAt time of its latest change.

On a resource's own list, its id filter matches the record id: GET /v1/models?modelId=<account> returns that model. Filters are exact matches, and a filter a resource does not support returns VALIDATION_ERROR. Each list also accepts q, a case-insensitive search over the record's name, endpoint, image name, summary or id.

Status values:

GET /v1/attestations/{id} returns the latest revision of that attestation. activity kinds include model_created, lane_opened, lane_payment, distribution, attestation_recorded, attestation_revoked, attestation_expired, key_released, key_denied, bond_deposited, unbond_requested, split_proposed, split_applied, dispute_opened, dispute_ruled and claim_paid, among others.

Pagination

Lists return a page:

{ "items": [ ], "nextCursor": "eyJvZmZzZXQiOjIw…", "total": 57 }

nextCursor is null on the last page. A cursor belongs to its resource and filters: keep the same query and change only cursor.

curl "<api-url>/v1/lanes?modelId=<model>&status=open&limit=50"

Eligibility

GET /v1/eligibility?modelId=<model>&nodeId=<node> returns eligible, checkedAt, the attestationId and attestationRevision it used, reasons (the codes that failed) and checks, one per rule:

{ "code": "bond_below_min", "passed": true, "message": "Operator bond must meet the model and protocol tier minimums.", "actual": "1000000000", "required": "100000000" }

The rule codes are no_valid_attestation, attestation_expired, attestation_revoked, runtime_not_allowed, platform_not_registered, tier_below_min, bond_below_min, operator_frozen, operator_not_on_allowlist, tcb_not_up_to_date, node_disabled and protocol_paused.

Transaction previews

POST /v1/transactions/preview takes one wallet intent and returns the exact transaction to sign. Every intent has an action and an authority: the wallet that signs and pays the network fee.

Intents

price is { "scheme": "exact", "perCall": "25000" } or { "scheme": "upto", "inputPerMillionTokens": "…", "outputPerMillionTokens": "…", "maxPerCall": "…" }. A split is 1 to 8 entries { recipientAta, recipientOwner, bps, locked, role } with distinct canonical USDC accounts, summing to 10,000 bps. role is owner, operator, base_model or contributor. Include recipientOwner for any recipient whose USDC account does not exist yet: the transaction creates it.

curl -X POST "<api-url>/v1/transactions/preview" \
  -H "Content-Type: application/json" \
  -d '{"action":"distribute","authority":"<your wallet>","laneId":"<lane>"}'

Preview response

When blockedBy is not empty, serializedTransaction is null and message says what to do.

Preview blockers

Applications

POST /v1/applications receives operator and model-owner applications from the form at https://sealroom.cloud/apply. It needs an Idempotency-Key header (16 to 128 letters, digits, _ or -) and the form's anti-abuse token. Sending the same key and body again returns the same receipt: id, status (received), confirmation and receivedAt.

Errors

Every error has retryable, which is true for 429 and 5xx responses. The TypeScript client adds NETWORK_ERROR, TIMEOUT, CANCELLED and INVALID_RESPONSE for failures before a valid response arrives.

Rate limits

POST /v1/transactions/preview and POST /v1/applications share a limit of 20 requests per minute for each client address, counted in one-minute windows. A request over the limit returns 429 RATE_LIMITED with Retry-After. Reads are not rate limited.

Headers

Query parameters appear once each; a repeated parameter returns VALIDATION_ERROR.