Skip to content

Commit 0497cb1

Browse files
saminacodessaminacodes
committed
initial nebula docs
1 parent bc368c5 commit 0497cb1

File tree

8 files changed

+386
-8
lines changed

8 files changed

+386
-8
lines changed

‎apps/portal/src/app/Header.tsx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@ const links = [
3232
name: "Insight",
3333
href: "/insight",
3434
},
35+
{
36+
name: "Nebula",
37+
href: "/nebula",
38+
},
3539
];
3640

3741
const toolLinks = [

‎apps/portal/src/app/nebula/api-reference/page.mdx‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Nebula API Reference
2+
3+
Nebula provides a conversational interface to interact with blockchain data and services, and access to thirdweb tools.
4+
5+
## Authentication
6+
7+
All API endpoints require authentication using the thirdweb secret key.
8+
9+
Add the following header to your requests:
10+
11+
```
12+
x-secret-key: YOUR_THIRDWEB_SECRET_KEY
13+
```
14+
15+
## Sessions
16+
17+
A session represents a conversation thread with the AI. Sessions can be:
18+
19+
- Created explicitly via the `/session` endpoint
20+
- Created automatically when sending a message without a session_id
21+
- Reused to maintain context across multiple messages
22+
- Configured with specific execution parameters
23+
24+
Sessions persist your conversation history and any custom configurations you've set for interacting with blockchain data and thirdweb tools.
25+
26+
## Context Filtering
27+
28+
The context filter allows you to control what blockchain data is used to inform AI responses:
29+
30+
- Specify which blockchain networks to search via chain IDs (e.g. 1 for Ethereum mainnet)
31+
- Filter data by specific contract addresses
32+
- Control the context scope for more relevant AI responses
33+
- Optimize response relevance and token usage
34+
35+
Example context filter:
36+
```json
37+
{
38+
"context_filter": {
39+
"chain_ids": [1], // Ethereum mainnet
40+
"contract_addresses": ["0x..."] // Target contract address
41+
}
42+
}
43+
```
44+
45+
## Endpoints
46+
47+
### Chat
48+
49+
#### Send Message
50+
51+
```http
52+
POST /chat
53+
```
54+
55+
Send a message and get a response. Supports both streaming and non-streaming responses.
56+
57+
Request body:
58+
59+
```json
60+
{
61+
"message": "Find the last 5 blocks",
62+
"session_id": "abc", // Optional - will create new session if omitted
63+
"stream": true, // Optional, default false
64+
"context_filter": { // Optional: Filter data sources for context
65+
"chain_ids": [137], // Optional: Array of chain IDs to search (e.g. 137 for Polygon)
66+
"contract_addresses": ["0x.."] // Optional: Array of contract addresses
67+
}
68+
}
69+
```
70+
71+
For non-streaming responses (stream: false):
72+
73+
```json
74+
{
75+
"result": {
76+
"message": "The last 5 blocks on polygon are...",
77+
"session_id": "abc",
78+
"message_id": "1234",
79+
"created_at": "2024-01-01T00:00:00Z",
80+
"usage": {
81+
"prompt_tokens": 10,
82+
"completion_tokens": 15,
83+
"total_tokens": 25
84+
}
85+
}
86+
}
87+
```
88+
89+
For streaming responses (stream: true), returns Server-Sent Events (SSE) with the following event types:
90+
91+
- `message`: Contains a chunk of the response text
92+
- `error`: Contains error information if something goes wrong
93+
- `done`: Signals the end of the stream with complete message details
94+
95+
Example SSE stream:
96+
97+
```
98+
event: message
99+
data: {"text": "Hello", "message_id": "123"}
100+
101+
event: message
102+
data: {"text": " world!", "message_id": "123"}
103+
104+
event: done
105+
data: {
106+
"message_id": "123",
107+
"session_id": "abc",
108+
"created_at": "2024-01-01T00:00:00Z",
109+
"usage": {
110+
"prompt_tokens": 10,
111+
"completion_tokens": 15,
112+
"total_tokens": 25
113+
}
114+
}
115+
```
116+
117+
### Execute
118+
119+
#### Execute Command
120+
121+
```http
122+
POST /execute
123+
```
124+
125+
Execute a specific command or action.
126+
127+
Request body:
128+
129+
```json
130+
{
131+
"message": "Deploy a new ERC20 contract",
132+
"session_id": "sess_01HKW2ZH45JNQRTM0YPKJ6QXXX", // Optional
133+
"config": {
134+
"chain": "ethereum",
135+
"contract_name": "MyToken",
136+
"symbol": "MTK"
137+
}
138+
}
139+
```
140+
141+
142+
### Sessions
143+
144+
#### List Sessions
145+
146+
```http
147+
GET /session/list
148+
```
149+
150+
Returns a list of available sessions for the authenticated account.
151+
152+
Response:
153+
154+
```json
155+
{
156+
"result": [
157+
{
158+
"id": "string",
159+
"title": "string",
160+
"model_name": "string",
161+
"is_public": boolean,
162+
"created_at": "datetime",
163+
"updated_at": "datetime"
164+
}
165+
]
166+
}
167+
```
168+
169+
#### Get Session
170+
171+
```http
172+
GET /session/{session_id}
173+
```
174+
175+
Retrieves details for a specific session.
176+
177+
Response:
178+
179+
```json
180+
{
181+
"result": {
182+
"id": "string",
183+
"title": "string",
184+
"model_name": "string",
185+
"is_public": boolean,
186+
"created_at": "datetime",
187+
"updated_at": "datetime",
188+
"messages": []
189+
}
190+
}
191+
```
192+
193+
#### Create Session
194+
195+
```http
196+
POST /session
197+
```
198+
199+
Create a new chat session.
200+
201+
Request body:
202+
203+
```json
204+
{
205+
"title": "My DeFi Research", // Optional: Custom session title
206+
"is_public": true, // Optional: Make session publicly accessible
207+
"context_filter": { // Optional: Filter data sources for context
208+
"chain_ids": [1], // Optional: Array of chain IDs (e.g. 1 for Ethereum)
209+
"contract_addresses": ["0x..."] // Array of contract addresses
210+
}
211+
}
212+
```
213+
214+
215+
#### Update Session
216+
217+
```http
218+
PUT /session/{session_id}
219+
```
220+
221+
Update an existing session.
222+
223+
Request body:
224+
225+
```json
226+
{
227+
"title": "string",
228+
"is_public": boolean,
229+
}
230+
```
231+
232+
#### Clear Session
233+
234+
```http
235+
POST /session/{session_id}/clear
236+
```
237+
238+
Clears the message history of a session.
239+
240+
#### Delete Session
241+
242+
```http
243+
DELETE /session/{session_id}
244+
```
245+
246+
Deletes a session.
247+
248+
249+
## Error Handling
250+
251+
The API uses standard HTTP status codes and returns error messages in the following format:
252+
253+
```json
254+
{
255+
"error": {
256+
"message": "Error description"
257+
}
258+
}
259+
```
260+
261+
Common status codes:
262+
263+
- 400: Bad Request
264+
- 401: Unauthorized
265+
- 404: Not Found
266+
- 500: Internal Server Error

‎apps/portal/src/app/nebula/layout.tsx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
import { DocLayout } from "@/components/Layouts/DocLayout";
2+
import { createMetadata } from "@doc";
3+
import { sidebar } from "./sidebar";
4+
5+
export default async function Layout(props: { children: React.ReactNode }) {
6+
return (
7+
<DocLayout sideBar={sidebar} editPageButton={true}>
8+
{props.children}
9+
</DocLayout>
10+
);
11+
}
12+
13+
export const metadata = createMetadata({
14+
title: "Engine",
15+
description:
16+
"Engine is a backend HTTP server that calls smart contracts using your managed backend wallets.",
17+
});

‎apps/portal/src/app/nebula/page.mdx‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# What is Nebula?
2+
3+
Natural language model with blockchain reasoning, autonomous transaction capabilities and real-time access to the blockchain.
4+
5+
Nebula is currently available in Alpha. [Join the waitlist.](https://thirdweb.com/nebula)
6+
7+
### With Nebula, you can:
8+
9+
- Chat with an AI with blockchain context - answer questions about transactions, wallets, and smart contracts in real-time
10+
- Create code editors that can write web3 apps & games
11+
- Build blockchain explorers that explain complex transactions in plain English
12+
- Build automated trading agents that can monitor and execute trades based on specific conditions
13+
- Perform smart contract security analysis and audit assistance
14+
- Wallet management assistants that help users track portfolios and suggest optimizations
15+
- Create DeFi strategy advisors that analyze yields and risks across protocols
16+
- Create NFT collection managers that can mint, list, and track market activity
17+
- Enable automated customer support for web3 products
18+
19+
### Supported Chains
20+
Nebula is supported on every EVM compatible chain. To view the full list, visit [thirdweb chainlist](https://thirdweb.com/chainlist).

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
import type { SideBar } from "@/components/Layouts/DocLayout";
2+
3+
export const sidebar: SideBar = {
4+
name: "Nebula",
5+
links: [
6+
{
7+
name: "Overview",
8+
href: "/nebula",
9+
},
10+
{
11+
name: "API Reference",
12+
href: "/nebula/api-reference",
13+
},
14+
],
15+
};

‎apps/portal/src/app/page.tsx‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ import {
88
ConnectOverviewIcon,
99
ContractDeployIcon,
1010
ContractExploreIcon,
11-
ContractInteractIcon,
1211
ContractModularContractIcon,
1312
ContractPublishIcon,
1413
DotNetIcon,
@@ -45,6 +44,7 @@ export default function Page() {
4544
<EngineSection />
4645
<ContractsSection />
4746
<InsightSection />
47+
<NebulaSection />
4848
</main>
4949
);
5050
}
@@ -314,12 +314,6 @@ function ContractsSection() {
314314
href="/contracts/build/overview"
315315
icon={ContractModularContractIcon}
316316
/>
317-
<ArticleCardIndex
318-
title="Interact"
319-
description="Add smart contract interactions in your app"
320-
icon={ContractInteractIcon}
321-
href="/contracts"
322-
/>
323317
<ArticleCardIndex
324318
title="Explore"
325319
description="Ready-to-deploy contracts"
@@ -371,6 +365,23 @@ function InsightSection() {
371365
);
372366
}
373367

368+
function NebulaSection() {
369+
return (
370+
<section className="my-12">
371+
<SectionTitle id="insight" title="Insight" />
372+
<div className="mb-6 border-b" />
373+
<Grid>
374+
<ArticleCardIndex
375+
href="/nebula"
376+
title="Nebula"
377+
description=""
378+
icon={InfraInsightIcon}
379+
/>
380+
</Grid>
381+
</section>
382+
);
383+
}
384+
374385
function SectionTitle(props: {
375386
title: string;
376387
id: string;

0 commit comments

Comments
 (0)