Users

The user object

string

UUID.

string | null

Display name.

string | null

E.164 without spaces. Null for email-only users.

string | null

Lowercased. Null for phone-only users. Not returned by phone or ID lookups.

string

Kernel smart-account address.

string

Dialling code captured at registration, for example +91.

string

ACTIVE, INACTIVE or SUSPENDED.

string

ISO 8601 timestamp.

Example

{
  "id": "4f0c9a6e-5b1f-4b0e-9a57-2a4c1c3f9e11",
  "name": "Ada",
  "phoneNumber": "+14155550123",
  "walletAddress": "0x8bA1f109551bD432803012645Ac136ddd64DBA72",
  "countryCode": "+1",
  "status": "ACTIVE",
  "createdAt": "2026-11-03T10:15:22.418Z"
}

Register or sync the current user

POST /user/register · Requires auth Creates the caller’s user record, or returns it if it exists. The identity (phone or email) is taken only from the token. Call this after every login and session restore.

string

required

The caller’s Kernel smart-account address, from kernelAddressForEoa(eoa).

Behaviour

Situation	Result
Identity is new	`201`, user created
Identity exists with the same wallet	`200`, existing user
Identity exists with a claimable wallet	Balance swept to `walletAddress`, then `200` with the updated user. If the sweep fails twice, `200` with the unchanged user; retry later
Identity exists with a different registered wallet	`200`, wallet updated
`walletAddress` belongs to another identity	`409`

curl -X POST https://api.numpay.app/api/user/register \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"0x8bA1f109551bD432803012645Ac136ddd64DBA72"}'

Create a claimable wallet

POST /user/pregenerate · Requires auth Creates a backend-held claimable wallet for a phone number or email that isn’t registered yet. If the identity already exists, returns it unchanged.

string

E.164 phone number, 10–15 characters. Required unless email is given.

string

Email address. Used only when phoneNumber is absent.

Responses: 201 new claimable user · 200 existing user · 400 neither field valid.

Response

{
  "id": "b2d1…",
  "phoneNumber": "+2348012345678",
  "walletAddress": "0x3f5C…9e2A",
  "countryCode": "+234",
  "status": "ACTIVE",
  "createdAt": "2026-11-05T08:01:44.112Z"
}

Update your profile

PUT /user/update/{id} · Requires auth

string

required

The caller’s user UUID.

string

1–100 characters.

string

Dialling code.

string

ACTIVE or INACTIVE.

walletAddress, phoneNumber and email can’t be changed. Returns 403 if id isn’t the caller’s own record.

Get a user by ID or wallet

GET /user/get/{id}

string

required

A user UUID, or a 42-character 0x wallet address.

Returns the user object (without email), or 404.

Get a user by phone number

GET /user/phone/{phoneNumber}

string

required

E.164, 10–15 characters, URL-encoded (%2B14155550123).

Returns the user object (without email), or 404 { "message": "User not found" }.

Get a user by email

GET /user/email/{email}

string

required

URL-encoded email address.

Returns the user object without phoneNumber, so an email can’t reveal a phone number. 404 if not found.

Get an activity summary

GET /user/{userId}/summary

string

required

User UUID.

Response

{
  "success": true,
  "data": {
    "activities": [
      { "type": "TRANSACTION", "date": "2026-11-05T09:12:00.000Z", "amount": 20, "isOutgoing": true, "txhash": "0x…", "sender": { … }, "receiver": { … } },
      { "type": "REQUEST", "date": "2026-11-04T17:40:00.000Z", "amount": 15, "isOutgoing": false, "requestStatus": "PENDING", "requester": { … } }
    ],
    "summary": {
      "totalSent": 20,
      "totalReceived": 35,
      "netBalance": 15,
      "totalTransactions": 3,
      "totalRequests": 1
    }
  }
}

netBalance is computed from recorded history, not the on-chain balance.

Basics

Endpoints

The user object

Register or sync the current user

Create a claimable wallet

Update your profile

Get a user by ID or wallet

Get a user by phone number

Get a user by email

Get an activity summary

​The user object

​Register or sync the current user

​Create a claimable wallet

​Update your profile

​Get a user by ID or wallet

​Get a user by phone number

​Get a user by email

​Get an activity summary

The user object

Register or sync the current user

Create a claimable wallet

Update your profile

Get a user by ID or wallet

Get a user by phone number

Get a user by email

Get an activity summary