diff --git a/apps/portal/src/app/nebula/api-reference/chat/page.mdx b/apps/portal/src/app/nebula/api-reference/chat/page.mdx index ba428db248b..11faeb82d91 100644 --- a/apps/portal/src/app/nebula/api-reference/chat/page.mdx +++ b/apps/portal/src/app/nebula/api-reference/chat/page.mdx @@ -2,7 +2,7 @@ import { EndpointMetadata } from './EndpointMetadata'; -#### Chat Actions +# 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. diff --git a/apps/portal/src/app/nebula/api-reference/page.mdx b/apps/portal/src/app/nebula/api-reference/page.mdx index ed46cb0742e..9ffb69d50c0 100644 --- a/apps/portal/src/app/nebula/api-reference/page.mdx +++ b/apps/portal/src/app/nebula/api-reference/page.mdx @@ -1,3 +1,15 @@ +import { createMetadata } from "@doc"; + +export const metadata = createMetadata({ + image: { + title: "API Reference", + icon: "nebula", + }, + title: "thirdweb Nebula API Reference", + description: + "Explore the thirdweb Nebula API reference to unlock the most powerful AI to interact with the blockchain and start building AI powered web3 apps.", +}); + # Nebula API Reference Nebula provides a conversational interface to interact with blockchain data and services, and access to thirdweb tools. @@ -13,7 +25,9 @@ https://nebula-api.thirdweb.com ## Authentication -All API endpoints require authentication using the thirdweb secret key. Include this key in your request headers: +All API endpoints require authentication using the thirdweb secret key. [Learn how to obtain a secret key.](/nebula/get-started). + +Include this key in your request headers: ```bash x-secret-key: YOUR_THIRDWEB_SECRET_KEY @@ -31,161 +45,7 @@ curl -X POST https://nebula-api.thirdweb.com/chat \ }' ``` -## Sessions - -Sessions maintain conversation threads with the AI and can be: - -- Created explicitly via the `/session` endpoint -- Created automatically when sending a message without a session_id -- Reused to maintain context across multiple messages -- Configured with specific execution parameters - -Sessions persist your conversation history and custom configurations for blockchain data and thirdweb tools interactions. - -## Context Filters - -Control what blockchain data informs AI responses through context filtering: - -```json -{ - "context": { - "chain_ids": ["1"], // comma delimited list of chain ID's - "wallet_address": "0x..." // wallet address - } -} -``` - -Benefits: -- Filter by blockchain networks using chain IDs -- Target specific contract addresses -- Target specific wallet addresses -- Control context scope for relevant responses -- Optimize token usage and response relevance - -## Execute Configuration - -Configure transaction execution behavior using the execute config: - -```json -{ - "execute_config": { - "mode": "client", - "signer_wallet_address": "0x..." - } -} -``` - -Parameters: -- `mode`: Execution mode (currently supports "client") -- `signer_wallet_address`: Wallet address for transaction signing - -When mode is "client", Nebula returns an unsigned transaction for local wallet signing. - -## Response Handling - -Nebula API supports two types of response modes: streaming and non-streaming. The mode is controlled by the `stream` parameter in your request. - -### Non-Streaming Responses - -When `stream: false`, the API returns a single JSON response: - -```json -{ - "result": { - "message": "The last 5 blocks on polygon are...", - "session_id": "abc", - "message_id": "1234" - } -} -``` - -### Streaming Responses - -When `stream: true`, the API uses Server-Sent Events (SSE) to stream the response. You'll need to handle the following event types: - -1. `init`: Initializes the stream and provides session information -2. `presence`: Provides backend status updates about worker processing -3. `action`: Contains blockchain transaction or action data -4. `delta`: Contains chunks of the response message text -5. `error`: Contains error information if something goes wrong - -**Example SSE Stream:** -```tsx -event: init -data: { - "session_id": "f4b45429-9570-4ee8-8c8f-8b267429915a", - "request_id": "9efc7f6a-8576-4d9c-8603-f6c72aa72164", - "type": "init", - "source": "user", - "data": "" -} - -event: presence -data: { - "session_id": "f4b45429-9570-4ee8-8c8f-8b267429915a", - "request_id": "9efc7f6a-8576-4d9c-8603-f6c72aa72164", - "type": "presence", - "source": "executor", - "data": "Performing function execution: ExecuteNativeTransferClientSigning" -} - -event: action -data: { - "session_id": "f4b45429-9570-4ee8-8c8f-8b267429915a", - "request_id": "9efc7f6a-8576-4d9c-8603-f6c72aa72164", - "type": "sign_transaction", - "source": "executor", - "data": "{\"chainId\": 11155111, \"to\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\", \"data\": \"0x\", \"value\": \"0x5af3107a4000\"}" -} - -event: delta -data: {"v": "To send 0.0001 ETH on the Sepolia network"} - -event: delta -data: {"v": " to the address associated with"} -``` - -**JavaScript Example for Handling Streams:** -```javascript -const eventSource = new EventSource('/chat', { - headers: { - 'x-secret-key': 'YOUR_THIRDWEB_SECRET_KEY' - } -}); -let messageText = ''; - -eventSource.addEventListener('init', (event) => { - const data = JSON.parse(event.data); - console.log('Stream initialized:', data); -}); - -eventSource.addEventListener('presence', (event) => { - const data = JSON.parse(event.data); - console.log('Backend status:', data.data); -}); - -eventSource.addEventListener('action', (event) => { - const data = JSON.parse(event.data); - console.log('Received action:', data); - if (data.type === 'sign_transaction') { - // Handle transaction signing - handleTransaction(data); - } -}); - -eventSource.addEventListener('delta', (event) => { - const data = JSON.parse(event.data); - messageText += data.v; - console.log('Current message:', messageText); -}); - -eventSource.addEventListener('error', (event) => { - const error = JSON.parse(event.data); - console.error('Error:', error); - eventSource.close(); -}); -``` diff --git a/apps/portal/src/app/nebula/assets/streamed-response.png b/apps/portal/src/app/nebula/assets/streamed-response.png new file mode 100644 index 00000000000..a745cd36537 Binary files /dev/null and b/apps/portal/src/app/nebula/assets/streamed-response.png differ diff --git a/apps/portal/src/app/nebula/faqs/page.mdx b/apps/portal/src/app/nebula/faqs/page.mdx index 23340a39e84..2c8e606c3b5 100644 --- a/apps/portal/src/app/nebula/faqs/page.mdx +++ b/apps/portal/src/app/nebula/faqs/page.mdx @@ -10,7 +10,7 @@ Nebula supports the read and write context of any verified contract or any contr If you have a published contract you would like to enable for deployment through Nebula, please [contact us](https://thirdweb.com/contact-us). ### Does Nebula have memory from past conversations? -Nebula retains memory within the confines of a session. +Nebula retains memory within the confines of a session. [Learn more about sessions](/nebula/key-concepts/sessions). ### What is the context size of Nebula? The context size or window is 128k tokens. diff --git a/apps/portal/src/app/nebula/get-started/page.mdx b/apps/portal/src/app/nebula/get-started/page.mdx index cb8b58b3eee..69f82f416c8 100644 --- a/apps/portal/src/app/nebula/get-started/page.mdx +++ b/apps/portal/src/app/nebula/get-started/page.mdx @@ -1,7 +1,18 @@ -import { Step, Steps, DocImage, Callout } from "@doc"; +import { Step, Steps, DocImage, Callout, createMetadata } from "@doc"; import NewProject from "../assets/new-project.png"; import KeysSetup from "../assets/keys.png"; +export const metadata = createMetadata({ + image: { + title: "Get Started", + icon: "nebula", + }, + title: "Get started with thirdweb Nebula: Set up Guide", + description: + "How to start building web3 capable apps with thirdweb Nebula, the most powerful AI to interact with the blockchain.", +}); + + # Get Started Learn how to get set up and started with the Nebula API to successfully prepare and enable a connected user to sign a transfer . diff --git a/apps/portal/src/app/nebula/key-concepts/chat-execute/page.mdx b/apps/portal/src/app/nebula/key-concepts/chat-execute/page.mdx new file mode 100644 index 00000000000..29f6750fd0b --- /dev/null +++ b/apps/portal/src/app/nebula/key-concepts/chat-execute/page.mdx @@ -0,0 +1,5 @@ +# Chat & Execute endpoints + +The `/chat` endpoint is used for **natural language interactions** with the AI. It allows users to ask questions, get explanations, or retrieve blockchain-related insights, and execute transactions. + +The `/execute` endpoint is used for **triggering actual blockchain transactions** through AI-generated execution logic. This endpoint **performs actions** on-chain and is designed to be used without historical context. diff --git a/apps/portal/src/app/nebula/key-concepts/context-filters/page.mdx b/apps/portal/src/app/nebula/key-concepts/context-filters/page.mdx new file mode 100644 index 00000000000..8a1f8adec1f --- /dev/null +++ b/apps/portal/src/app/nebula/key-concepts/context-filters/page.mdx @@ -0,0 +1,24 @@ +# Context Filters + +Context filters help control what blockchain data the AI uses to generate responses. + +You can specify: + +- Chain IDs – Choose which blockchain networks to pull data from. +- Wallet Address – Focus on a specific wallet’s transactions, balances, and interactions. + +Benefits: + +- **More relevant answers:** AI focuses only on the data you care about. +- **Enable Scope**: Keep results relevant to networks and wallets specified. + +Example, + +```jsx +{ + "context": { + "chain_ids": ["1"], // Ethereum network + "wallet_address": "0x123...abc" // Specific wallet to analyze + } +} +``` \ No newline at end of file diff --git a/apps/portal/src/app/nebula/key-concepts/execute-configuration/page.mdx b/apps/portal/src/app/nebula/key-concepts/execute-configuration/page.mdx new file mode 100644 index 00000000000..1ad3106f765 --- /dev/null +++ b/apps/portal/src/app/nebula/key-concepts/execute-configuration/page.mdx @@ -0,0 +1,19 @@ +# Execute Configuration + +Configure transaction execution behavior using the execute config: + +```json +{ + "execute_config": { + "mode": "client", + "signer_wallet_address": "0x..." + } +} +``` + +Parameters: + +- `mode`: Execution mode (currently supports "client") +- `signer_wallet_address`: Wallet address for transaction signing + +When mode is "client", Nebula returns an unsigned transaction for local wallet signing. \ No newline at end of file diff --git a/apps/portal/src/app/nebula/key-concepts/response-handling/page.mdx b/apps/portal/src/app/nebula/key-concepts/response-handling/page.mdx new file mode 100644 index 00000000000..383a5019270 --- /dev/null +++ b/apps/portal/src/app/nebula/key-concepts/response-handling/page.mdx @@ -0,0 +1,134 @@ +import { DocImage } from '@doc'; +import StreamedResponse from "../../assets/streamed-response.png"; + +# Response Handling + +## Streamed vs non-streamed responses + +- **Streaming Responses**: This method streams data in real-time, providing immediate feedback as the response is generated. Set the `stream` parameter to `true` in your request, the API delivers responses via Server-Sent Events (SSE). +- **Non-Streaming Responses**: When the `stream` parameter is set to `false`, the API returns the complete response in a single JSON payload after processing is complete. + + + +For `stream:true`, you'll need to handle the following event types: + +- `init`: Initializes the stream and provides session information +- `presence`: Provides backend status updates about worker processing +- `action`: Contains blockchain transaction or action data +- `delta`: Contains chunks of the response message text +- `error`: Contains error information if something goes wrong + + +**Example SSE Stream:** + +```jsx +event: init +data: { + "session_id": "f4b45429-9570-4ee8-8c8f-8b267429915a", + "request_id": "9efc7f6a-8576-4d9c-8603-f6c72aa72164", + "type": "init", + "source": "user", + "data": "" +} + +event: presence +data: { + "session_id": "f4b45429-9570-4ee8-8c8f-8b267429915a", + "request_id": "9efc7f6a-8576-4d9c-8603-f6c72aa72164", + "type": "presence", + "source": "executor", + "data": "Performing function execution: ExecuteNativeTransferClientSigning" +} + +event: action +data: { + "session_id": "f4b45429-9570-4ee8-8c8f-8b267429915a", + "request_id": "9efc7f6a-8576-4d9c-8603-f6c72aa72164", + "type": "sign_transaction", + "source": "executor", + "data": "{\"chainId\": 11155111, \"to\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\", \"data\": \"0x\", \"value\": \"0x5af3107a4000\"}" +} + +event: delta +data: {"v": "To send 0.0001 ETH on the Sepolia network"} + +event: delta +data: {"v": " to the address associated with"} +``` +**JavaScript Example for handling streams:** + +```jsx +const eventSource = new EventSource("/chat", { + headers: { + "x-secret-key": "YOUR_THIRDWEB_SECRET_KEY", + }, +}); + +let messageText = ""; + +eventSource.addEventListener("init", (event) => { + const data = JSON.parse(event.data); + console.log("Stream initialized:", data); +}); + +eventSource.addEventListener("presence", (event) => { + const data = JSON.parse(event.data); + console.log("Backend status:", data.data); +}); + +eventSource.addEventListener("action", (event) => { + const data = JSON.parse(event.data); + console.log("Received action:", data); + if (data.type === "sign_transaction") { + // Handle transaction signing + handleTransaction(data); + } +}); + +eventSource.addEventListener("delta", (event) => { + const data = JSON.parse(event.data); + messageText += data.v; + console.log("Current message:", messageText); +}); + +eventSource.addEventListener("error", (event) => { + const error = JSON.parse(event.data); + console.error("Error:", error); + eventSource.close(); +}); +``` +## Response Format + +By default, responses are returned as JSON Objects. You may optionally specify the desired response format using the `response_format` parameter. + +- **JSON Object**: To receive the response as a JSON object, set `response_format` to `{ "type": "json_object" }`. +- **JSON Schema**: For responses adhering to a specific JSON schema, set `response_format` to `{ "type": "json_schema", "json_schema": { ... } }`, where you define the desired schema structure. + +Example with `json_schema` format, + +```jsx +curl -X POST https://nebula-api.thirdweb.com/chat \ +-H "Content-Type: application/json" \ +-H "x-secret-key: ...." \ +-d '{ + "message": "what is the balance of eimanabdel.eth on contract 0xddC761FEb956Caf62dfa1c8b42e9f33Df424715A on sepolia", + "stream": false, + "response_format": { + "type": "json_schema", + "json_schema": { + "type": "object", + "properties": { + "ens_name": { + "type": "string", + "description": "The ENS name being queried" + }, + "balance": { + "type": "integer", + "description": "The balance of the address on the specified contract" + } + }, + "required": ["ens_name", "balance"] + } + } +}' +``` \ No newline at end of file diff --git a/apps/portal/src/app/nebula/key-concepts/sessions/page.mdx b/apps/portal/src/app/nebula/key-concepts/sessions/page.mdx new file mode 100644 index 00000000000..437e2d1a602 --- /dev/null +++ b/apps/portal/src/app/nebula/key-concepts/sessions/page.mdx @@ -0,0 +1,15 @@ + +# Sessions + +Sessions are a way to maintain context across multiple interactions with a user. Since LLMs are stateless by default, sessions help simulate continuity. + +- Sessions are created automatically when calling `/chat` without a `session_id` or can be created explicitly by calling the `/session` endpoint. +- Sessions can be managed through the following endpoints: + - [Create Session](/api-reference/create-session) + - [Get Session](/api-reference/get-session) + - [Clear Session](/api-reference/clear-session) + - [Update Session](/api-reference/update-session) + - [Delete Session](/api-reference/delete-session) + - [List Sessions](/api-reference/list-sessions) + +- Sessions persist your conversation history, custom configurations for blockchain data, and thirdweb tools interactions. \ No newline at end of file diff --git a/apps/portal/src/app/nebula/page.mdx b/apps/portal/src/app/nebula/page.mdx index cf334a51e61..790109b7e65 100644 --- a/apps/portal/src/app/nebula/page.mdx +++ b/apps/portal/src/app/nebula/page.mdx @@ -3,6 +3,16 @@ import { DocImage, createMetadata, FeatureCard, GithubTemplateCard, Stack, Grid, import NebulaDiagram from "./assets/nebula-diagram.png"; import SupportedChains from "./assets/supported-chains.png"; +export const metadata = createMetadata({ + image: { + title: "Nebula Documentation", + icon: "nebula", + }, + title: "thirdweb Nebula Documentation", + description: + "thirdweb Nebula Docs : explore the Nebula API Reference and unlock the most powerful AI to interact with the blockchain & build AI powered web3 apps.", +}); + # What is Nebula? Natural language model with improved blockchain reasoning, autonomous transaction capabilities, and real-time access to the blockchain. @@ -34,18 +44,6 @@ Nebula is currently available in Alpha. [Join the waitlist.](https://thirdweb.co iconUrl={} /> - } - /> - - } - /> - + + - + ## Supported Chains -Nebula is supported on every EVM compatible chain. To view the full list, visit [thirdweb chainlist](https://thirdweb.com/chainlist). +Nebula is supported on every EVM compatible chain. To view the full list, visit [thirdweb chainlist](https://thirdweb.com/chainlist?service=nebula). diff --git a/apps/portal/src/app/nebula/plugins/eliza/page.mdx b/apps/portal/src/app/nebula/plugins/eliza/page.mdx index 73e210aa2ba..b883d6cf63e 100644 --- a/apps/portal/src/app/nebula/plugins/eliza/page.mdx +++ b/apps/portal/src/app/nebula/plugins/eliza/page.mdx @@ -1,7 +1,17 @@ -import { Callout, OpenSourceCard, Step, Steps, DocImage } from '@doc' +import { Callout, OpenSourceCard, Step, Steps, DocImage, createMetadata } from '@doc' import NewProject from "../../assets/new-project.png"; import KeysSetup from "../../assets/keys.png"; +export const metadata = createMetadata({ + image: { + title: "Eliza x Nebula", + icon: "nebula", + }, + title: "Integrate ElizaOS x thirdweb Nebula", + description: + "Learn about how you can unlock advanced AI capabilities for your app with thirdweb Nebula and Eliza Integration.", +}); + # Eliza Eliza is a simple, fast, and lightweight AI agent framework to build flexible, scalable, and secure conversational agents. diff --git a/apps/portal/src/app/nebula/plugins/openai/page.mdx b/apps/portal/src/app/nebula/plugins/openai/page.mdx index e3df8ab6ae6..86c087952cd 100644 --- a/apps/portal/src/app/nebula/plugins/openai/page.mdx +++ b/apps/portal/src/app/nebula/plugins/openai/page.mdx @@ -1,3 +1,15 @@ +import { createMetadata } from "@doc"; + +export const metadata = createMetadata({ + image: { + title: "OpenAI x Nebula", + icon: "nebula", + }, + title: "Integrate OpenAI x thirdweb Nebula", + description: + "Learn about how you can unlock advanced AI capabilities for your app with thirdweb Nebula and OpenAI integration.", +}); + # OpenAI ### Chat Completions API diff --git a/apps/portal/src/app/nebula/plugins/page.mdx b/apps/portal/src/app/nebula/plugins/page.mdx index 1a95ec2d7b1..e2b30ec2dfc 100644 --- a/apps/portal/src/app/nebula/plugins/page.mdx +++ b/apps/portal/src/app/nebula/plugins/page.mdx @@ -1,3 +1,15 @@ +import { createMetadata } from "@doc"; + +export const metadata = createMetadata({ + image: { + title: "Plugins & Integrations", + icon: "nebula", + }, + title: "thirdweb Nebula Compatible AI Plugins", + description: + "Learn about AI plugins supported by thirdweb Nebula, such as OpenAI & Eliza.", +}); + import { Callout } from '@doc' # Plugins diff --git a/apps/portal/src/app/nebula/prompt-guide/page.mdx b/apps/portal/src/app/nebula/prompt-guide/page.mdx index e2da10a8f36..3f58228c460 100644 --- a/apps/portal/src/app/nebula/prompt-guide/page.mdx +++ b/apps/portal/src/app/nebula/prompt-guide/page.mdx @@ -1,3 +1,15 @@ +import {createMetadata} from "@doc"; + +export const metadata = createMetadata({ + image: { + title: "Prompt Guide", + icon: "nebula", + }, + title: "thirdweb Nebula Prompt Guide", + description: + "A comprehensive prompt guide to help you unlock the most powerful AI to interact with the blockchain & build AI powered web3 apps.", +}); + # Prompt Guide Maximize the potential of Nebula. Whether you’re new to blockchain development or an experienced user, this document will help you craft prompts that fully leverage Nebula’s blockchain specific features. diff --git a/apps/portal/src/app/nebula/sidebar.tsx b/apps/portal/src/app/nebula/sidebar.tsx index 9ede09d6026..d35cf4122ba 100644 --- a/apps/portal/src/app/nebula/sidebar.tsx +++ b/apps/portal/src/app/nebula/sidebar.tsx @@ -1,11 +1,12 @@ import type { SideBar } from "@/components/Layouts/DocLayout"; -import { NebulaSideIcon, TypeScriptIcon } from "@/icons"; +import { NebulaSideIcon, TypeScriptIcon, UnityIcon } from "@/icons"; import { Blocks, Braces, Code, ExternalLink, + Key, MessageCircleQuestion, PencilRuler, Rocket, @@ -35,6 +36,32 @@ export const sidebar: SideBar = { href: "/nebula/get-started", icon: , }, + { + name: "Key Concepts", + icon: , + links: [ + { + name: "Chat & Execute", + href: "/nebula/key-concepts/chat-execute", + }, + { + name: "Context Filters", + href: "/nebula/key-concepts/context-filters", + }, + { + name: "Execute Config", + href: "/nebula/key-concepts/execute-configuration", + }, + { + name: "Response Handling", + href: "/nebula/key-concepts/response-handling", + }, + { + name: "Sessions", + href: "/nebula/key-concepts/sessions", + }, + ], + }, { name: "API Reference", href: "/nebula/api-reference", @@ -107,6 +134,11 @@ export const sidebar: SideBar = { href: "/references/typescript/v5/chat", icon: , }, + { + name: "Unity", + href: "/dotnet/nebula/quickstart", + icon: , + }, ], }, {