POST /chat

Request Body:

{
  "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:

{
  "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 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:

{
  "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:

• Parse the message field for human-readable transaction details
• Extract the transaction data from the actions array
• Present transaction details to the user for review
• Use a local wallet to sign the transaction
• Broadcast the signed transaction to the network

Example Implementation with thirdweb SDK:

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);