Skip to content

Commit 31d11fa

Browse files
saminacodessaminacodes
authored
re-organized nebula documentation (#5839)
1 parent 03bf859 commit 31d11fa

File tree

26 files changed

+760
-513
lines changed

26 files changed

+760
-513
lines changed

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

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
### Send Message
2+
3+
```http
4+
POST /chat
5+
```
6+
7+
**Request Body:**
8+
```json
9+
{
10+
"message": "Find the last 5 blocks",
11+
"session_id": "abc",
12+
"stream": true,
13+
"context_filter": {
14+
"chain_ids": [137],
15+
"contract_addresses": ["0x..."],
16+
"wallet_addresses": ["0x..."]
17+
},
18+
"execute_config": {
19+
"mode": "client",
20+
"signer_wallet_address": "0x..."
21+
}
22+
}
23+
```
24+
25+
**Request Parameters:**
26+
27+
- `message` (required)
28+
- Type: string
29+
- Description: The user's input message or command to be processed by Nebula
30+
31+
- `session_id` (optional)
32+
- Type: string
33+
- Description: Identifier for maintaining conversation context
34+
- Default: A new session will be created if omitted
35+
36+
- `stream` (optional)
37+
- Type: boolean
38+
- Description: Controls whether the response is streamed or returned as a single response
39+
- Default: false
40+
41+
- `context_filter` (optional)
42+
- Type: object
43+
- Description: Controls which blockchain data sources are used for context
44+
- Properties:
45+
- `chain_ids`: Array of numbers representing blockchain network IDs
46+
- `contract_addresses`: Array of strings containing contract addresses to focus on
47+
48+
- `execute_config` (optional)
49+
- Type: object
50+
- Description: Configuration for transaction execution
51+
- Properties:
52+
- `mode`: String indicating execution mode (currently only "client" is supported)
53+
- `signer_wallet_address`: String containing the wallet address that will sign transactions
54+
55+
#### Chat Messages
56+
57+
Chat messages are natural language responses from Nebula. They appear in the `message` field of the response and provide formatted information, explanations, or answers to your queries. Messages can include formatted text, blockchain data, and technical details.
58+
59+
**Example Response with Chat Message:**
60+
```json
61+
{
62+
"message": "The last block on the Arbitrum mainnet is block number **284204124**. Here are the details:\n\n- **Block Hash:** 0xf42e3d624ae1e3fd6b89d4680f39943eb1cd3b8f0606918ef818d3021b7724f1\n- **Parent Hash:** 0x4c45cd0964281833b070b633980d8f530debdd21dfbdbf6eddf96cc93cbaac8e\n- **Timestamp:** 1734063299\n- **Gas Used:** 5,064,851\n- **Gas Limit:** 1,125,899,906,842,624\n- **Base Fee per Gas:** 10,000,000\n- **Transaction Count:** 7\n- **Withdrawals Count:** 0\n\nIf you need any more information about this block or related transactions, feel free to ask!",
63+
"actions": [],
64+
"session_id": "5d579903-5a63-434f-8667-788adfae9304",
65+
"request_id": "d46cfb80-de6a-48a6-9a97-746e1708d066"
66+
}
67+
```
68+
69+
Response properties:
70+
- `message`: A formatted string containing the response, which may include:
71+
- Markdown formatting for better readability
72+
- Technical data (hashes, addresses, numbers)
73+
- Structured information about blockchain state
74+
- `actions`: Array of actions (empty when no transactions are needed)
75+
- `session_id`: Unique identifier for the current session
76+
- `request_id`: Unique identifier for the specific request
77+
78+
#### Chat Actions
79+
80+
Chat actions represent blockchain transactions or operations that Nebula has prepared in response to your request. The response includes both a detailed explanation in the `message` field and the actual transaction data in the `actions` array.
81+
82+
**Example Response with Chat Action:**
83+
```json
84+
{
85+
"message": "The transaction to transfer 0.0001 ETH to the address resolved from the ENS name `vitalik.eth` (which is `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`) is set up successfully. The simulation indicates that the transaction is likely to succeed.\n\nPlease proceed by signing and confirming the transaction.",
86+
"actions": [
87+
{
88+
"session_id": "437a0df7-d512-4ef4-95b5-6168ccbbe097",
89+
"request_id": "c2b51ed6-da79-49ac-b411-206a42059509",
90+
"type": "sign_transaction",
91+
"source": "executor",
92+
"data": "{\"chainId\": 11155111, \"to\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\", \"data\": \"0x\", \"value\": \"0x5af3107a4000\"}"
93+
}
94+
],
95+
"session_id": "437a0df7-d512-4ef4-95b5-6168ccbbe097",
96+
"request_id": "c2b51ed6-da79-49ac-b411-206a42059509"
97+
}
98+
```
99+
100+
**Action Properties:**
101+
- `session_id`: Unique identifier for the current session
102+
- `request_id`: Unique identifier for the specific request
103+
- `type`: The type of action (e.g., "sign_transaction")
104+
- `source`: Origin of the action (e.g., "executor")
105+
- `data`: Transaction parameters including:
106+
- `chainId`: Network identifier (e.g., 11155111 for Sepolia)
107+
- `to`: Recipient's address
108+
- `data`: Transaction data (if any)
109+
- `value`: Amount to send in wei
110+
111+
When handling actions:
112+
1. Parse the `message` field for human-readable transaction details
113+
2. Extract the transaction data from the `actions` array
114+
3. Present transaction details to the user for review
115+
4. Use a local wallet to sign the transaction
116+
5. Broadcast the signed transaction to the network
117+
118+
**Example Implementation with thirdweb SDK:**
119+
```javascript
120+
import {
121+
createThirdwebClient,
122+
prepareTransaction,
123+
sendTransaction,
124+
privateKeyToAccount
125+
} from "thirdweb";
126+
127+
// Example function to handle the API response
128+
async function handleNebulaResponse(response) {
129+
// Initialize thirdweb client
130+
const client = createThirdwebClient({
131+
secretKey: process.env.THIRDWEB_SECRET_KEY
132+
});
133+
134+
// Initialize account
135+
const account = privateKeyToAccount({
136+
client,
137+
privateKey: process.env.EOA_PRIVATE_KEY
138+
});
139+
140+
// Check if we have any actions
141+
if (response.actions && response.actions.length > 0) {
142+
const action = response.actions[0];
143+
144+
// Parse the transaction data from the action
145+
const txData = JSON.parse(action.data);
146+
147+
try {
148+
// Prepare transaction with client
149+
const transaction = prepareTransaction({
150+
to: txData.to,
151+
data: txData.data,
152+
value: BigInt(txData.value),
153+
chain: txData.chainId,
154+
client
155+
});
156+
157+
// Send transaction with account
158+
const result = await sendTransaction({
159+
transaction,
160+
account
161+
});
162+
163+
return result;
164+
} catch (error) {
165+
console.error("Error processing transaction:", error);
166+
throw error;
167+
}
168+
}
169+
}
170+
171+
// Example usage
172+
const response = await fetch('https://nebula-api.thirdweb.com/chat', {
173+
method: 'POST',
174+
headers: {
175+
'Content-Type': 'application/json',
176+
'x-secret-key': 'YOUR_THIRDWEB_SECRET_KEY'
177+
},
178+
body: JSON.stringify({
179+
message: "send 0.0001 ETH on sepolia to vitalik.eth",
180+
execute_config: {
181+
mode: "client",
182+
signer_wallet_address: "0xc3F2b2a12Eba0f5989cD75B2964E31D56603a2cE"
183+
}
184+
})
185+
});
186+
187+
const data = await response.json();
188+
const result = await handleNebulaResponse(data);
189+
```

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#### Clear Session
2+
3+
Clear a session's message history.
4+
5+
```bash
6+
POST /session/{session_id}/clear
7+
```
8+
9+
**Example curl:**
10+
```bash
11+
curl -X POST https://nebula-api.thirdweb.com/session/abc123/clear \
12+
-H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY"
13+
```

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
#### Create Session
2+
3+
Create a new chat session.
4+
5+
```bash
6+
POST /session
7+
```
8+
**Request Body:**
9+
```tsx
10+
{
11+
"title": "My DeFi Research", // Optional: Custom session title
12+
"is_public": true, // Optional: Make session publicly accessible
13+
"context_filter": { // Optional: Filter data sources
14+
"chain_ids": [1],
15+
"contract_addresses": ["0x..."]
16+
}
17+
}
18+
```
19+
20+
**Example curl:**
21+
```bash
22+
curl -X POST https://nebula-api.thirdweb.com/session \
23+
-H "Content-Type: application/json" \
24+
-H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY" \
25+
-d '{
26+
"title": "My DeFi Research",
27+
"is_public": true,
28+
"context_filter": {
29+
"chain_ids": [1]
30+
}
31+
}'
32+
```

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Delete Session
2+
3+
4+
Delete a session.
5+
6+
```bash
7+
DELETE /session/{session_id}
8+
```
9+
10+
Example curl:
11+
12+
```bash
13+
curl -X DELETE https://nebula-api.thirdweb.com/session/abc123 \
14+
-H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY"
15+
```

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

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
### Execute
2+
3+
Execute specific blockchain commands or actions. This endpoint is designed for direct command execution without the conversational context of the chat endpoint.
4+
5+
```bash
6+
POST /execute
7+
```
8+
9+
**Request Body:**
10+
```bash
11+
{
12+
"message": "send 0.0001 ETH on sepolia to vitalik.eth",
13+
"user_id": "default-user",
14+
"stream": false,
15+
"execute_config": {
16+
"mode": "client",
17+
"signer_wallet_address": "0xc3F2b2a12Eba0f5989cD75B2964E31D56603a2cE"
18+
}
19+
}
20+
```
21+
22+
**Request Parameters:**
23+
- `message` (required): The command to execute
24+
- `user_id` (optional): Identifier for the user making the request
25+
- `stream` (optional): Whether to stream the response
26+
- `execute_config` (optional): Configuration for transaction execution
27+
- `mode`: Execution mode (currently only "client" is supported)
28+
- `signer_wallet_address`: Address that will sign the transaction
29+
30+
**Example Response:**
31+
```json
32+
{
33+
"message": "The transaction to transfer 0.0001 ETH to the address resolved from the ENS name `vitalik.eth` (which is `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`) is set up successfully. The simulation indicates that the transaction is likely to succeed.\n\nPlease proceed by signing and confirming the transaction.",
34+
"actions": [
35+
{
36+
"session_id": "437a0df7-d512-4ef4-95b5-6168ccbbe097",
37+
"request_id": "c2b51ed6-da79-49ac-b411-206a42059509",
38+
"type": "sign_transaction",
39+
"source": "executor",
40+
"data": "{\"chainId\": 11155111, \"to\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\", \"data\": \"0x\", \"value\": \"0x5af3107a4000\"}"
41+
}
42+
],
43+
"session_id": "437a0df7-d512-4ef4-95b5-6168ccbbe097",
44+
"request_id": "c2b51ed6-da79-49ac-b411-206a42059509"
45+
}
46+
```
47+
48+
**Example curl:**
49+
```bash
50+
curl -X POST https://nebula-api.thirdweb.com/execute \
51+
-H "Content-Type: application/json" \
52+
-H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY" \
53+
-d '{
54+
"message": "send 0.0001 ETH on sepolia to vitalik.eth",
55+
"user_id": "default-user",
56+
"stream": false,
57+
"execute_config": {
58+
"mode": "client",
59+
"signer_wallet_address": "0xc3F2b2a12Eba0f5989cD75B2964E31D56603a2cE"
60+
}
61+
}'
62+
```
63+
64+
**Response Properties:**
65+
- `message`: A human-readable description of the action to be taken
66+
- `actions`: Array of actions to be executed
67+
- `session_id`: Unique identifier for the session
68+
- `request_id`: Unique identifier for this request
69+
- `type`: The type of action (e.g., "sign_transaction")
70+
- `source`: Origin of the action
71+
- `data`: Transaction data in hexadecimal format including:
72+
- `chainId`: Network identifier
73+
- `to`: Recipient's address
74+
- `data`: Transaction data
75+
- `value`: Amount to send in hex
76+
- `session_id`: Session identifier for this execution
77+
- `request_id`: Unique identifier for this request

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
#### Get Session
2+
3+
Get details for a specific session.
4+
5+
```bash
6+
GET /session/{session_id}
7+
```
8+
9+
**Example curl:**
10+
```bash
11+
curl -X GET https://nebula-api.thirdweb.com/session/abc123 \
12+
-H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY"
13+
```
14+
15+
**Response:**
16+
```tsx
17+
{
18+
"result": {
19+
"id": "string",
20+
"title": "string",
21+
"model_name": "string",
22+
"is_public": boolean,
23+
"created_at": "datetime",
24+
"updated_at": "datetime",
25+
"messages": []
26+
}
27+
}
28+
```

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#### List Sessions
2+
3+
Retrieve available sessions for the authenticated account.
4+
5+
```bash
6+
GET /session/list
7+
```
8+
9+
**Example curl:**
10+
```bash
11+
curl -X GET https://nebula-api.thirdweb.com/session/list \
12+
-H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY"
13+
```
14+
15+
**Response:**
16+
```bash
17+
{
18+
"result": [
19+
{
20+
"id": "string",
21+
"title": "string",
22+
"model_name": "string",
23+
"is_public": boolean,
24+
"created_at": "datetime",
25+
"updated_at": "datetime"
26+
}
27+
]
28+
}
29+
```

0 commit comments

Comments
 (0)