Integration and contribution guide

The machine-readable index is at /api/v1.

Reads are public. Writes require a session established by signing a SIWE message. The message must use this site's domain, chain id 4663, a nonce issued by POST /api/v1/auth/nonce and an expiration within one hour. Signatures are verified server-side (EIP-1271 contract wallets included) and each nonce is single-use. The session is an HttpOnly cookie valid for seven days. Signing a message sends no transaction and moves no funds.

POST /api/v1/auth/nonce            → { nonce, domain, chainId, expiresAt }
sign SIWE message (viem createSiweMessage) with your wallet
POST /api/v1/auth/verify { message, signature } → sets kuxer_session cookie
POST /api/v1/proposals  (cookie)      → 201 { proposal, experiment, created, queue }

POST /api/v1/proposals accepts the fields below. parents lists validated proposal ids to inherit from; the baseline is always added as the first parent. The source must be a JavaScript ES module exporting solve(instance, ctx) (see the candidate contract). Send an Idempotency-Key header to make retries safe; an identical resubmission returns the existing proposal with created: false.

{
  "capabilityId": "cap_euclidean-tsp-v1",
  "baselineId": "bl_nearest-neighbor-v1",
  "parents": [],
  "title": "Nearest neighbor with 2-opt refinement",
  "summary": "Applies a deterministic 2-opt local search after nearest-neighbor construction.",
  "method": "Standard 2-opt with first-improvement moves until no improving swap exists or 80% of the deadline is used.",
  "source": "export function solve(instance, ctx) { /* ... */ }"
}

The response includes the queued INITIAL experiment. Poll GET /api/v1/proposals/{id} to follow status changes; the experiment's full harness result is available at GET /api/v1/experiments/{id} once it completes.

When the registry is deployed, a contributor can commit their proposal from their own wallet by calling commitProposal(id, contentHash, parents) on the registry, where id and each parent are keccak256(utf8(recordId)) (returned as chainKey) and contentHash is the proposal's contentHash. All parents must already be committed. Then report the transaction with POST /api/v1/proposals/{id}/anchor; the server verifies the receipt and event before recording it. Evaluations of anchored proposals are committed by the operator's evaluator signer and confirmed by the indexer.

• List endpoints use keyset pagination: pass limit (1–100, default 25) and the meta.nextCursor value as cursor. Cursors are opaque.
• Public GET responses carry Cache-Control with short s-maxage values; mutable records are not cached.
• The API is versioned by path. Breaking changes ship as /api/v2; schema changes are reflected in schemaVersion on each record. Every response includes an x-api-version header.

Exceeding a limit returns 429 rate_limited with details.retryAfterSeconds. Limits apply per wallet for writes and per IP for anonymous requests.

{
  "error": {
    "code": "validation_error",
    "message": "request failed validation",
    "details": [
      {
        "path": "summary",
        "message": "Too small: expected string to have >=10 characters"
      }
    ]
  }
}

Retry 429 and 503 with backoff and the same Idempotency-Key. Never retry 4xx validation failures without changing the request.