API Documentation

Base URL

The base URL for all API endpoints is the root of your deployed application.

Authentication

Most endpoints require authentication using Privy JWT tokens. Some endpoints also require a Chip Auth JWT token.

Authentication Header Format

Authorization: Bearer <privyJwt> <chipAuthJwt>

Note: Some endpoints only require the Privy JWT token.

Endpoints

1. Create User

URL: /api/users

Method: POST

Authentication: Privy JWT required

Request Body

{
  "username": "string",
  "phone": "string",
  "birthday": "string" (ISO 8601 date format)
}

Response

Success: 200 OK

{
  "_id": "string",
  "privyDid": "string",
  "wallet": "string",
  "email": "string",
  "username": "string",
  "phone": "string",
  "birthday": "string",
  "colors": ["string", "string", "string"],
  "contactsCount": 0,
  "createdAt": "string"
}

Error: 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

2. Get User

URL: /api/users

Method: GET

Authentication: Privy JWT required

Query Parameters

  • privyDid: string (optional)
  • email: string (optional)
  • username: string (optional)
  • chipUid: string (optional)
  • limit: number (default: 10)

Response

Success: 200 OK

[
  {
    "_id": "string",
    "privyDid": "string",
    "email": "string",
    "username": "string",
    "chip": {
      "uid": "string",
      "groupId": number
    },
    "colors": ["string", "string", "string"],
    "contactsCount": number,
    "createdAt": "string",
    "contacts": [
      {
        "receiver": {
          "privyDid": "string",
          "email": "string",
          "username": "string",
          "chip": {
            "uid": "string",
            "groupId": number
          },
          "colors": ["string", "string", "string"]
        },
        "receiverColorsSnapshot": ["string", "string", "string"],
        "createdAt": "string"
      }
    ]
  }
]

Error: 500 Internal Server Error

3. Update User

URL: /api/users/[id]

Method: PUT

Authentication: Privy JWT required

Request Body

{
  "phone": "string",
  "username": "string",
  "birthday": "string" (ISO 8601 date format)
}

Response

Success: 200 OK

{
  "_id": "string",
  "privyDid": "string",
  "email": "string",
  "phone": "string",
  "username": "string",
  "birthday": "string",
  "chip": {
    "uid": "string",
    "groupId": number
  },
  "colors": ["string", "string", "string"],
  "contactsCount": number,
  "createdAt": "string"
}

Error: 401 Unauthorized, 404 Not Found, 500 Internal Server Error

4. Get User by ID

URL: /api/users/[id]

Method: GET

Response

Success: 200 OK

{
  "_id": "string",
  "privyDid": "string",
  "email": "string",
  "username": "string",
  "chip": {
    "uid": "string",
    "groupId": number
  },
  "colors": ["string", "string", "string"],
  "contactsCount": number,
  "createdAt": "string",
  "contacts": [
    {
      "receiver": {
        "privyDid": "string",
        "email": "string",
        "username": "string",
        "chip": {
          "uid": "string",
          "groupId": number
        },
        "colors": ["string", "string", "string"]
      },
      "receiverColorsSnapshot": ["string", "string", "string"],
      "createdAt": "string"
    }
  ]
}

Error: 404 Not Found, 500 Internal Server Error

5. Link User to Chip

URL: /api/users

Method: PUT

Authentication: Privy JWT and Chip Auth JWT required

Request Body

{
  "username": "string",
  "phone": "string",
  "birthday": "string" (ISO 8601 date format)
}

Response

Success: 200 OK

{
  "_id": "string",
  "privyDid": "string",
  "wallet": "string",
  "email": "string",
  "username": "string",
  "phone": "string",
  "birthday": "string",
  "chip": {
    "uid": "string",
    "groupId": number
  },
  "colors": ["string", "string", "string"],
  "contactsCount": number,
  "createdAt": "string"
}

Error: 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error

6. Create Contact

URL: /api/contacts

Method: POST

Authentication: Privy JWT and Chip Auth JWT required

Response

Success: 200 OK

{
  "_id": "string",
  "initiator": "string",
  "receiver": "string",
  "receiverColorsSnapshot": ["string", "string", "string"],
  "lotteryIndex": number,
  "createdAt": "string"
}

Error: 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error

7. Get All Contacts

URL: /api/contacts

Method: GET

Response

Success: 200 OK

[
  {
    "_id": "string",
    "initiator": "string",
    "receiver": "string",
    "receiverColorsSnapshot": ["string", "string", "string"],
    "lotteryIndex": number,
    "createdAt": "string"
  }
]

Error: 500 Internal Server Error

8. Get Leaderboard

URL: /api/leaderboard

Method: GET

Query Parameters

  • userId: string (optional)
  • limit: number (default: 10)

Response

Success: 200 OK

{
  "leaderboard": [
    {
      "email": "string",
      "username": "string",
      "contactsCount": number,
      "ranking": number
    }
  ],
  "user": {
    "email": "string",
    "username": "string",
    "contactsCount": number,
    "ranking": number
  }
}

Notes:

  • The "user" field is only included if a valid userId is provided.
  • The leaderboard is sorted by contactsCount (descending) and createdAt (ascending) as a tiebreaker.
  • The ranking starts from 1 and represents the user's position in the overall leaderboard.

Error: 404 Not Found (if userId is provided but not found), 500 Internal Server Error