Validator HTTP API

The validator runs a FastAPI server exposing endpoints for model distribution, checkpoint submission, and health monitoring.

Authentication

All endpoints except GET /health require Bearer token authentication:

Authorization: Bearer <BZ_AUTH_TOKEN>

Requests with missing or invalid tokens receive 401 Unauthorized.

---

GET /model/partial

Returns the expert group slice for the requesting miner.

Request headers

Authorization: Bearer <token>
X-Expert-Group: 0
X-Hotkey: 5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty

Header	Required	Description
Authorization	yes	Bearer token
X-Expert-Group	yes	Integer expert group ID
X-Hotkey	yes	Miner's SS58 hotkey address

Response

JSON metadata header followed by binary tensor data:

{
  "expert_group": 0,
  "block_number": 12345,
  "model_version": "step_1000",
  "content_hash": "sha256:abcdef1234..."
}

Field	Description
expert_group	Expert group ID of the returned slice
block_number	Chain block at which this model version was snapshotted
model_version	Human-readable model version identifier
content_hash	SHA-256 hash of the binary payload for integrity verification

Status codes

Code	Meaning
200 OK	Success — body contains expert group tensor data
401 Unauthorized	Missing or invalid auth token
404 Not Found	Requested expert group does not exist
503 Service Unavailable	Model has not finished loading

---

GET /model/full

Returns the complete model for peer validators. Restricted to callers registered as validators on the subnet.

Request headers

Authorization: Bearer <token>

Response

Full model weights streamed as a safetensors file (~60GB for Qwen3-VL-30B).

Status codes

Code	Meaning
200 OK	Success — body is the streamed safetensors model
401 Unauthorized	Missing or invalid auth token
403 Forbidden	Requester hotkey is not registered as a validator

---

POST /submit

Accepts a miner checkpoint submission during the submit phase.

Request body — application/json

{
  "hotkey": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty",
  "expert_group": 0,
  "checkpoint_url": "https://miner-server.example.com/checkpoint_500_12345.pt",
  "block_number": 12345,
  "signature": "url-safe-base64-encoded-ed25519-signature"
}

Field	Required	Description
hotkey	yes	Miner's SS58 Bittensor hotkey
expert_group	yes	Expert group ID the checkpoint was trained for
checkpoint_url	yes	URL from which the validator can fetch the checkpoint
block_number	yes	Chain block at which the training cycle ended
signature	yes	URL-safe base64-encoded ed25519 signature over the submission fields

Response — 202 Accepted

{
  "status": "accepted",
  "submission_id": "550e8400-e29b-41d4-a716-446655440000",
  "evaluation_eta_blocks": 5
}

Status codes

Code	Meaning
202 Accepted	Queued for evaluation
400 Bad Request	Malformed body or invalid signature
409 Conflict	Duplicate submission for this hotkey + block
423 Locked	Not currently in submit phase

---

GET /health

Health check. No authentication required.

Response — 200 OK

{
  "status": "healthy",
  "model_loaded": true,
  "current_block": 12345,
  "phase": "train"
}

Field	Description
status	"healthy" when operating normally
model_loaded	true once the base model has finished loading
current_block	Most recently observed chain block number
phase	Current subnet phase: "distribute", "train", "commit", or "submit"