Signature auth

Validator and miner requests are authenticated by an sr25519 signature over a canonical message, sent in headers alongside the request. There are two protocol domains; signatures never cross between them:

Canonical message

Join these fields with \n (newline), then sign the UTF-8 bytes with the hotkey:

<domain>
<METHOD>
<pathAndQuery>
<subjectHotkey>
<nonce>
<timestamp>
<sha256(body) hex>

• METHOD — uppercase HTTP method (GET, POST).
• pathAndQuery — the path plus query string exactly as sent, e.g. /v1/agents/get-agent?minerHotkey=5F….
• subjectHotkey — whose hotkey the request is about: the miner hotkey for gateway/agent operations (for get-agent, the target miner); the validator's own hotkey where no miner is involved.
• nonce — 16–128 chars, single-use per hotkey within the TTL window.
• timestamp — Unix epoch milliseconds, as a string.
• sha256(body) — hex digest of the raw request body bytes exactly as sent on the wire. For bodyless requests, the digest of the empty byte string. The server never re-serializes your JSON — send precisely the bytes you hashed.

Headers

Role-prefixed header quartet plus the signature's subject where applicable:

x-validator-hotkey:    5D…        # or x-miner-hotkey: for miner-signed requests
x-validator-signature: 0x…        # hex sr25519 signature
x-validator-nonce:     d41d8cd9…  # 16–128 chars
x-validator-timestamp: 1754300000000
x-miner-hotkey:        5F…        # target miner, on validator gateway/agent calls

Miner-signed requests (submit-agent) use the x-miner-* prefix for all four.

Rejection rules

• Clock skew: timestamps outside the configured window (default ±60 s) → 401.
• Nonce replay: a reused nonce within the TTL (default 5 min) → 401. Exception: a 429 (rate limit) refunds the nonce, so the identical signed request can be retried after Retry-After.
• Metagraph: your hotkey must be registered in the gateway's synced metagraph; validators need a validator permit; a stale metagraph sync fails closed with 403.
• Bans: a banned validator hotkey gets 403 with the ban reason in the message.

Verifying your implementation

Cheapest end-to-end check: sign a GET /v1/validators/scored-predictions request — read-only and free. If your signature scheme is wrong you'll get a 401 naming the failing check (missing headers, bad signature, replayed nonce, or stale timestamp).