curl --request POST \
--url https://api-stage.bitrobot.ai/subnets/{subnet_id}/points/grants \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"recipient": {
"bitrobot_user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS"
},
"points": 100,
"reason": "Task completion bonus",
"client_ref": "task_123_completion"
}
'{
"message": "Subnet Points granted successfully",
"ledger_id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
"resolved_user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS",
"resolved_by": "bitrobot_user_id",
"created_placeholder_user": false
}Grant Subnet Points
Grants uncapped Subnet Points to a recipient identified by exactly one of bitrobot_user_id, email, discord_user_id, or wallet_address.
This is a dedicated, single-purpose endpoint for granting Subnet Points — not tied to a task run or the multiplexed events endpoint. It accepts the grant fields directly (no event_type wrapper) and returns the resolved recipient. It is functionally equivalent to sending a points_grant event to Create a new event: both share the same grant logic, validation, and client_ref idempotency, and both record the grant against your subnet’s current open distribution window. The server assigns the grant timestamp and epoch automatically, so caller-supplied granted_at and brb_epoch_id are rejected with a 422.
If the recipient is identified by email, discord_user_id, or an unregistered wallet_address and is not yet a BitRobot user, the grant is held on a placeholder account and applied when they sign up or connect the wallet (see created_placeholder_user in the response). Granting by bitrobot_user_id requires an existing user.
curl --request POST \
--url https://api-stage.bitrobot.ai/subnets/{subnet_id}/points/grants \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"recipient": {
"bitrobot_user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS"
},
"points": 100,
"reason": "Task completion bonus",
"client_ref": "task_123_completion"
}
'{
"message": "Subnet Points granted successfully",
"ledger_id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
"resolved_user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS",
"resolved_by": "bitrobot_user_id",
"created_placeholder_user": false
}Authorizations
API key authentication. Your API key should start with brb_.
Example: Authorization: Bearer brb_1234567890abcdef
Path Parameters
The unique identifier of the subnet (ULID format)
^[0-9A-HJKMNP-TV-Z]{26}$Body
Request body for the dedicated Grant Subnet Points endpoint. The same grant fields as the points_grant event, without the event_type discriminator. The recipient is identified by exactly one of bitrobot_user_id, email, discord_user_id, or wallet_address. The grant is recorded against the current open distribution window; the server assigns the timestamp and epoch automatically, so granted_at and brb_epoch_id are not accepted.
Exactly one of bitrobot_user_id, email, discord_user_id, or wallet_address must be provided. On grants, email, discord_user_id, and wallet_address support pre-registration attribution: if the recipient is not yet on BitRobot, the grant is held on a placeholder and applied when they create a BitRobot account or connect the wallet. bitrobot_user_id must reference an existing user, and revocations always require a recipient who already exists.
Show child attributes
Show child attributes
{
"bitrobot_user_id": "01HQXK5V7YWQZ8NGQB2RJVT9MS"
}
The number of points to grant (must be greater than 0).
x >= 1100
The reason for granting these points.
256"Task completion bonus"
Optional client reference ID for idempotency and tracking. Duplicate values for the same subnet are rejected.
64"task_123_completion"
Response
Subnet Points granted successfully.
Human-readable confirmation message.
"Subnet Points granted successfully"
ID of the points ledger entry created for this grant.
^[0-9A-HJKMNP-TV-Z]{26}$"01ARZ3NDEKTSV4RRFFQ69G5FAX"
ID of the BitRobot user (or newly created placeholder user) the grant was applied to.
^[0-9A-HJKMNP-TV-Z]{26}$"01HQXK5V7YWQZ8NGQB2RJVT9MS"
Which recipient identifier was used to resolve or create the user.
bitrobot_user_id, email, discord, wallet_address "bitrobot_user_id"
Whether a placeholder account was created because the recipient was not yet a BitRobot user. The grant is applied to the real account when they sign up (email or Discord) or connect the wallet. Always false when granting by bitrobot_user_id.
false