Users API Reference

This section covers all endpoints related to users.

Get User Growth

Endpoint: GET /users/growth

Responses

Status Code	Description
200	Successful Response

---

List Chute Shares

Endpoint: GET /users/{user_id}/shares

Parameters

Parameter	Type	Required	Description
user_id	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin User Id Lookup

Endpoint: GET /users/user_id_lookup

Parameters

Parameter	Type	Required	Description
username	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin Balance Lookup

Endpoint: GET /users/{user_id_or_username}/balance

Parameters

Parameter	Type	Required	Description
user_id_or_username	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin Invoiced User List

Endpoint: GET /users/invoiced_user_list

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin Batch User Lookup

Endpoint: POST /users/batch_user_lookup

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin Balance Change

Endpoint: POST /users/admin_balance_change

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Request Body

Field	Type	Required	Description
user_id	string	Yes
amount	number	Yes
reason	string	Yes

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Balance Transfer

Transfer balance from the authenticated user to a target user. Supports three authentication methods:

1. Hotkey authentication (X-Chutes-Hotkey + X-Chutes-Signature + X-Chutes-Nonce)
2. Admin API key (Authorization: cpk_...)
3. Fingerprint (Authorization: )

Endpoint: POST /users/balance_transfer

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Request Body

Field	Type	Required	Description
user_id	string	Yes
amount	number | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

---

Grant Subnet Role

Endpoint: POST /users/grant_subnet_role

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Request Body

Field	Type	Required	Description
user	string	Yes
netuid	integer	Yes
admin	boolean	Yes

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Revoke Subnet Role

Endpoint: POST /users/revoke_subnet_role

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Request Body

Field	Type	Required	Description
user	string	Yes
netuid	integer	Yes

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin Quotas Change

Endpoint: POST /users/{user_id}/quotas

Parameters

Parameter	Type	Required	Description
user_id	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin Get User Quotas

Load quotas for a user.

Endpoint: GET /users/{user_id}/quotas

Parameters

Parameter	Type	Required	Description
user_id	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin Quota Effective Date Change

Endpoint: PUT /users/{user_id}/quotas/{chute_id}/effective_date

Parameters

Parameter	Type	Required	Description
user_id	string	Yes
chute_id	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Request Body

Field	Type	Required	Description
effective_date	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin Discounts Change

Endpoint: POST /users/{user_id}/discounts

Parameters

Parameter	Type	Required	Description
user_id	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin List Discounts

Endpoint: GET /users/{user_id}/discounts

Parameters

Parameter	Type	Required	Description
user_id	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Admin Enable Invoicing

Endpoint: POST /users/{user_id}/enable_invoicing

Parameters

Parameter	Type	Required	Description
user_id	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

My Quotas

Load quotas for the current user.

Endpoint: GET /users/me/quotas

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

My Discounts

Load discounts for the current user.

Endpoint: GET /users/me/discounts

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

My Price Overrides

Load price overrides for the current user.

Endpoint: GET /users/me/price_overrides

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Chute Quota Usage

Check the current quota usage for a chute.

Endpoint: GET /users/me/quota_usage/{chute_id}

Parameters

Parameter	Type	Required	Description
chute_id	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

My Subscription Usage

Get current subscription usage and caps for the authenticated user. Returns monthly and 4-hour window usage vs limits.

Endpoint: GET /users/me/subscription_usage

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Delete My User

Delete account.

Endpoint: DELETE /users/me

Parameters

Parameter	Type	Required	Description
Authorization	string	Yes	Authorization header

Responses

Status Code	Description
200	Successful Response
422	Validation Error

---

Set Logo

Get a detailed response for the current user.

Endpoint: GET /users/set_logo

Parameters

Parameter	Type	Required	Description
logo_id	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Check Username

Check if a username is valid and available.

Endpoint: GET /users/name_check

Parameters

Parameter	Type	Required	Description
username	string	Yes
readonly	boolean | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

---

Register

Register a user.

Endpoint: POST /users/register

Parameters

Parameter	Type	Required	Description
token	string | null	No
X-Chutes-Hotkey	string	Yes	The hotkey of the user
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Request Body

Field	Type	Required	Description
username	string	Yes
coldkey	string	Yes
logo_id	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Get Registration Token

Initial form with cloudflare + hcaptcha to generate a registration token.

Endpoint: GET /users/registration_token

Responses

Status Code	Description
200	Successful Response

---

Post Rtok

Verify hCaptcha and get a short-lived registration token.

Endpoint: POST /users/registration_token

Responses

Status Code	Description
200	Successful Response

---

Admin Create User

Create a new user manually from an admin account, no bittensor stuff necessary.

Endpoint: POST /users/create_user

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Request Body

Field	Type	Required	Description
username	string	Yes
coldkey	string | null	No
hotkey	string | null	No
logo_id	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Change Fingerprint

Reset a user's fingerprint using either the hotkey or coldkey.

Endpoint: POST /users/change_fingerprint

Parameters

Parameter	Type	Required	Description
Authorization	string | null	No
X-Chutes-Hotkey	string | null	No
X-Chutes-Coldkey	string | null	No
X-Chutes-Nonce	string	No	Nonce
X-Chutes-Signature	string	No	Hotkey signature

Request Body

Field	Type	Required	Description
fingerprint	string	Yes

Responses

Status Code	Description
200	Successful Response
422	Validation Error

---

Get Login Nonce

Get a nonce for hotkey signature login. The nonce is a UUID4 string that must be signed by the user's hotkey. Valid for 5 minutes.

Endpoint: GET /users/login/nonce

Responses

Status Code	Description
200	Successful Response

---

Login

Exchange credentials for a JWT.

Supports two authentication methods:

1. Fingerprint: {"fingerprint": "your-fingerprint"}
2. Hotkey signature: {"hotkey": "5...", "signature": "hex...", "nonce": "uuid"}

For hotkey auth, first call GET /users/login/nonce to get a nonce, sign it with your hotkey (e.g., btcli w sign --message <nonce>), then submit the hotkey, signature, and nonce.

Endpoint: POST /users/login

Responses

Status Code	Description
200	Successful Response

---

Change Bt Auth

Change the bittensor hotkey/coldkey associated with an account via fingerprint auth.

Endpoint: POST /users/change_bt_auth

Parameters

Parameter	Type	Required	Description
Authorization	string	Yes

Responses

Status Code	Description
200	Successful Response
422	Validation Error

---

Update Squad Access

Enable squad access.

Endpoint: PUT /users/squad_access

Parameters

Parameter	Type	Required	Description
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

List Usage

List usage summary data.

Endpoint: GET /users/{user_id}/usage

Parameters

Parameter	Type	Required	Description
user_id	string	Yes
page	integer | null	No
limit	integer | null	No
per_chute	boolean | null	No
chute_id	string | null	No
start_date	string | null	No
end_date	string | null	No
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Get User Info

Get user info.

Endpoint: GET /users/{user_id}

Parameters

Parameter	Type	Required	Description
user_id	string	Yes
X-Chutes-Hotkey	string | null	No
X-Chutes-Signature	string | null	No
X-Chutes-Nonce	string | null	No
Authorization	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

Authentication

This endpoint requires authentication.

---

Agent Registration

Register an AI agent programmatically using hotkey/coldkey/signature. Returns a payment address where the agent must send TAO to complete registration.

Endpoint: POST /users/agent_registration

Request Body

Field	Type	Required	Description
hotkey	string	Yes
coldkey	string	Yes
signature	string	Yes
username	string | null	No

Responses

Status Code	Description
200	Successful Response
422	Validation Error

---

Get Agent Registration Status

Check the status of an agent registration by hotkey. Handles all states: pending payment, completed (converted to user), or expired.

Endpoint: GET /users/agent_registration/{hotkey}

Parameters

Parameter	Type	Required	Description
hotkey	string	Yes

Responses

Status Code	Description
200	Successful Response
422	Validation Error

---

Agent Setup

One-time setup endpoint for agent-registered users. Requires hotkey signature to prove ownership. Returns API key and config.ini template.

Endpoint: POST /users/{user_id}/agent_setup

Parameters

Parameter	Type	Required	Description
user_id	string	Yes

Request Body

Field	Type	Required	Description
hotkey	string	Yes
signature	string	Yes

Responses

Status Code	Description
200	Successful Response
422	Validation Error

---