Fetch a Single User

From the backend, you are able to get the details of any user within your in app or ecosystem wallet.

To get the user details, you can make a GET request to the following endpoint:

https://in-app-wallet.thirdweb.com/api/2023-11-30/embedded-wallet/user-details

You can specify the query parameter queryBy to query by different user identifiers:

• queryBy: The parameter to query by. Can be one of walletAddress, email, phone, externalWalletAddress, or id.

You can then specify the value to query by, matching the queryBy parameter:

• walletAddress: 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 your ThirdWeb Client Secret in the Authorization header.

If you are an ecosystem owner, you have to include the x-ecosystem-id header and optionally the x-ecosystem-partner-id header if the ecosystem is set to partners only.

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

 
curl -X GET 'https://in-app-wallet.thirdweb.com/api/2023-11-30/embedded-wallet/user-details?queryBy=email&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://in-app-wallet.thirdweb.com/api/2023-11-30/embedded-wallet/user-details?queryBy=walletAddress&walletAddress=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://in-app-wallet.thirdweb.com/api/2023-11-30/embedded-wallet/user-details?queryBy=walletAddress&walletAddress=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:

[
  {
    "userId": "string",
    "walletAddress": "string",
    "email": "string (optional)",
    "phone": "string (optional)",
    "createdAt": "string",
    "linkedAccounts": [
      {
        "type": "string",
        "details": {
          "phone": "string",
          // or
          "email": "string",
          // or
          "address": "string",
          // or
          "id": "string",
          // Additional key-value pairs may be present
        }
      }
    ]
  }
]

Note: The details object in linkedAccounts will contain different fields based on the account type. See the list of Strategies above for more information.

Remember to handle the response appropriately in your chosen programming language, including error cases and parsing the JSON response.

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

Fetch All Users

Once you have users connecting to your app through in-app wallets, you can fetch all users through our REST API:

https://in-app-wallet.thirdweb.com/api/v1/users

You need to include the following headers:

• Content-Type: Must be set to application/json
• 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 pregenerate a thirdweb wallet for the user user@example.com:

curl -X GET 'https://in-app-wallet.thirdweb.com/api/v1/users?offset=200&limit=100' \
  -H 'x-secret-key: YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json'

Limit defaults to 100 users per request.

A successful API call returns an array of user objects in the following format:

[
  {
    "userId": "9841a5de-b4a6-44b3-ad14-c4b8745782ca",
    "walletAddress": "0x933F5BC72634c55b3643A6Aa0cD5b65ca4915d39",
    "createdAt": "2024-11-05T00:55:25.142Z",
    "authProvider": "google",
    "authDetails": {
        "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
    },
    "email": "richard@piedpiper.com",
  }
]