Username API

Wallets remain the canonical account anchor. User-facing labels are provided by unique usernames.

Get current username

GET /v1/username?userId=<uuid>

Returns either a full username record or { userId, username: null } when unset.

Set username

PUT /v1/username

Request body:

{
  "userId": "00000000-0000-0000-0000-000000000000",
  "username": "builder_one"
}

Rules:

• lowercase letters, numbers, underscores only
• length 3-24
• globally unique (case-insensitive)

When another user claims the name first, API returns 409 with error=username_taken.

Check availability

GET /v1/username/check?username=builder_one

Response:

{
  "username": "builder_one",
  "available": true
}

Batch resolve usernames

POST /v1/username/batch

Request body:

{
  "userIds": [
    "00000000-0000-0000-0000-000000000000",
    "11111111-1111-4111-8111-111111111111"
  ]
}

Response includes existing usernames for the requested IDs.