Fetch Users

GET request to the following endpoint:

GET /v1/wallets/user?email=user@example.com
Host: api.thirdweb.com
x-secret-key: <your-secret-key>

You can then query by different user identifiers:

• address: The user's wallet address that thirdweb has generated for them
• email: The user's email address
• phone: The user's phone number
• externalWalletAddress: The user's wallet address that used to login via SIWE
• id: The user's ID (for custom auth)

You need to include the following headers:

• x-secret-key: Your secret key for authentication
• x-ecosystem-id (optional): Your ecosystem ID
• x-ecosystem-partner-id (optional): Your ecosystem partner ID

Here's an example curl command to fetch user details by email:

 
curl -X GET 'https://api.thirdweb.com/v1/wallets/user?email=user@example.com' \
  -H 'x-secret-key: YOUR_SECRET_KEY'
 

Here's an example curl command to fetch user details by address:

curl -X GET 'https://api.thirdweb.com/v1/wallets/user?address=0x123456789abcdef' \
  -H 'x-secret-key: YOUR_SECRET_KEY'

Here's an example curl command to fetch the user details for an ecosystem owner:

curl -X GET 'https://api.thirdweb.com/v1/wallets/user?address=0x123456789abcdef' \
  -H 'x-secret-key: YOUR_SECRET_KEY' \
  -H 'x-ecosystem-id: ecosystem.YOUR_ECOSYSTEM_ID' \
  -H 'x-ecosystem-partner-id: YOUR_PARTNER_ID'

In both examples, replace YOUR_SECRET_KEY with your actual ThirdWeb Client Secret.

Replace YOUR_ECOSYSTEM_ID and YOUR_PARTNER_ID with your actual ecosystem ID and partner ID respectively. The partner ID can be one you set up for yourself as the ecosystem owner.

The API returns a JSON array with the following structure for each user:

{
  "result": {
    "pagination": {
      "hasMore": false,
      "limit": 50,
      "page": 1
    },
    "wallets": [
      {
        "address": "0x3aA70e68BBA8BC922a75d07388e368892c15c9Da",
        "createdAt": "2025-07-21T22:58:12.834Z",
        "profiles": [
          {
            "id": "107302390467834615186",
            "name": "Richard Hendricks",
            "type": "google",
            "email": "richard@piedpiper.com",
            "picture": "https://lh3.googleusercontent.com/a/ACg8ocKC1D6ezzzaZxxUk4qtK_HCwVwpNamVopazXwklGBwuuHeSf_c=s96-c",
            "givenName": "Richard",
            "emailVerified": true
          }
        ]
      }
    ]
  }
}

For more information, view the full reference

If you are using the thirdweb SDK, you can use the getUser method to retrieve user details.