Nickname Management

A nickname is a unique, user-friendly identifier for your account. Instead of sharing your long wallet address, you can use a simple nickname that others can use to identify you. This guide covers how to create, retrieve, and update your nickname.

Overview

Nicknames provide a more user-friendly way to identify accounts compared to wallet addresses. Key features:

  • Unique Identifier - Each nickname is unique across the platform
  • User-Friendly - Easy to remember and share
  • One-Time Creation - Once created, you can only update it (not delete and recreate)
  • Points Reward - Creating a nickname earns you points

Prerequisites

Before creating a nickname, ensure you have:

  • Completed authentication and have a valid access token
  • Created a wallet (required before creating a nickname)

Get Nickname

Retrieve your current nickname. If you haven't created one yet, this will return a not found error.

Get nickname

curl -X GET https://api.example.com/api/nickname \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Nickname retrieved successfully",
  "data": {
    "nickname": {
      "id": "nickname-id",
      "client_id": "client-id",
      "nickname": "johndoe",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  }
}

Response (No nickname):

{
  "status": 404,
  "message": "Nickname not found"
}

Create Nickname

Create a new nickname for your account. You can only create a nickname once. After creation, you can only update it.

Create nickname

curl -X POST https://api.example.com/api/nickname \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "nickname": "johndoe"
  }'

Required Fields:

  • nickname - Your desired nickname (must be unique and follow validation rules)

Response:

{
  "status": 201,
  "message": "Nickname created successfully",
  "data": {
    "nickname": "johndoe"
  }
}

Note: Creating a nickname rewards you with points in the platform's points system.

Update Nickname

Update your existing nickname to a new one. You can change your nickname as many times as you want, as long as the new nickname is available.

Update nickname

curl -X PUT https://api.example.com/api/nickname \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "nickname": "newjohndoe"
  }'

Required Fields:

  • nickname - Your new desired nickname (must be unique and follow validation rules)

Response:

{
  "status": 200,
  "message": "Nickname updated successfully",
  "data": {
    "nickname": "newjohndoe"
  }
}

Nickname Validation Rules

Nicknames must follow these rules:

  • Allowed Characters: Only lowercase letters (a-z), digits (0-9), underscore (_), and dot (.)
  • Case Sensitive: All letters must be lowercase
  • Unique: Each nickname must be unique across the platform
  • No Spaces: Spaces are not allowed
  • No Special Characters: Only underscore and dot are allowed as special characters

Valid Examples:

  • johndoe
  • john_doe
  • john.doe
  • john123
  • john_doe.123

Invalid Examples:

  • JohnDoe (uppercase letters)
  • john doe (spaces)
  • john-doe (hyphen not allowed)
  • john@doe (special characters not allowed)

Error Handling

Wallet Not Found

{
  "status": 404,
  "message": "It's necessary to create a wallet first"
}

This error occurs when trying to create a nickname before creating a wallet.

Invalid Nickname Format

{
  "status": 400,
  "message": "Nickname must contain only lowercase letters, digits, underscore, or dot."
}

This error occurs when the nickname doesn't follow the validation rules.

Nickname Already Created

{
  "status": 400,
  "message": "Nickname already was created",
  "data": {
    "nickname": "johndoe"
  }
}

This error occurs when trying to create a nickname but you already have one. Use the update endpoint instead.

Nickname Already Exists

{
  "status": 400,
  "message": "This nickname already exists",
  "data": {
    "nickname": "johndoe"
  }
}

This error occurs when trying to create or update to a nickname that is already taken by another user.

Nickname Not Found

{
  "status": 404,
  "message": "Nickname not found"
}

This error occurs when trying to retrieve a nickname that doesn't exist.

Complete Flow Example

Here's a complete example of the nickname management flow:

# 1. Create wallet first (required)
curl -X POST https://api.example.com/api/wallet \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 2. Create nickname
curl -X POST https://api.example.com/api/nickname \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "nickname": "johndoe"
  }'

# 3. Get nickname
curl -X GET https://api.example.com/api/nickname \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 4. Update nickname (if needed)
curl -X PUT https://api.example.com/api/nickname \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "nickname": "newjohndoe"
  }'

Important Notes

  1. Wallet Required: You must create a wallet before you can create a nickname. The system verifies that you have a wallet address before allowing nickname creation.

  2. One-Time Creation: You can only create a nickname once. After creation, you can only update it to a new nickname. You cannot delete your nickname and create a new one.

  3. Uniqueness: Each nickname must be unique across the entire platform. If a nickname is already taken, you'll need to choose a different one.

  4. Case Sensitivity: Nicknames are case-sensitive, but only lowercase letters are allowed. This means johndoe and JohnDoe are treated the same (both must be lowercase), but the system enforces lowercase-only.

  5. Points Reward: Creating a nickname for the first time rewards you with points in the platform's points system. Updating your nickname does not award additional points.

  6. Update Behavior: When updating your nickname, the system checks if the new nickname is available. If it's already taken, you'll receive an error and your current nickname remains unchanged.

  7. Validation: The nickname validation is strict. Make sure your nickname follows all the rules before submitting to avoid errors.

Use Cases

Nicknames are useful for:

  • User Identification: Easier to identify users than wallet addresses
  • Social Features: Sharing your nickname instead of your wallet address
  • User Experience: More memorable than long hexadecimal addresses
  • Integration: Can be used in other parts of the platform for user lookup

Best Practices

  1. Choose Wisely: Since you can only create once, choose a nickname you'll be happy with long-term
  2. Keep It Simple: Shorter nicknames are easier to remember and share
  3. Check Availability: Try common variations if your first choice is taken
  4. Be Consistent: Use the same nickname across platforms if possible
  5. Update When Needed: You can update your nickname if you change your mind, but remember it must be unique

Was this page helpful?