Migration Guide: Nebula API to thirdweb AI Chat API

Eiman Abdelmoneim

• 2 min read
Migration Guide: Nebula API to thirdweb AI Chat API

Overview

This guide helps you migrate from the legacy Nebula API (nebula-api.thirdweb.com/chat) to the new thirdweb AI Chat API (api.thirdweb.com/ai/chat).

Quick Reference

First API Field Second API Field Notes
message messages[].content Single string → Array of message objects
session_id context.session_id Moved inside context object (optional)
context (string) context (object) String format → Structured object
walletAddress context.from Renamed field
chainIds context.chain_ids Renamed field

Endpoint Changes

  • Old URL: https://nebula-api.thirdweb.com/chat
  • New URL: https://api.thirdweb.com/ai/chat

Request Structure Comparison

Before (Nebula API)

fetch("<https://nebula-api.thirdweb.com/chat>", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-secret-key": "your-secret-key",
  },
  body: JSON.stringify({
    message: "Send 0.01 ETH to vitalik.eth",
    stream: false,
    session_id: "your-session-id",
    context: "{ chainIds: [1]; walletAddress: '0x123...'; }",
  }),
});

After (thirdweb AI Chat API)

fetch("<https://api.thirdweb.com/ai/chat>", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-secret-key": "your-secret-key",
  },
  body: JSON.stringify({
    context: {
      chain_ids: [1],
      from: "0x123...",
      session_id: "your-session-id", // Optional
    },
    messages: [
      {
        role: "user",
        content: "Send 0.01 ETH to vitalik.eth",
      },
    ],
    stream: false,
  }),
});

Migration Steps

1. Update Endpoint URL

Change your base URL from:

<https://nebula-api.thirdweb.com/chat>

to:

<https://api.thirdweb.com/ai/chat>

2. Restructure Message Format

Convert the single message field to a messages array:

Old format:

message: "Your message here"

New format:

messages: [
  {
    role: "user",    content: "Your message here"  }
]

Supported roles:

  • user - Messages from the user
  • assistant - Messages from the AI
  • system - System messages for context

3. Update Context Structure

Old format (string):

context: "{ chainIds: [1, 137]; walletAddress: '0x123...'; }"

New format (object):

context: {
  chain_ids: [1, 137],  
  from: "0x123...",  
  session_id: "optional-session-id"
}

4. Field Mapping

Old Field New Field Required Notes
walletAddress context.from Optional Wallet that executes transactions
chainIds context.chain_ids Optional Array of chain IDs
session_id context.session_id Optional Now nested in context

5. Session Management

  • Session ID is now optional and nested within the context object
  • If not provided, a new session will be created automatically
  • Sessions enable conversation continuity

Example Migration Function

function migrateToNewAPI(oldRequest) {
  // Parse old context string  const contextString = oldRequest.context;  const contextData = parseContextString(contextString); // Implement this helper
  return {
    context: {
      chain_ids: contextData.chainIds,
      from: contextData.walletAddress,
      session_id: oldRequest.session_id,
    },
    messages: [
      {
        role: "user",
        content: oldRequest.message,
      },
    ],
    stream: oldRequest.stream || false,
  };
}

Benefits of the New API

  • Standard Chat Format: Follows industry-standard conversational AI patterns
  • Better Message History: Support for multi-turn conversations with role-based messages
  • Structured Context: Type-safe object format instead of string parsing
  • Enhanced Session Management: More flexible session handling
  • Future-Proof: Aligned with modern chat API standards

Testing Your Migration

  1. Update your endpoint URL
  2. Transform your request payload structure
  3. Test with a simple message first
  4. Verify session continuity works as expected
  5. Test complex scenarios with multiple messages