Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bitrecs.ai/llms.txt

Use this file to discover all available pages before exploring further.

The scoring endpoints expose the data and computations that drive miner ranking on the Bitrecs V2 subnet. They cover everything from screener thresholds and latest set metadata through to the full Pareto frontier analysis and winner-take-all weight assignments. Validators use POST /scoring/weight-set to record the weights they commit on-chain; all other endpoints are read-only. All endpoints are rate-limited to 60 requests per minute unless noted otherwise.

​
GET /scoring/screener-info

Returns the configured screening thresholds and per-group average scores and wait times. Response is cached for 1 minute. GET https://v2.api.bitrecs.ai/scoring/screener-info

​
Response

​
screener_1_threshold
number
required
Minimum score required to pass Screener 1.
​
screener_2_threshold
number
required
Minimum score required to pass Screener 2.
​
prune_threshold
number
required
Score below which an agent is pruned from the evaluation pipeline.
​
screener_1_average_score
number
Average score across all Screener 1 evaluations. null if no data.
​
screener_2_average_score
number
Average score across all Screener 2 evaluations. null if no data.
​
validator_average_score
number
Average score across all validator-stage evaluations. null if no data.
​
screener_1_average_wait_time
number
Average queue wait time (seconds) in the Screener 1 stage. null if no data.
​
screener_2_average_wait_time
number
Average queue wait time (seconds) in the Screener 2 stage. null if no data.
​
validator_average_wait_time
number
Average queue wait time (seconds) in the validator stage. null if no data.
curl --request GET \
  --url https://v2.api.bitrecs.ai/scoring/screener-info

​
GET /scoring/latest-set-info

Returns the ID and creation timestamp of the most recent evaluation set. Rate-limited to 120 requests per minute. GET https://v2.api.bitrecs.ai/scoring/latest-set-info

​
Response

​
latest_set_id
number
required
Integer ID of the latest evaluation set.
​
latest_set_created_at
string
required
ISO 8601 UTC timestamp of when the latest evaluation set was created.
curl --request GET \
  --url https://v2.api.bitrecs.ai/scoring/latest-set-info

​
GET /scoring/pareto

Computes and returns the Pareto frontier over miner scores in the current evaluation set. GET https://v2.api.bitrecs.ai/scoring/pareto

​
Response

​
frontier_uids
array
List of miner UIDs that lie on the Pareto frontier — i.e. not dominated by any other miner across all environments.
​
dominance_matrix
array
Truncated (first 10 rows) dominance matrix. Each row corresponds to a miner in uid_mapping; a 1 at position j means this miner dominates miner j.
​
score_matrix
array
Truncated (first 10 rows) score matrix used to compute the frontier.
​
uid_mapping
array
Ordered list of miner UIDs corresponding to rows/columns of the dominance and score matrices.
​
miner_scores
object
Map of miner UID to a dict of per-environment scores. Keys are UIDs (string); values are objects keyed by environment ID.
​
samples
object
Map of environment ID to the number of samples used for that environment in the current set.
​
dominance_explanation
object
Map of miner UID to a human-readable string: "On frontier" or "Dominated by others".
​
stats
array
Per-miner summary sorted by frontier membership then dominance count.
If no miners are in the current evaluation set the response is {"error": "No miners in current evaluation set"}.
curl --request GET \
  --url https://v2.api.bitrecs.ai/scoring/pareto

​
GET /scoring/wta

Runs the winner-take-all algorithm over Pareto-frontier miners and returns final weights. GET https://v2.api.bitrecs.ai/scoring/wta

​
Response

​
weights
object
Map of miner UID to normalized emission weight (float in [0, 1], summing to 1.0 across all miners).
​
subset_scores
object
Map of miner UID to aggregated subset-priority score used by the WTA algorithm.
​
miner_thresholds
object
Per-miner threshold values computed from their score distributions.
​
miner_blocks
object
Map of miner UID to the Bittensor block number of their first submission (used for tie-breaking).
​
subset_winners
object
Sample of up to 10 environment subset combinations mapped to the winning miner UID for that subset.
​
stats
array
Per-miner ranking summary sorted by descending weight.
curl --request GET \
  --url https://v2.api.bitrecs.ai/scoring/wta

​
GET /scoring/constants

Returns all static scoring constants used by the Bitrecs V2 scoring engine. GET https://v2.api.bitrecs.ai/scoring/constants

​
Response

​
MIN_THRESHOLD_GAP
number
Minimum allowed gap between miner threshold and mean score.
​
MAX_THRESHOLD_GAP
number
Maximum allowed gap between miner threshold and mean score.
​
DEFAULT_Z_SCORE
number
Z-score used when computing default thresholds.
​
DEFAULT_EPISODES_PER_ENV
number
Default number of evaluation episodes per environment.
​
MIN_EPSILON
number
Minimum epsilon value used in threshold computation.
​
MAX_EPSILON
number
Maximum epsilon value used in threshold computation.
​
MINER_EMISSION_PORTION
number
Fraction of total subnet emission allocated to miners.
​
GRACE_PERIOD_DAYS
number
Number of days a new miner is protected from decay.
​
DECAY_FACTOR
number
Per-cycle score decay factor applied outside the grace period.
​
DECAY_FLOOR
number
Minimum score floor below which decay does not reduce scores further.
curl --request GET \
  --url https://v2.api.bitrecs.ai/scoring/constants

​
GET /scoring/latest

Returns all miner scores for the most recent evaluation set as a list of records. GET https://v2.api.bitrecs.ai/scoring/latest

​
Response

​
scores
array
List of score records, one per miner–environment–set combination. Field names match the underlying scores database schema (e.g. uid, hotkey, score, evaluation_set_id).
curl --request GET \
  --url https://v2.api.bitrecs.ai/scoring/latest

​
POST /scoring/weight-set

Records a validator weight set for the current evaluation set. Validators call this endpoint after computing and committing weights on-chain. POST https://v2.api.bitrecs.ai/scoring/weight-set
This endpoint is intended for use by registered validators. Calls from non-validators will still be accepted by the API but the data will not influence scoring outputs.

​
Body

​
validator_hotkey
string
required
SS58 hotkey of the validator submitting the weight set.
​
block
number
Bittensor block number at which the weights were committed. Defaults to 0.
​
wta_uid
number
required
UID of the winner-take-all winning miner for this weight commitment.
​
wta_hotkey
string
required
SS58 hotkey of the WTA winning miner.
​
wta_weight
number
required
Weight assigned to the WTA winner (float in [0, 1]).
​
weights
object
required
Full weight map of miner UID to weight value for all miners in the set.

​
Response

​
status
string
required
"success" on successful insertion, "error" if any required field is missing or an exception occurs.
​
message
string
Present only when status is "error". Describes what went wrong.
curl --request POST \
  --url https://v2.api.bitrecs.ai/scoring/weight-set \
  --header 'Content-Type: application/json' \
  --data '{
    "validator_hotkey": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty",
    "block": 3847500,
    "wta_uid": 42,
    "wta_hotkey": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
    "wta_weight": 0.65,
    "weights": { "42": 0.65, "7": 0.20, "19": 0.15 }
  }'
Success response (200) 
{
  "status": "success"
}
Error response (200 with error status) 
{
  "status": "error",
  "message": "Missing required fields in weight set"
}