Skip to main content

Using the Validator & SN Owner APIs

This guide shows how to interact with the two HTTP APIs in the BlockZero subnet: the Validator API (model distribution and checkpoint submission) and the SN Owner Phase API (cycle timing and phase coordination).

SN Owner Phase API​

The SN owner runs a lightweight phase service that all participants query to determine the current training phase.

Check the current phase​

curl http://<owner_ip>:<owner_port>/get_phase

Response:

{
  "block": 54321,
  "cycle_length": 45,
  "cycle_index": 1207,
  "cycle_block_index": 6,
  "phase_name": "Train",
  "phase_index": 1,
  "phase_start_block": 54320,
  "phase_end_block": 54339,
  "blocks_into_phase": 1,
  "blocks_remaining_in_phase": 18
}

Check when the next phase starts​

curl http://<owner_ip>:<owner_port>/blocks_until_next_phase

Each entry returns [start_block, end_block, blocks_until].

Get DHT bootstrap peers​

curl http://<owner_ip>:<owner_port>/get_init_peer_id

Returns a list of multiaddresses for bootstrapping inter-validator connections.

See the SN Owner Phase API Reference for full endpoint documentation.

Validator API​

The validator runs a FastAPI server for model distribution and checkpoint submission. All endpoints except /health require Bearer token authentication.

Health check​

curl https://<validator_host>:8080/health

Response:

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

Download your expert group (miners)​

During the Distribute phase, miners download their assigned expert group:

curl -H "Authorization: Bearer <BZ_AUTH_TOKEN>" \
     -H "X-Expert-Group: 0" \
     -H "X-Hotkey: <your_ss58_hotkey>" \
     https://<validator_host>:8080/model/partial \
     -o expert_group_0.pt

The response includes metadata headers (expert_group, block_number, model_version, content_hash) followed by binary tensor data.

Submit a checkpoint (miners)​

During the Submit phase, miners upload their trained checkpoint:

curl -X POST https://<validator_host>:8080/submit \
     -H "Authorization: Bearer <BZ_AUTH_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "hotkey": "<your_ss58_hotkey>",
       "expert_group": 0,
       "checkpoint_url": "https://your-server.com/checkpoint.pt",
       "block_number": 12345,
       "signature": "<url-safe-base64-ed25519-signature>"
     }'

Response (202 Accepted):

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

Download the full model (validators)​

Peer validators can download the complete model:

curl -H "Authorization: Bearer <BZ_AUTH_TOKEN>" \
     https://<validator_host>:8080/model/full \
     -o full_model.safetensors

Restricted to registered validators. Returns 403 Forbidden if the requester is not a validator.

Get a specific checkpoint (external clients)​

External clients can request model checkpoints, optionally filtered by expert group:

# Full checkpoint
curl -H "Authorization: Bearer <BZ_AUTH_TOKEN>" \
     https://<validator_host>:8080/get-checkpoint

# Specific expert group
curl -H "Authorization: Bearer <BZ_AUTH_TOKEN>" \
     -F "expert_group_id=0" \
     https://<validator_host>:8080/get-checkpoint

# Shared parameters only
curl -H "Authorization: Bearer <BZ_AUTH_TOKEN>" \
     -F "expert_group_id=shared" \
     https://<validator_host>:8080/get-checkpoint

See the Validator HTTP API Reference for full endpoint documentation.

Common Patterns​

Polling for phase transitions​

A typical miner or monitoring script polls the phase service to coordinate actions:

import requests
import time

OWNER_URL = "http://<owner_ip>:<owner_port>"

while True:
    phase = requests.get(f"{OWNER_URL}/get_phase").json()
    print(f"Block {phase['block']}: {phase['phase_name']} "
          f"({phase['blocks_remaining_in_phase']} blocks remaining)")

    if phase["phase_name"] == "Distribute":
        # trigger model download
        pass
    elif phase["phase_name"] == "Submission":
        # trigger checkpoint submission
        pass

    time.sleep(12)  # ~1 block

Authentication​

All validator API calls (except /health) require a Bearer token:

Authorization: Bearer <BZ_AUTH_TOKEN>

Set the token via the BZ_AUTH_TOKEN environment variable on the validator. Share this token with authorized miners.