Skip to content

[Docs] Update pregenerate wallets API endpoint and request format #7791

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 6, 2025
Merged

[Docs] Update pregenerate wallets API endpoint and request format #7791

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 43 additions & 7 deletions apps/portal/src/app/wallets/custom-auth/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,13 +57,31 @@ You will be asked to enter the following values

### Usage example

<Tabs defaultValue="typescript">
<Tabs defaultValue="http">
<TabsList>
<TabsTrigger value="http">HTTP</TabsTrigger>
<TabsTrigger value="typescript">TypeScript</TabsTrigger>
<TabsTrigger value="react">React</TabsTrigger>
<TabsTrigger value="dotnet">.NET</TabsTrigger>
</TabsList>

<TabsContent value="http">

```http
POST https://api.thirdweb.com/v1/wallets/user/generic-auth
Content-Type: application/json
x-client-id: <your-client-id>
x-ecosystem-id: <your-ecosystem-id> (optional)
x-ecosystem-partner-id: <your-ecosystem-partner-id> (optional)

{
"type": "jwt",
"jwt": "<your-jwt>"
}
```

</TabsContent>

<TabsContent value="react">

```typescript
Expand All @@ -81,7 +99,7 @@ const handlePostLogin = async () => {
wallet.connect({
client,
strategy: "jwt",
jwt: "<your-jwt-token>",
jwt: "<your-jwt>",
});
return wallet;
});
Expand All @@ -107,7 +125,7 @@ const wallet = inAppWallet();
const account = await wallet.connect({
client,
strategy: "jwt",
jwt: "<your-jwt-token>",
jwt: "<your-jwt>",
});

// use the account to send transactions
Expand All @@ -122,7 +140,7 @@ using Thirdweb;

var client = ThirdwebClient.Create(clientId: "your-client-id");
var wallet = await InAppWallet.Create(client: client, authProvider: AuthProvider.JWT);
var address = await wallet.LoginWithCustomAuth(jwt: "<your-jwt-token>");
var address = await wallet.LoginWithCustomAuth(jwt: "<your-jwt>");
```

</TabsContent>
Expand Down Expand Up @@ -170,13 +188,33 @@ You can also pass a list of headers. These headers will be sent with every reque

Once you've logged in with your own auth, you can pass the user's JWT to the in-app wallet to authenticate and connect.

<Tabs defaultValue="typescript">
<Tabs defaultValue="http">
<TabsList>
<TabsTrigger value="http">HTTP</TabsTrigger>
<TabsTrigger value="typescript">TypeScript</TabsTrigger>
<TabsTrigger value="react">React</TabsTrigger>
<TabsTrigger value="dotnet">.NET</TabsTrigger>
</TabsList>

<TabsContent value="http">

```http
POST https://api.thirdweb.com/v1/wallets/user/generic-auth
Content-Type: application/json
x-client-id: <your-client-id>
x-ecosystem-id: <your-ecosystem-id> (optional)
x-ecosystem-partner-id: <your-ecosystem-partner-id> (optional)

{
"type": "auth-payload",
"payload": "<your-auth-payload>"
}
```



</TabsContent>

<TabsContent value="react">

```typescript
Expand Down Expand Up @@ -214,8 +252,6 @@ const MyComponent = () => {

<TabsContent value="typescript">

In other frameworks, use your own instance of the wallet to authenticate and connect.

```typescript
import { inAppWallet } from "thirdweb/wallets";

Expand Down
38 changes: 26 additions & 12 deletions apps/portal/src/app/wallets/pregenerate-wallets/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ export const metadata = createMetadata({
icon: "wallets",
},
title: "Pregenerate Wallets | thirdweb",
description: "Create wallets before users sign up with thirdweb’s wallet pregeneration. Pre-fund with tokens, NFTs, or game assets to enable smooth onboarding and asset claiming.",
description: "Create wallets before users sign up with thirdweb's wallet pregeneration. Pre-fund with tokens, NFTs, or game assets to enable smooth onboarding and asset claiming.",
});

# Pregenerate Wallets
Expand Down Expand Up @@ -35,35 +35,48 @@ You can distribute assets to wallets before users claim them, enabling:

To pregenerate an in-app or ecosystem wallet wallet, you can make a `POST` request to the following endpoint:

```
https://in-app-wallet.thirdweb.com/api/v1/pregenerate
```http
POST https://api.thirdweb.com/v1/wallets/user/pregenerate
Content-Type: application/json
x-secret-key: <your-secret-key>
x-ecosystem-id: <your-ecosystem-id> (optional)
x-ecosystem-partner-id: <your-ecosystem-partner-id> (optional)

{
"type": "email",
"email": "[email protected]"
}
```

## Request Body

The request body should be a JSON object with the following parameters:

- `strategy`: The strategy for wallet generation
- `email` or `phone` or `userId`: The user identifier associated with the wallet to be generated
- `type`: The type of wallet identifier to pregenerate a wallet for:
- Email based: `email`, `google`, `facebook`, `discord`
- Phone based: `phone`
- Wallet based: `signer`
- User ID based: `custom_jwt` or `custom_auth_endpoint`
- `email` or `phone` or `userId` or `walletAddress`: The user identifier associated with the wallet to be generated

### Email based wallets

```
{ strategy: "email", email: "[email protected]" }
{ type: "email", email: "[email protected]" }
```

When the user logs in with any method associated with that email (including google, facebook, discord auth), they will get access to the same pregenerated wallet.

### Phone based wallets

```
{ strategy: "phone", phone: "+1321123321" }
{ type: "phone", phone: "+1321123321" }
```

### Custom user id based wallets

```
{ strategy: "custom_auth_endpoint", userId: "some_user_id" }
{ type: "custom_auth_endpoint", userId: "some_user_id" }
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's an inconsistency in the parameter naming for custom user ID based wallets. In the request body description (line 60), the parameter is referred to as user, but in the example JSON (line 70), it's shown as userId. These should be aligned to provide clear documentation. Consider standardizing on one parameter name throughout the documentation.

Suggested change
{ type: "custom_auth_endpoint", userId: "some_user_id" }
{ type: "custom_auth_endpoint", user: "some_user_id" }

Spotted by Diamond

Is this helpful? React 👍 or 👎 to let us know.

```

{/* TODO: update link when custom auth documentation has been updated */}
Expand All @@ -83,13 +96,13 @@ You need to include the following headers:
Here's an example curl command to pregenerate a thirdweb wallet for the user `[email protected]`:

```bash
curl -X POST 'https://in-app-wallet.thirdweb.com/api/v1/pregenerate' \
curl -X POST 'https://api.thirdweb.com/v1/wallets/user/pregenerate' \
-H 'x-ecosystem-id: ecosystem.example-eco-123' \
-H 'x-ecosystem-partner-id: 1415d24e-c7b0-4fce-846e-740841ef2c32' \
-H 'x-secret-key: 9f8e7d6c5b4a3f2e1d0c9b8a7ffge434b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7' \
-H 'x-secret-key: <your-project-secret-key>' \
-H 'Content-Type: application/json' \
-d '{
"strategy": "email",
"type": "email",
"email": "[email protected]"
}'
```
Expand All @@ -107,9 +120,10 @@ A successful API call returns a JSON object in the following format:

```json
{
"wallet": {
"result": {
"address": "string",
"createdAt": "string",
"profile": "object[]"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The indentation of the profile field should be aligned with the address and createdAt fields for consistent formatting in the JSON response example. Consider adjusting to:

{
  "result": {
    "address": "string",
    "createdAt": "string",
    "profile": "object[]"
  }
}

Spotted by Diamond

Is this helpful? React 👍 or 👎 to let us know.

}
}
```
Expand Down
Loading