Documentation | Users › Lookup User By Wallet Address

API Reference

Users

users

Methods

Create User ->

User

post/v1/users

Create a new user with linked accounts. Optionally pre-generate embedded wallets for the user.

Create Custom Metadata -> { custom_metadata }

post/v1/users/{user_id}/custom_metadata

Adds custom metadata to a user by user ID.

Delete User ->

delete/v1/users/{user_id}

Delete a user by user ID.

Get User ->

User

get/v1/users/{user_id}

Get a user by user ID.

path Parameters

user_id: string

User ID

Response fields

User

Request example

curl https://api.privy.io/v1/users/$USER_ID \
    -H "Authorization: Basic $PRIVY_APP_ID:$PRIVY_APP_SECRET"

200Example

{
  "id": "did:privy:cm3np4u9j001rc8b73seqmqqk",
  "created_at": 1731974895,
  "has_accepted_terms": true,
  "is_guest": false,
  "linked_accounts": [
    {
      "address": "[email protected]",
      "first_verified_at": 1674788927,
      "latest_verified_at": 1674788927,
      "type": "email",
      "verified_at": 1674788927
    },
    {
      "fid": 4423,
      "first_verified_at": 1740678402,
      "latest_verified_at": 1741194370,
      "owner_address": "0xE6bFb4137F3A8C069F98cc775f324A84FE45FdFF",
      "type": "farcaster",
      "verified_at": 1740678402,
      "bio": "engineering at /privy. building pixelpool.xyz, the first Farcaster video client. nyc. 👨‍💻🍎🏳️‍🌈  nf.td/payton",
      "display_name": "payton ↑",
      "homepage_url": "homepage_url",
      "profile_picture": "https://supercast.mypinata.cloud/ipfs/QmNexfCxdnFzWdJqKVgrjd27UGLMexNaw5FXu1XKR3cQF7?filename=IMG_2799.png",
      "profile_picture_url": "https://supercast.mypinata.cloud/ipfs/QmNexfCxdnFzWdJqKVgrjd27UGLMexNaw5FXu1XKR3cQF7?filename=IMG_2799.png",
      "signer_public_key": "signer_public_key",
      "username": "payton"
    },
    {
      "credential_id": "Il5vP-3Tm3hNmDVBmDlREgXzIOJnZEaiVnT-XMliXe-BufP9GL1-d3qhozk9IkZwQ_",
      "enrolled_in_mfa": true,
      "first_verified_at": 1741194420,
      "latest_verified_at": 1741194420,
      "type": "passkey",
      "verified_at": 1741194420,
      "authenticator_name": "1Password",
      "created_with_browser": "Chrome",
      "created_with_device": "Macintosh",
      "created_with_os": "Mac OS"
    }
  ],
  "mfa_methods": [
    {
      "type": "passkey",
      "verified_at": 1741194420
    }
  ],
  "custom_metadata": {
    "foo": "string"
  }
}

Lookup User By Email Address ->

User

post/v1/users/email/address

Looks up a user by their email address.

Lookup User By Custom Auth ID ->

User

post/v1/users/custom_auth/id

Looks up a user by their custom auth ID.

Lookup User By Wallet Address ->

User

post/v1/users/wallet/address

Looks up a user by their wallet address.

Response fields

User

Request example

curl https://api.privy.io/v1/users/wallet/address \
    -H 'Content-Type: application/json' \
    -H "Authorization: Basic $PRIVY_APP_ID:$PRIVY_APP_SECRET" \
    -d '{
      "address": "address"
    }'

200Example

{
  "id": "id",
  "created_at": 0,
  "has_accepted_terms": true,
  "is_guest": true,
  "linked_accounts": [
    {
      "address": "address",
      "first_verified_at": 0,
      "latest_verified_at": 0,
      "type": "email",
      "verified_at": 0
    }
  ],
  "mfa_methods": [
    {
      "type": "passkey",
      "verified_at": 0
    }
  ],
  "custom_metadata": {
    "foo": "string"
  }
}

Gets Users -> Cursor<

User

get/v1/users

Get all users in your app.

Get User ->

User

get/v1/users/{user_id}

Get a user by user ID.

Domain types

User = { id, created_at, has_accepted_terms, 4 more... }