re-organized nebula documentation (#5839)

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

@@ -0,0 +1,189 @@
+### Send Message
+
+```http
+POST /chat
+```
+
+**Request Body:**
+```json
+{
+  "message": "Find the last 5 blocks",
+  "session_id": "abc",          
+  "stream": true,                
+  "context_filter": {            
+    "chain_ids": [137],          
+    "contract_addresses": ["0x..."],
+    "wallet_addresses": ["0x..."]
+  },
+  "execute_config": {            
+    "mode": "client",
+    "signer_wallet_address": "0x..."
+  }
+}
+```
+
+**Request Parameters:**
+
+- `message` (required)
+  - Type: string
+  - Description: The user's input message or command to be processed by Nebula
+
+- `session_id` (optional)
+  - Type: string
+  - Description: Identifier for maintaining conversation context
+  - Default: A new session will be created if omitted
+
+- `stream` (optional)
+  - Type: boolean
+  - Description: Controls whether the response is streamed or returned as a single response
+  - Default: false
+
+- `context_filter` (optional)
+  - Type: object
+  - Description: Controls which blockchain data sources are used for context
+  - Properties:
+    - `chain_ids`: Array of numbers representing blockchain network IDs
+    - `contract_addresses`: Array of strings containing contract addresses to focus on
+
+- `execute_config` (optional)
+  - Type: object
+  - Description: Configuration for transaction execution
+  - Properties:
+    - `mode`: String indicating execution mode (currently only "client" is supported)
+    - `signer_wallet_address`: String containing the wallet address that will sign transactions
+
+    #### Chat Messages
+
+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.
+
+**Example Response with Chat Message:**
+```json
+{
+  "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!",
+  "actions": [],
+  "session_id": "5d579903-5a63-434f-8667-788adfae9304",
+  "request_id": "d46cfb80-de6a-48a6-9a97-746e1708d066"
+}
+```
+
+Response properties:
+- `message`: A formatted string containing the response, which may include:
+  - Markdown formatting for better readability
+  - Technical data (hashes, addresses, numbers)
+  - Structured information about blockchain state
+- `actions`: Array of actions (empty when no transactions are needed)
+- `session_id`: Unique identifier for the current session
+- `request_id`: Unique identifier for the specific request
+
+#### Chat Actions
+
+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.
+
+**Example Response with Chat Action:**
+```json
+{
+  "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.",
+  "actions": [
+    {
+      "session_id": "437a0df7-d512-4ef4-95b5-6168ccbbe097",
+      "request_id": "c2b51ed6-da79-49ac-b411-206a42059509",
+      "type": "sign_transaction",
+      "source": "executor",
+      "data": "{\"chainId\": 11155111, \"to\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\", \"data\": \"0x\", \"value\": \"0x5af3107a4000\"}"
+    }
+  ],
+  "session_id": "437a0df7-d512-4ef4-95b5-6168ccbbe097",
+  "request_id": "c2b51ed6-da79-49ac-b411-206a42059509"
+}
+```
+
+**Action Properties:**
+- `session_id`: Unique identifier for the current session
+- `request_id`: Unique identifier for the specific request
+- `type`: The type of action (e.g., "sign_transaction")
+- `source`: Origin of the action (e.g., "executor")
+- `data`: Transaction parameters including:
+  - `chainId`: Network identifier (e.g., 11155111 for Sepolia)
+  - `to`: Recipient's address
+  - `data`: Transaction data (if any)
+  - `value`: Amount to send in wei
+
+When handling actions:
+1. Parse the `message` field for human-readable transaction details
+2. Extract the transaction data from the `actions` array
+3. Present transaction details to the user for review
+4. Use a local wallet to sign the transaction
+5. Broadcast the signed transaction to the network
+
+**Example Implementation with thirdweb SDK:**
+```javascript
+import { 
+  createThirdwebClient, 
+  prepareTransaction, 
+  sendTransaction,
+  privateKeyToAccount 
+} from "thirdweb";
+
+// Example function to handle the API response
+async function handleNebulaResponse(response) {
+  // Initialize thirdweb client
+  const client = createThirdwebClient({
+    secretKey: process.env.THIRDWEB_SECRET_KEY
+  });
+
+  // Initialize account
+  const account = privateKeyToAccount({
+    client,
+    privateKey: process.env.EOA_PRIVATE_KEY
+  });
+
+  // Check if we have any actions
+  if (response.actions && response.actions.length > 0) {
+    const action = response.actions[0];
+
+    // Parse the transaction data from the action
+    const txData = JSON.parse(action.data);
+
+    try {
+      // Prepare transaction with client
+      const transaction = prepareTransaction({
+        to: txData.to,
+        data: txData.data,
+        value: BigInt(txData.value),
+        chain: txData.chainId,
+        client
+      });
+
+      // Send transaction with account
+      const result = await sendTransaction({
+        transaction,
+        account
+      });
+
+      return result;
+    } catch (error) {
+      console.error("Error processing transaction:", error);
+      throw error;
+    }
+  }
+}
+
+// Example usage
+const response = await fetch('https://nebula-api.thirdweb.com/chat', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'x-secret-key': 'YOUR_THIRDWEB_SECRET_KEY'
+  },
+  body: JSON.stringify({
+    message: "send 0.0001 ETH on sepolia to vitalik.eth",
+    execute_config: {
+      mode: "client",
+      signer_wallet_address: "0xc3F2b2a12Eba0f5989cD75B2964E31D56603a2cE"
+    }
+  })
+});
+
+const data = await response.json();
+const result = await handleNebulaResponse(data);
+```

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

@@ -0,0 +1,13 @@
+#### Clear Session
+
+Clear a session's message history.
+
+```bash
+POST /session/{session_id}/clear
+```
+
+**Example curl:**
+```bash
+curl -X POST https://nebula-api.thirdweb.com/session/abc123/clear \
+  -H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY"
+```

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

@@ -0,0 +1,32 @@
+#### Create Session
+
+Create a new chat session.
+
+```bash
+POST /session
+```
+**Request Body:**
+```tsx
+{
+  "title": "My DeFi Research",     // Optional: Custom session title
+  "is_public": true,               // Optional: Make session publicly accessible
+  "context_filter": {              // Optional: Filter data sources
+    "chain_ids": [1],             
+    "contract_addresses": ["0x..."]
+  }
+}
+```
+
+**Example curl:**
+```bash
+curl -X POST https://nebula-api.thirdweb.com/session \
+  -H "Content-Type: application/json" \
+  -H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY" \
+  -d '{
+    "title": "My DeFi Research",
+    "is_public": true,
+    "context_filter": {
+      "chain_ids": [1]
+    }
+  }'
+```

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

@@ -0,0 +1,15 @@
+Delete Session
+
+
+Delete a session.
+
+```bash
+DELETE /session/{session_id}
+```
+
+Example curl:
+
+```bash
+curl -X DELETE https://nebula-api.thirdweb.com/session/abc123 \
+  -H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY"
+```

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

@@ -0,0 +1,77 @@
+### Execute
+
+Execute specific blockchain commands or actions. This endpoint is designed for direct command execution without the conversational context of the chat endpoint.
+
+```bash
+POST /execute
+```
+
+**Request Body:**
+```bash
+{
+  "message": "send 0.0001 ETH on sepolia to vitalik.eth",
+  "user_id": "default-user",
+  "stream": false,
+  "execute_config": {
+    "mode": "client",
+    "signer_wallet_address": "0xc3F2b2a12Eba0f5989cD75B2964E31D56603a2cE"
+  }
+}
+```
+
+**Request Parameters:**
+- `message` (required): The command to execute
+- `user_id` (optional): Identifier for the user making the request
+- `stream` (optional): Whether to stream the response
+- `execute_config` (optional): Configuration for transaction execution
+  - `mode`: Execution mode (currently only "client" is supported)
+  - `signer_wallet_address`: Address that will sign the transaction
+
+**Example Response:**
+```json
+{
+  "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.",
+  "actions": [
+    {
+      "session_id": "437a0df7-d512-4ef4-95b5-6168ccbbe097",
+      "request_id": "c2b51ed6-da79-49ac-b411-206a42059509",
+      "type": "sign_transaction",
+      "source": "executor",
+      "data": "{\"chainId\": 11155111, \"to\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\", \"data\": \"0x\", \"value\": \"0x5af3107a4000\"}"
+    }
+  ],
+  "session_id": "437a0df7-d512-4ef4-95b5-6168ccbbe097",
+  "request_id": "c2b51ed6-da79-49ac-b411-206a42059509"
+}
+```
+
+**Example curl:**
+```bash
+curl -X POST https://nebula-api.thirdweb.com/execute \
+  -H "Content-Type: application/json" \
+  -H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY" \
+  -d '{
+    "message": "send 0.0001 ETH on sepolia to vitalik.eth",
+    "user_id": "default-user",
+    "stream": false,
+    "execute_config": {
+      "mode": "client",
+      "signer_wallet_address": "0xc3F2b2a12Eba0f5989cD75B2964E31D56603a2cE"
+    }
+  }'
+```
+
+**Response Properties:**
+- `message`: A human-readable description of the action to be taken
+- `actions`: Array of actions to be executed
+  - `session_id`: Unique identifier for the session
+  - `request_id`: Unique identifier for this request
+  - `type`: The type of action (e.g., "sign_transaction")
+  - `source`: Origin of the action
+  - `data`: Transaction data in hexadecimal format including:
+    - `chainId`: Network identifier
+    - `to`: Recipient's address
+    - `data`: Transaction data
+    - `value`: Amount to send in hex
+- `session_id`: Session identifier for this execution
+- `request_id`: Unique identifier for this request

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

@@ -0,0 +1,28 @@
+#### Get Session
+
+Get details for a specific session.
+
+```bash
+GET /session/{session_id}
+```
+
+**Example curl:**
+```bash
+curl -X GET https://nebula-api.thirdweb.com/session/abc123 \
+  -H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY"
+```
+
+**Response:**
+```tsx
+{
+  "result": {
+    "id": "string",
+    "title": "string",
+    "model_name": "string",
+    "is_public": boolean,
+    "created_at": "datetime",
+    "updated_at": "datetime",
+    "messages": []
+  }
+}
+```

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

@@ -0,0 +1,29 @@
+#### List Sessions
+
+Retrieve available sessions for the authenticated account.
+
+```bash
+GET /session/list
+```
+
+**Example curl:**
+```bash
+curl -X GET https://nebula-api.thirdweb.com/session/list \
+  -H "x-secret-key: YOUR_THIRDWEB_SECRET_KEY"
+```
+
+**Response:**
+```bash
+{
+  "result": [
+    {
+      "id": "string",
+      "title": "string",
+      "model_name": "string",
+      "is_public": boolean,
+      "created_at": "datetime",
+      "updated_at": "datetime"
+    }
+  ]
+}
+```