3 months ago

Migration Guide: Nebula API to thirdweb AI Chat API

Eiman Abdelmoneim

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

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