Run a completion via the gateway (validator auth)

Authenticated by a Bittensor validator's sr25519 signature over the newline-joined canonical message `sub41-gateway-v1\nMETHOD\npathAndQuery\nminerHotkey\nnonce\ntimestamp\nsha256(body) hex`. The body hash covers the request body exactly as sent on the wire (raw bytes) — send precisely the bytes you hashed; the server never re-serializes. The billed org is resolved from `x-miner-hotkey` via `OrgMiner` / `SubnetRegistration`. Replayed nonces and stale metagraph reads fail closed.

POST/v1/gateway/validator/completions

Authorization

validator-auth

x-validator-signature<token>

Bittensor validator sr25519 signature. Also send x-validator-hotkey, x-validator-nonce, x-validator-timestamp (and x-miner-hotkey on the gateway proxy route).

In: header

Header Parameters

Idempotency-Key?string

Optional client-chosen key (1–255 chars), scoped to the billed org. A repeat request with a key that already produced a successful completion is rejected with 409 and no provider call or debit occurs. Failed calls do not consume the key. Note: this header is not part of the signed canonical message.

x-miner-hotkey*string

SS58 hotkey of the miner whose org should be billed. Must be registered via POST /miners.

x-validator-timestamp*string

Unix epoch milliseconds. Rejected outside the configured clock-skew window.

x-validator-nonce*string

16–128 char nonce. Single-use per validator within the TTL window.

x-validator-signature*string

Hex-encoded sr25519 signature over the canonical message.

x-validator-hotkey*string

SS58 hotkey of the signing validator (must hold a validator permit in the synced metagraph).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider*string

Provider identifier

model*string

messages*array<>

maxTokens?number

Range1 <= value <= 128000

temperature?number

Range0 <= value <= 2

topP?number

Range0 <= value <= 1

stop?array<string>

minerHotkey?string

Optional miner hotkey override (api-key flow only).

Response Body

`application/json`

curl -X POST "https://example.com/v1/gateway/validator/completions" \  -H "x-miner-hotkey: string" \  -H "x-validator-timestamp: string" \  -H "x-validator-nonce: string" \  -H "x-validator-signature: string" \  -H "x-validator-hotkey: string" \  -H "Content-Type: application/json" \  -d '{    "provider": "openrouter",    "model": "anthropic/claude-3.5-sonnet",    "messages": [      {        "role": "system",        "content": "Hello!"      }    ]  }'

{  "provider": "openrouter",  "model": "anthropic/claude-3.5-sonnet",  "output": "The market is likely to resolve YES because…",  "usage": {    "promptTokens": 412,    "completionTokens": 187,    "totalTokens": 599,    "cacheReadInputTokens": 2048,    "cacheCreationInputTokens": 0,    "costUsd": 0.00342  },  "costMicro": "12500",  "providerCostMicro": "10000",  "markupBps": 2500,  "balanceAfterMicro": "987500"}