Points System - BitRobot

Overview

BitRobot uses a two-layer reward system to track and incentivize robot operations across all subnets. Subnet Points are an intermediate, per-subnet scoring layer, and BitRobot Bolts are the network-wide reward they convert into.

Subnet Points are instant, uncapped points that each subnet awards to its users for contributions. They exist to score contributions relative to each other within a period — a Subnet Point has no fixed Bolts value on its own. They are recorded on the user’s points ledger and can be attributed by BitRobot user ID, email, Discord user ID, or Solana wallet address.
BitRobot Bolts are the final, network-wide reward. A user’s Bolts accumulate across every subnet they contribute to, plus Foundation rewards such as referral and hardware bonuses. At each distribution interval (every N days, where N is a factor of 30 — 1, 2, 3, 5, 6, 10, 15, or 30 — depending on the subnet’s settings), a user’s share of a subnet’s total Subnet Points for the period determines their share of that subnet’s Bolts allocation for the period.

Epochs

Points are organized into epochs, each with defined competition periods and leaderboards to track top contributors.

Earning Subnet Points

Subnets award Subnet Points by sending points_grant events via the API:

POST /subnets/{subnet_id}/events
{
  "event_type": "points_grant",
  "recipient": {
    "bitrobot_user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS"
  },
  "points": 100,
  "reason": "Task completion",
  "client_ref": "unique_identifier"
}

Identify the recipient using exactly one of bitrobot_user_id, email, discord_user_id, or wallet_address inside the recipient object. You can also grant points through the dedicated Grant Subnet Points endpoint — POST /subnets/{subnet_id}/points/grants — which takes the same recipient, points, reason, and client_ref fields directly, without the event_type wrapper. Both paths share the same grant logic and idempotency, so use whichever fits your integration. Subnet Points are uncapped. New grants are recorded directly on the user’s points ledger and do not consume a point-pool balance.

Requirements

Recipient: Provide exactly one of recipient.bitrobot_user_id, recipient.email, recipient.discord_user_id, or recipient.wallet_address. Email, Discord, and wallet identifiers all support pre-registration reward attribution. If the recipient is not yet known to BitRobot, the grant is held on a placeholder account and applied to the real user when they sign up (email or Discord). For a wallet address, everything you grant after the user connects reaches their account, and the balance already on the placeholder is folded in as well.
Client Reference: Unique identifier prevents duplicate grants (idempotency). Reusing the same client_ref for a subnet returns an error for the events API.
Reason: Description of why points were awarded (max 256 characters).

The grant time is assigned by the server based on the current open distribution window for your subnet. Caller-supplied granted_at and brb_epoch_id fields are not accepted and will return a 422 error.

Automatic grants from VRW

By default, a subnet also grants Subnet Points automatically whenever a task run is validated. When a run is validated with vrw_points > 0 — through a task_validate event or a task batch upload — the resource owner is granted the same number of Subnet Points as the run’s vrw_points, in addition to the VRW recorded on-chain for token rewards. A subnet controls this with the auto_grant_subnet_points_from_vrw setting (returned by the Subnet Economics Overview):

true (default) — validating a run grants the resource owner Subnet Points equal to its vrw_points. Operators who want Subnet Points to track verified work 1:1 can rely on this alone and never send points_grant events.
false — validating a run still records VRW on-chain, but grants no Subnet Points. The subnet distributes Subnet Points itself using the points_grant events or CSV upload above. Use this to run your own incentive logic — quality tiers, loyalty, an operator cut — instead of granting points 1:1 with VRW.

This setting is configured per subnet by a BitRobot admin.

Referral Bonuses

When a referred user’s Subnet Points convert to BitRobot Bolts, their referrer automatically receives a 10% bonus paid in Bolts (10% of the referee’s Bolts allocation from that conversion). The bonus is applied at conversion time, not when the Subnet Points are initially granted.

Points Management

Subnet admins can manage points through the Points Management page in the BitRobot dashboard:

Upload Points CSV: Bulk distribute points to contributors via CSV upload
View Grants History: See all points granted for the subnet with filtering and sorting
Reverse Grants: Reverse a previous grant — instantly if its points haven’t converted yet, or by requesting a reversal if they have (see Reversing grants)

Reversing grants

Each grant on the Points Management page shows a reversal action that depends on whether its Subnet Points have already converted to Bolts:

Unconverted grants reverse instantly. Choose Reverse Instantly to remove the points right away. Because they haven’t converted to Bolts yet, no approval is required. This is the dashboard equivalent of the points_revoke API event.
Converted grants need a reversal request. Once a grant’s points have converted to Bolts, you can’t reverse them yourself. Choose Request Reversal and provide a reason. A BitRobot admin reviews the request, and if approved, the already-converted Bolts for that period are rebalanced: the Bolts the grant produced are clawed back from the contributor, and the subnet owner’s split and any referral bonuses for that period are adjusted to match. If the request is rejected, nothing changes. While a request is awaiting review, the grant shows Reversal Requested.

CSV Upload

Bulk distribute points by uploading a CSV file through the dashboard. Subnet Points are uncapped, so uploads do not require a pre-funded point pool.

CSV Format

The CSV must include a header row. Required and optional columns:

Column	Required	Description
`bitrobot_user_id`	Yes*	BitRobot user ID (ULID format)
`email`	Yes*	Email address (alternative to bitrobot_user_id)
`discord_user_id`	Yes*	Discord user ID (alternative to bitrobot_user_id)
`wallet_address`	Yes*	Solana wallet address (alternative to bitrobot_user_id)
`points`	Yes	Number of points to grant (must be > 0)
`reason`	Yes	Description of why points were awarded (max 256 characters)
`client_ref`	No	Unique identifier for idempotency (max 64 characters)

Exactly one of bitrobot_user_id, email, discord_user_id, or wallet_address is required for each row. The grant time and epoch are assigned by the server from the current open distribution window — granted_at and brb_epoch_id columns are not accepted and will fail validation if present.

Example CSV

Using bitrobot_user_id:

bitrobot_user_id,points,reason,client_ref
01HQXK5V7YWQZ8NGQB2RJVT9MS,1000,Task completion bonus,task-001
01HQXK6A2BWPN3KGQC4SJWU8NT,500,Community contribution,contrib-042

Using email:

email,points,reason,client_ref
[email protected],1000,Task completion bonus,task-001
[email protected],500,Community contribution,contrib-042

Idempotency

If you include a client_ref value, the system will skip any rows where that client_ref has already been processed for your subnet. This allows you to safely re-upload the same CSV without creating duplicate grants. Note that the events API behaves differently: a duplicate client_ref there returns an error instead of skipping.

Response

A successful upload returns:

{
  "message": "Subnet Points imported successfully",
  "processed": 10,
  "imported": 8,
  "errors": [
    {
      "row": 3,
      "client_ref": "task-003",
      "error": "User not found: invalid-user-id"
    }
  ]
}

processed: Rows processed after duplicate client_ref skips
imported: Rows successfully imported
errors: Details for any rows that failed

Error Handling

The CSV upload continues processing valid rows even when some rows fail. If a row’s client_ref has already been processed for the subnet, that row is skipped and does not appear in errors. Common errors:

Error	Cause
`Points is required`	Missing or empty points value
`Points must be greater than 0`	Points value is zero or negative
`Reason is required`	Missing reason field
`Reason must be 256 characters or less`	Reason exceeds max length
`Exactly one recipient identity is required: bitrobot_user_id, email, discord_user_id, or wallet_address`	Row has no identifier or multiple identifiers provided
`granted_at is not accepted for subnet-facing points imports; the server assigns grant time from the current open window`	Row supplied a `granted_at` value
`brb_epoch_id is not accepted for subnet-facing points imports; the server derives the current epoch`	Row supplied a `brb_epoch_id` value
`User not found: {id}`	Invalid `bitrobot_user_id` provided
`No active epoch found`	No epoch is currently active
`Invalid CSV format`	Malformed CSV file
`Another CSV import is currently in progress`	Concurrent upload for same subnet

Viewing Bolts and Points

Users can check their earnings via:

Bolts Balance: Total BitRobot Bolts earned across all subnets and the Foundation Pool
Subnet Points: Points earned within each individual subnet for the current period
Leaderboard Rankings: Compare Bolts earnings with other contributors across the current epoch and all-time

Subnet Economics Overview

Retrieve the authenticated economics and configuration view for a subnet. This endpoint is intended for subnet admins and super admins in the BitRobot Main App and requires a JWT bearer token.

GET /subnets/{subnet_id}/economics
Authorization: Bearer <jwt>

Response

{
  "status": "success",
  "subnet": {
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "name": "ThorSim",
    "description": "A teleoperation subnet for simulation and real-world robot contributions.",
    "tagline": "Help train embodied AI",
    "image_url": "https://example.com/images/thorsim.png",
    "release_order": 12,
    "tags": ["simulation", "teleop"],
    "contributor_types": [
      {
        "label": "Pilot",
        "description": "Drive teleoperated robots",
        "icon": "gamepad"
      }
    ],
    "owner_name": "BitRobot",
    "subnet_url": "https://bitrobot.ai/subnets/thorsim",
    "help_url": "https://docs.bitrobot.ai/subnets/thorsim",
    "distribution_frequency": "15 day",
    "next_conversion_at": "2026-06-17T00:00:00Z",
    "coming_soon": false,
    "subnet_pda": "GjwzKQ5tqViQh7yWWGStvkEG1Zmhx6uasJtWCJzkPdA",
    "public": true,
    "admin_status": "active",
    "launch_scheduled_for": null,
    "retirement_scheduled_for": null,
    "launched_at": "2026-01-15T00:00:00Z",
    "retired_at": null,
    "coming_soon_since": null,
    "return_to_live_scheduled_for": null,
    "configuration": {
      "distribution_frequency": "15 day",
      "owner_split_percentage": 10,
      "auto_grant_subnet_points_from_vrw": false
    },
    "stats": {
      "multiplier": 1.0,
      "daily_bolts_allocation": 10000.0,
      "qualified_hours": 4823,
      "contributor_count": 312
    }
  }
}

The response returns the subnet’s full record. Every field is documented below.

Response Fields

Identity and metadata

Field	Description
`subnet.id`	Subnet ULID
`subnet.name`	Display name
`subnet.description`	Long-form description
`subnet.tagline`	Short tagline
`subnet.image_url`	Subnet image URL (may be a time-limited presigned URL)
`subnet.release_order`	Ordinal used to order subnets in the app
`subnet.tags`	Array of free-form tag strings
`subnet.contributor_types`	Array of contributor-type objects, each with `label`, `description`, and `icon`
`subnet.owner_name`	Owner’s display name, falling back to the owner’s email if no display name is set
`subnet.subnet_url`	Public subnet page URL
`subnet.help_url`	Subnet help / documentation URL
`subnet.subnet_pda`	The subnet’s on-chain Solana Program Derived Address (public)

Lifecycle and visibility

Field	Description
`subnet.public`	Whether the subnet is publicly listed
`subnet.coming_soon`	`true` while the subnet is in a coming-soon or pending-return-to-live state
`subnet.admin_status`	Lifecycle status: one of `draft`, `pending_launch`, `active`, `coming_soon`, `pending_retirement`, `pending_return_to_live`, or `retired`
`subnet.next_conversion_at`	ISO 8601 timestamp of the next scheduled Subnet Points-to-Bolts conversion, or `null` when the subnet is coming soon
`subnet.launch_scheduled_for`	ISO 8601 timestamp the subnet is scheduled to launch, or `null`
`subnet.launched_at`	ISO 8601 timestamp the subnet launched, or `null`
`subnet.retirement_scheduled_for`	ISO 8601 timestamp the subnet is scheduled to retire, or `null`
`subnet.retired_at`	ISO 8601 timestamp the subnet retired, or `null`
`subnet.coming_soon_since`	ISO 8601 timestamp the subnet entered the coming-soon state, or `null`
`subnet.return_to_live_scheduled_for`	ISO 8601 timestamp a coming-soon subnet is scheduled to return to live, or `null`
`subnet.distribution_frequency`	The same value as `configuration.distribution_frequency`, surfaced at the top level for convenience

`configuration`

Field	Description
`subnet.configuration.distribution_frequency`	How often the subnet receives Bolts. A string of the form `N day` where N is a factor of 30: `1 day`, `2 day`, `3 day`, `5 day`, `6 day`, `10 day`, `15 day`, or `30 day`
`subnet.configuration.owner_split_percentage`	Percentage of Bolts allocated to the subnet owner
`subnet.configuration.auto_grant_subnet_points_from_vrw`	Whether validating a task run automatically grants Subnet Points. Defaults to `true`. When `true`, validating a run (via `task_validate` or a task batch upload) with `vrw_points > 0` grants the resource owner that many Subnet Points, on top of the VRW recorded on-chain. When `false`, validation still records VRW on-chain but grants no Subnet Points — the subnet distributes them itself via `points_grant` or CSV upload. See Automatic grants from VRW

`stats`

Field	Description
`subnet.stats.multiplier`	Subnet’s current Bolts multiplier (float)
`subnet.stats.daily_bolts_allocation`	Total Bolts this subnet receives per day (float)
`subnet.stats.qualified_hours`	Total qualified hours accrued since the launch of the BitRobot Main App
`subnet.stats.contributor_count`	Number of distinct users with applied Subnet Point grants

This endpoint is admin-authenticated, so the response always describes the caller’s own subnet. The lifecycle and visibility fields primarily drive the BitRobot dashboard UI — most integrations only need the configuration and stats objects.

Revoke Subnet Points

Revoke previously granted Subnet Points from a user by sending a points_revoke event via the same events endpoint used for granting points.

This endpoint only revokes unconverted Subnet Points. Once Subnet Points have been included in a Bolts conversion, they can’t be revoked through the API — the Bolts those points produced have already been distributed and recorded on the user’s ledger. The maximum amount you can revoke for a user equals their current_period_points value from the List balances endpoint, which is exactly the user’s remaining unconverted Subnet Points.To reverse a grant that has already converted to Bolts, submit a reversal request from the dashboard instead — see Reversing grants.

POST /subnets/{subnet_id}/events
{
  "event_type": "points_revoke",
  "recipient": {
    "bitrobot_user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS"
  },
  "points": 50,
  "reason": "Duplicate grant correction",
  "client_ref": "revoke-task-001"
}

Request Fields

Field	Required	Description
`event_type`	Yes	Must be `points_revoke`
`recipient`	Yes	Object with exactly one of `bitrobot_user_id`, `email`, `discord_user_id`, or `wallet_address`
`points`	Yes	Number of points to revoke (must be > 0 and ≤ user’s remaining unconverted balance)
`reason`	Yes	Description of why points are being revoked (max 256 characters)
`client_ref`	No	Unique identifier for idempotency (max 64 characters)

Response

{
  "status": "success",
  "data": {
    "ledger_id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
    "points_revoked": 50,
    "remaining_unconverted_points": 150,
    "resolved_user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS",
    "resolved_by": "bitrobot_user_id"
  }
}

remaining_unconverted_points reflects the user’s remaining unconverted balance for this subnet after the revocation is applied. resolved_user_id is the BitRobot user the revocation was applied to, and resolved_by indicates which recipient identifier matched them (bitrobot_user_id, email, discord_user_id, or wallet_address).

Errors

Error	Cause
`Only unconverted points can be revoked via the subnet events API`	The user has no unconverted Subnet Points left to revoke (everything they earned has already been converted to Bolts)
`Requested revocation exceeds the user's remaining unconverted points`	The user has some unconverted points, but fewer than the amount requested
`Duplicate client_ref: {value}`	A previous grant or revocation in this subnet already used this `client_ref`
`Exactly one recipient identity is required: bitrobot_user_id, email, discord_user_id, or wallet_address`	The `recipient` object is missing or contains zero / multiple identifiers

Balances

List all users and their Subnet Points and Bolts balances for your subnet.

GET /subnets/{subnet_id}/balances

Query Parameters

Parameter	Required	Description
`page`	No	Page number for pagination (default: 1)
`limit`	No	Results per page (default: 50, max: 200)

Response

{
  "status": "success",
  "data": {
    "balances": [
      {
        "wallet_address": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
        "user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS",
        "current_period_points": 1200,
        "all_time_points": 45600,
        "bolts": 8432.50
      },
      {
        "wallet_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
        "user_id": "01HQXK6A2BWPN3KGQC4SJWU8NT",
        "current_period_points": 800,
        "all_time_points": 32100,
        "bolts": 5219.75
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 312
    }
  }
}

Response Fields

Field	Description
`current_period_points`	Subnet Points earned in the current period, not yet converted to Bolts
`all_time_points`	Total Subnet Points earned across all periods, including already converted
`bolts`	Total BitRobot Bolts earned from this subnet’s Epoch Bolts and Milestone Bolts

The bolts field only reflects Bolts earned through this subnet. It does not include Foundation Bolts (hardware purchases, referral bonuses, etc.), which are managed separately by the BitRobot Foundation.

Subnet Points History

View the full history of Subnet Points grants and revocations for your subnet. Filterable by user and date range.

GET /subnets/{subnet_id}/points/history

Query Parameters

Parameter	Required	Description
`wallet_address`	No	Filter by Solana wallet address
`user_id`	No	Filter by BitRobot user ID
`start_date`	No	Filter events from this date (ISO 8601)
`end_date`	No	Filter events until this date (ISO 8601)
`page`	No	Page number for pagination (default: 1)
`limit`	No	Results per page (default: 50, max: 200)

Response

{
  "status": "success",
  "data": {
    "events": [
      {
        "ledger_id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
        "event_type": "grant",
        "wallet_address": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
        "user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS",
        "points": 100,
        "reason": "Task completion bonus",
        "client_ref": "task-001",
        "created_at": "2026-03-12T14:30:00Z"
      },
      {
        "ledger_id": "01ARZ3NDEKTSV4RRFFQ69G5FAY",
        "event_type": "revocation",
        "wallet_address": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
        "user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS",
        "points": -50,
        "reason": "Duplicate grant correction",
        "client_ref": "revoke-task-001",
        "created_at": "2026-03-12T15:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1547
    }
  }
}

Subnet Points to Bolts Conversions

View the history of Subnet Points -> BitRobot Bolts conversions for your subnet. Each entry represents a single conversion event (e.g., one period’s distribution).

GET /subnets/{subnet_id}/conversions

Query Parameters

Parameter	Required	Description
`start_date`	No	Filter conversions from this date (ISO 8601)
`end_date`	No	Filter conversions until this date (ISO 8601)
`page`	No	Page number for pagination (default: 1)
`limit`	No	Results per page (default: 50, max: 200)

Response

{
  "status": "success",
  "data": {
    "conversions": [
      {
        "conversion_id": "01ARZ3NDEKTSV4RRFFQ69G5FAZ",
        "converted_at": "2026-03-12T00:00:00Z",
        "period_started_at": "2026-03-11T00:00:00Z",
        "period_ended_at": "2026-03-12T00:00:00Z",
        "total_subnet_points_in_pool": 58000,
        "gross_bolts_allocation": 10000,
        "total_bolts_distributed": 10000,
        "user_bolts_distributed": 9000,
        "owner_bolts_distributed": 1000,
        "user_breakdown": [
          {
            "wallet_address": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
            "user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS",
            "subnet_points": 1200,
            "share_percentage": 2.07,
            "bolts_earned": 206.90
          },
          {
            "wallet_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
            "user_id": "01HQXK6A2BWPN3KGQC4SJWU8NT",
            "subnet_points": 800,
            "share_percentage": 1.38,
            "bolts_earned": 137.93
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 45
    }
  }
}

Response Fields

Field	Description
`converted_at`	Timestamp of the conversion event
`period_started_at`	Start of the distribution period this conversion covers (may be `null` for legacy conversions)
`period_ended_at`	End of the distribution period this conversion covers (may be `null` for legacy conversions)
`total_subnet_points_in_pool`	Total Subnet Points earned by all users during this period
`gross_bolts_allocation`	Gross Bolts allocation for the period before any subnet-owner split is applied
`total_bolts_distributed`	Total BitRobot Bolts distributed in this conversion (sum of `user_bolts_distributed` and `owner_bolts_distributed`)
`user_bolts_distributed`	Bolts distributed to contributors based on their Subnet Points share
`owner_bolts_distributed`	Bolts distributed to the subnet owner per the configured owner split (`0` if the subnet has no owner split)
`user_breakdown[].subnet_points`	Subnet Points this user earned during the period
`user_breakdown[].share_percentage`	This user’s percentage share of the pool
`user_breakdown[].bolts_earned`	BitRobot Bolts this user received from the conversion

API Reference

Learn how to grant points via the events API

​Overview

​Epochs

​Earning Subnet Points

​Requirements

​Automatic grants from VRW

​Referral Bonuses

​Points Management

​Reversing grants

​CSV Upload

​CSV Format

​Example CSV

​Idempotency

​Response

​Error Handling

​Viewing Bolts and Points

​Subnet Economics Overview

​Response

​Response Fields

​Identity and metadata

​Lifecycle and visibility

​configuration

​stats

​Revoke Subnet Points

​Request Fields

​Response

​Errors

​Balances

​Query Parameters

​Response

​Response Fields

​Subnet Points History

​Query Parameters

​Response

​Subnet Points to Bolts Conversions

​Query Parameters

​Response

​Response Fields

API Reference

Overview

Epochs

Earning Subnet Points

Requirements

Automatic grants from VRW

Referral Bonuses

Points Management

Reversing grants

CSV Upload

CSV Format

Example CSV

Idempotency

Response

Error Handling

Viewing Bolts and Points

Subnet Economics Overview

Response

Response Fields

Identity and metadata

Lifecycle and visibility

`configuration`

`stats`

Revoke Subnet Points

Request Fields

Response

Errors

Balances

Query Parameters

Response

Response Fields

Subnet Points History

Query Parameters

Response

Subnet Points to Bolts Conversions

Query Parameters

Response

Response Fields