Subnet Integration

Overview

A subnet is a robotics project or hardware platform that integrates with BitRobot to track operations and distribute rewards to participants.

Integration Steps

1. Register Your Subnet

Contact the BitRobot team to register your subnet and receive:

Subnet ID: Unique identifier for your application
Admin User: An admin account to manage your subnet via the BitRobot dashboard, where you can generate API keys and manage point grants and tasks

2. Get and manage your API key

Every request to the subnet API is authenticated with an API key. Create and manage keys from the API Keys page in your subnet’s settings on the BitRobot dashboard (available to subnet admins). To create a key:

Open API Keys for your subnet and choose Create API Key.
Give the key a name (for example, Production or Staging) so you can tell your keys apart.
Optionally set an expiration: No expiration, 30 days, 60 days, 90 days, or 1 year.
Copy the key when it’s shown. The full key is displayed only once and can’t be retrieved later — store it in a secret manager. Afterward the dashboard shows only a masked prefix, never the full key.

Keys start with brb_ and are sent as a bearer token:

Authorization: Bearer brb_your_api_key_here

Scope. Each API key is scoped to a single subnet and can only act on the subnet it was created for. A subnet can have multiple active keys, so you can issue a separate key per environment or service and revoke them independently. Revoke. Revoke a key from the API Keys page when it’s no longer needed or may have leaked. Revocation takes effect immediately — any request still using that key starts receiving 401 Unauthorized. Keys can’t be rotated in place; to rotate, create a new key, move your integration over to it, then revoke the old one. The dashboard also shows each key’s status (active or revoked), expiration, when it was last used, and who created it.

3. Send Events via API

Use the BitRobot API to track robot operations, award points, and read subnet reporting data:

POST https://api-stage.bitrobot.ai/subnets/{subnet_id}/events
Authorization: Bearer {api_secret}
Content-Type: application/json

{
  "event_type": "points_grant",
  "recipient": {
    "bitrobot_user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS"
  },
  "points": 100,
  "reason": "Task completion reward",
  "client_ref": "task-001"
}

For points_grant and points_revoke, identify the recipient using exactly one of bitrobot_user_id, email, discord_user_id, or wallet_address inside the recipient object.

4. Event Types

register_resource: Register a new robot/resource in the system
task_start: Start a new task run
task_end: Complete an existing task run
task_validate: Validate a completed task run and award VRW points
points_grant: Grant uncapped Subnet Points to a user
points_revoke: Revoke previously granted, unconverted Subnet Points from a user (converted points cannot be revoked)

You can also use the API to read your subnet’s balances, points history, and conversion history.

5. Let users connect their subnet wallet

If you grant points by wallet_address, BitRobot Connect links a user’s subnet wallet to their BitRobot account. You host a small connect page on your domain; BitRobot sends the user there, your backend confirms the wallet with one API call, and you redirect the browser to the return_url that call returns. The connection completes the moment the user lands back on BitRobot. Any wallet provider works, since you only ever send an address. Points you grant to a wallet before its owner connects are held and folded into their account when they do.

Best Practices

Send events asynchronously to avoid blocking operations
Include unique client_ref identifiers for idempotency on points_grant and points_revoke events
Log API responses for debugging
Handle authentication errors gracefully

Need Help?

API Reference

View detailed API documentation and endpoint specifications

​Overview

​Integration Steps

​1. Register Your Subnet

​2. Get and manage your API key

​3. Send Events via API

​4. Event Types

​5. Let users connect their subnet wallet

​Best Practices

​Need Help?