Skip to content

Commit 76be3f8

Browse files
saminacodessaminacodes
committed
added guide
1 parent 7eed8e6 commit 76be3f8

File tree

2 files changed

+189
-0
lines changed

2 files changed

+189
-0
lines changed

‎apps/portal/src/app/ai/chat/migrate-from-nebula/page.mdx‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
import {Callout, Step, Steps} from "@doc";
2+
3+
# Migrate to thirdweb AI
4+
5+
If you previously used the Nebula endpoints (nebula-api.thirdweb.com/chat) for thirdweb AI features, this guide that will teach you how
6+
to migrate to the thirdweb API.
7+
8+
<Callout variant="info" title="Nebula Deprecation"> As of August 14, 2025 Nebula (blockchain LLM) has officially been deprecated and re-branded to thirdweb AI </Callout>
9+
10+
**Endpoint Changes:**
11+
- Old URL: `https://nebula-api.thirdweb.com/chat`
12+
- New URL: `https://api.thirdweb.com/ai/chat`
13+
14+
15+
## Benefits of thirdweb API
16+
17+
- Standard Chat Format: Follows industry-standard conversational AI patterns
18+
- Better Message History: Support for multi-turn conversations with role-based messages
19+
- Structured Context: Type-safe object format instead of string parsing
20+
- Enhanced Session Management: More flexible session handling
21+
- Future-Proof: Aligned with modern chat API standards
22+
23+
## Quick Reference
24+
25+
| First API Field | Second API Field | Notes |
26+
|-----------------|-------------------------|---------------------------------------------|
27+
| message | messages[].content | Single string → Array of message objects |
28+
| session_id | context.session_id | Moved inside context object (optional) |
29+
| context (string)| context (object) | String format → Structured object |
30+
| walletAddress | context.from | Renamed field |
31+
| chainIds | context.chain_ids | Renamed field |
32+
33+
## Request Structure Comparison
34+
35+
Before (Nebula API)
36+
37+
```typescript
38+
fetch("<https://nebula-api.thirdweb.com/chat>", {
39+
method: "POST",
40+
headers: {
41+
"Content-Type": "application/json",
42+
"x-secret-key": "your-secret-key",
43+
},
44+
body: JSON.stringify({
45+
message: "Send 0.01 ETH to vitalik.eth",
46+
stream: false,
47+
session_id: "your-session-id",
48+
context: "{ chainIds: [1]; walletAddress: '0x123...'; }",
49+
}),
50+
});
51+
```
52+
53+
## After (thirdweb AI Chat API)
54+
55+
```typescript
56+
fetch("<https://api.thirdweb.com/ai/chat>", {
57+
method: "POST",
58+
headers: {
59+
"Content-Type": "application/json",
60+
"x-secret-key": "your-secret-key",
61+
},
62+
body: JSON.stringify({
63+
context: {
64+
chain_ids: [1],
65+
from: "0x123...",
66+
session_id: "your-session-id", // Optional
67+
},
68+
messages: [
69+
{
70+
role: "user",
71+
content: "Send 0.01 ETH to vitalik.eth",
72+
},
73+
],
74+
stream: false,
75+
}),
76+
});
77+
```
78+
79+
## Migration Steps
80+
81+
<Steps>
82+
83+
<Step title="Update Endpoint URL">
84+
85+
Change your base URL from:
86+
87+
`<https://nebula-api.thirdweb.com/chat>`
88+
89+
to
90+
91+
`<https://api.thirdweb.com/ai/chat>`
92+
93+
</Step>
94+
95+
<Step title="Restructure Message Format">
96+
Convert the single message field to a messages array:
97+
98+
Before:
99+
100+
```typescript
101+
message: "Your message here"
102+
```
103+
104+
After:
105+
106+
```typescript
107+
messages: [
108+
{
109+
role: "user", content: "Your message here" }
110+
]
111+
```
112+
113+
Supported roles:
114+
- **user** - Messages from the user
115+
- **assistant** - Messages from the AI
116+
- **system** - System messages for context
117+
118+
119+
</Step>
120+
121+
<Step title="Update Context Structure">
122+
Old format (string):
123+
124+
```typescript
125+
context: "{ chainIds: [1, 137]; walletAddress: '0x123...'; }"
126+
```
127+
128+
New format (object):
129+
130+
```typescript
131+
context: {
132+
chain_ids: [1, 137],
133+
from: "0x123...",
134+
session_id: "optional-session-id"
135+
}
136+
```
137+
138+
</Step>
139+
140+
<Step title="Map Fields">
141+
142+
| Old Field | New Field | Required | Notes |
143+
|---------------|--------------------|----------|--------------------------------|
144+
| walletAddress | context.from | Optional | Wallet that executes transactions |
145+
| chainIds | context.chain_ids | Optional | Array of chain IDs |
146+
| session_id | context.session_id | Optional | Now nested in context |
147+
148+
</Step>
149+
150+
<Step title="Session Manangement">
151+
- Session ID is now optional and nested within the context object
152+
- If not provided, a new session will be created automatically
153+
- Sssions enable conversation continuity
154+
</Step>
155+
</Steps>
156+
157+
### Example Migration Function
158+
159+
```typescript
160+
function migrateToNewAPI(oldRequest) {
161+
// Parse old context string const contextString = oldRequest.context; const contextData = parseContextString(contextString); // Implement this helper
162+
return {
163+
context: {
164+
chain_ids: contextData.chainIds,
165+
from: contextData.walletAddress,
166+
session_id: oldRequest.session_id,
167+
},
168+
messages: [
169+
{
170+
role: "user",
171+
content: oldRequest.message,
172+
},
173+
],
174+
stream: oldRequest.stream || false,
175+
};
176+
}
177+
```
178+
179+
### Test Migration
180+
181+
1. Update your endpoint URL
182+
2. Transform your request payload structure
183+
3. Test with a simple message first
184+
4. Verify session continuity works as expected
185+
5. Test complex scenarios with multiple messages

‎apps/portal/src/app/ai/sidebar.tsx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ export const sidebar: SideBar = {
3333
name: "API Reference",
3434
href: "https://api.thirdweb.com/reference#tag/ai/post/ai/chat",
3535
},
36+
{
37+
name: "Migrate from Nebula",
38+
href: "/ai/chat/migrate-from-nebula",
39+
},
3640
],
3741
},
3842
{ separator: true },

0 commit comments

Comments
 (0)