Changelog

Giselle Chacon

At thirdweb, our mission is to help builders succeed — from those starting their first project to teams scaling to millions of users. To keep improving, we’ve added a new feedback and rating feature in support in dashboard after ticket closure.

How it works

  1. Go to your thirdweb dashboard, and at the team level, click Support from the left menu.
  2. Open and create tickets or cases directly from there.
  3. After an interaction with our AI agent or support team, and once your ticket is closed, you’ll see the option to:
    • ⭐ Leave a star rating
    • 💬 Add a quick comment about your experience

Why it matters

We take your feedback seriously. Every rating helps us identify what’s working well and where we can improve. This ensures we continue building the best tools and providing the best support for builders like you.

Support that scales with you

Our support team is here to help you integrate thirdweb and bring your ideas to life. Different plans come with different SLAs, which you can check out here: thirdweb.com/pricing.

We appreciate every single customer and your feedback is key to making thirdweb the best tool for builders. 🚀

Firekeeper

✨ New Features

Bridge API - Chain Discovery Endpoint

  • Endpoint: GET /v1/bridge/chains
  • Description: Retrieves a list of blockchain networks supported for bridging.
  • Details:
    • Returns chain ID, name, icon, and native currency details

Example Response:

{
"result": [
{
"chainId": 1,
"name": "Ethereum Mainnet",
"icon": "https://...",
"nativeCurrency": {
"name": "Ether",
"symbol": "ETH",
"decimals": 18
}
}
]
}

Bridge API - Fiat-to-Crypto Conversion Endpoint

  • Endpoint: GET /v1/bridge/convert
  • Description: Calculates the equivalent crypto token amount for a given fiat currency amount based on current market prices. This endpoint provides conversion rate estimates and does not execute any transactions.
  • Parameters:
    • from (required) - Source fiat currency (broad list supported)
    • fromAmount (required) - Fiat amount (positive number)
    • chainId (required) - Target blockchain chain ID
    • to (required) - Ethereum address of the target token
  • Response: Returns JSON with converted crypto amount.
  • Performance:
    • Smart caching (30s fresh, 5m stale)
    • Rate-limited, requires client authentication

Example Usage:

GET /v1/bridge/convert?from=USD&fromAmount=100&chainId=42161&to=0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9

🔄 Changes

  • Migration: Legacy endpoint pay.thirdweb.com/convert/fiatToCrypto replaced by /v1/bridge/convert.

Visit the full reference here.

Firekeeper

✨ New Features

Token Owners Endpoint (/v1/tokens/{chainId}/{address}/owners)

  • Multi-standard Support: Now supports ERC-20, ERC-721, and ERC-1155 token contracts (previously ERC-20 only)
  • NFT Collection Owners: Query all owners of an NFT collection without specifying a token ID
  • Specific NFT Token Owners: Query owners of a specific NFT token by providing the tokenId parameter

📝 API Changes

Request Parameters

  • Added optional tokenId parameter to filter NFT owners by specific token ID
    • When provided: Returns owners of the specific NFT token
    • When omitted: Returns collection-level owners for NFTs, or token holders for ERC-20, automatically detecting what kind of token it is.

Response Format

  • Added optional tokenId field to owner objects in responses
    • Present for NFT queries (ERC-721/ERC-1155)
    • Absent for ERC-20 token queries

Response Behavior by Token Type

  • ERC-20: Returns token holders with their balance amounts
  • ERC-721 Collection: Returns owners with their token IDs and amount "1"
  • ERC-721 Specific: Returns owners of the specified token ID
  • ERC-1155 Collection: Returns owners with their token IDs and balance amounts
  • ERC-1155 Specific: Returns owners of the specified token ID with their balance amounts

🔧 Improvements

  • Automatic Token Standard Detection: The API automatically detects whether a contract is ERC-20, ERC-721, or ERC-1155 using ERC-165
  • Enhanced Error Handling: Better error messages specific to each token standard
  • Consistent Pagination: All token types now return consistent pagination metadata (hasMore, limit, page)

📚 Documentation

  • Updated OpenAPI specifications with examples for all supported token standards
  • Clarified what the amount field represents for different token types
Joaquim Verges

Every project in the thirdweb dashboard now comes with a dedicated AI chat. Think of it as your dev companion in your web3 building journey.

What thirdweb AI can do for you

  • Transact with your connected dashboard wallet
  • Swap tokens with your connected dashboard wallet
  • Deploy contracts with rich metadata
  • Ask about contract addresses, ABI, events, transactions, etc
  • Ask about chain stats, block info, etc
  • Ask about a wallet transactions, tokens, nfts, etc
  • Query contract state
  • Upload files to IPFS
  • Convert units, encode or decode data, etc
  • Debug transactions
  • and more!

Other features

  • View all past conversations, including the ones created programmatically from your apps
  • Track token usage
  • Auto execute transactions with your server wallets (coming soon!)

All of these make thirdweb AI a great sidekick during and post development. Head over to your project dashboard and give it a spin!

What about Nebula?

We've rebranded Nebula to thirdweb AI - now generally available via dashboard and API. As part of this change, nebula.thirdweb.com will be sunsetted on September 30th 2025. Please migrate any assets from it before that.

Samina Kabir
Greg

For a while, we offered Payments as an all-in-one solution. It helped developers handle everything from accepting crypto payments to moving tokens across chains. But as we grew, we noticed the needs for a crypto checkout and a crypto bridge becoming distinct amongst users.

That’s why we’re breaking out our product and re-introducing Bridge alongside Payments.

Bridge

Bridge is built for token transfers and swaps across any chain. Instantly move assets where you need them whether that’s supporting cross-chain dApps, enabling multi-chain liquidity, or powering user experiences that feel seamless across the EVM network.

Payments

Payments is focused on accepting crypto payments for goods and services. It gives businesses and developers a simple, reliable way to collect crypto from users with all the tools you need to map your onchain checkout flow to offchain actions such as accounting or completing orders.


Why the Split?

When everything lived under “Payments,” it blurred the lines. Some needed a checkout solution, while others needed a cross-chain infrastructure tool.

By separating the products, we aim to:

  • Make it easier for you to choose the right tool for the job.
  • Double down on specialized improvements for each product.
  • Offer clearer docs, examples, and support paths depending on whether you’re building with Payments or Bridge.

What’s Next

We are deprecating the following endpoints: /payments/swap and /tokens/swap in favor of the new Bridge endpoint /bridge/swap. This deprecation will not break your application but we encourage you to swap out this endpoint to ensure you are up to date and receive the subsequent updates to the endpoint.

👉 Learn more about this change.

You will also notice a breakout of Payments and Bridge on dashboard and in our documentation.

👉 View the updated Payments documentation

👉 View the new Bridge documentation

👉 View the API reference

This update doesn’t affect your existing integrations right away — but moving forward, you’ll see dedicated updates, features, and roadmaps for both.

We appreciate your patience with all the changes!

If you have any further questions or need support in regards to this update, please do not hesitate to reach out.

Nischit Pradhan

As part of ongoing efforts to streamline and maintain our API, we are deprecating several Insight Service endpoints that have seen limited usage.

The following endpoints will be deprecated:

  • GET /v1/transactions/{contractAddress}/{signature}
  • GET /v1/tokens/transfers/transaction/{transaction_hash}
  • GET /v1/contracts/deployed-by/{address}
  • GET /v1/contracts/metadata/{address}
  • POST /v1/decode/{address}
  • GET /v1/nfts/transfers/transaction/{transaction_hash}

Timeline

  • Deprecation Announcement: Effective immediately.
  • Deprecation Period: These endpoints will remain available for 30 days to allow for migration.
  • Removal Date: After the deprecation period, these endpoints will be permanently disabled.

Impact

  • Existing applications that call these endpoints will need to migrate to supported alternatives.
  • If your integration does not use these endpoints, no action is required.

Alternatives

  • For transaction-related insights: use GET /v1/transactions.
  • For token transfers: use GET /v1/events with filters.
  • For NFT transfers: use GET /v1/events with transaction or address filters.

(Please refer to our latest [API documentation] for details.)

Greg

You can now specify custom slippage tolerance on the /bridge/swap endpoint. With the slippageToleranceBps parameter, you can specify how many basis points in slippage your swap can tolerate. Warning: Lower slippage tolerance values could result in reverted swaps.

Without this value specified, it will continue to use the default behavior of automatically calculated slippage tolerance.

curl https://api.thirdweb.com/v1/bridge/swap \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'x-client-id: YOUR_SECRET_TOKEN' \
--data '{
"exact": "input",
"tokenIn": {
"address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"chainId": 42161,
"amount": "100"
},
"tokenOut": {
"address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
"chainId": 42161,
"minAmount": "80"
},
"from": "0xEfc38EF8C09535b25e364b6d1a7C406D3972f2A9",
"slippageToleranceBps": 50
}'

Payments API

This parameter is also available directly on the payments API. Learn more in the API reference.

Firekeeper

The v1/wallets/{address}/tokens endpoint now exposes additional query parameters for fine-grained control over token retrieval:

New Query Parameters:

  • metadata (boolean, default: true) - Include/exclude token metadata
  • resolveMetadataLinks (boolean, default: true) - Resolve metadata links for richer data
  • includeSpam (boolean, default: false) - Include/exclude spam tokens
  • includeNative (boolean, default: true) - Include/exclude native tokens (ETH, MATIC, etc.)
  • sortBy (enum, default: "usd_value") - Sort by: balance, token_address, token_price, or usd_value
  • sortOrder (enum, default: "desc") - Sort order: asc or desc
  • includeWithoutPrice (boolean, default: true) - Include/exclude tokens without price data

Breaking Changes:

  • None - all new parameters are optional with backward-compatible defaults

Defaults Updated:

  • Default sorting changed from balance to usd_value (descending)
  • All inclusion filters default to maximum data coverage

Example Usage:

GET /v1/wallets/{address}/tokens?chainId=1&sortBy=usd_value&includeSpam=false&limit=50

Developer Notes:

  • Existing API calls continue to work unchanged
  • New defaults provide more useful token ordering (by USD value)
  • Filters allow customization for specific use cases (e.g., excluding spam, metadata-only requests)
Greg

We've deprecated the /payments/swap and /tokens/swap endpoints in favor of the /bridge/swap endpoint. This endpoint behaves the same as the pre-existing swap endpoints, allowing you to perform cross-chain swaps with both input and output-centric amounts. To learn more, see the thirdweb API reference.

curl -sS -X POST "https://api.thirdweb.com/v1/bridge/swap" \
-H "Content-Type: application/json" \
-H "x-secret-key: <YOUR_SECRET_KEY>" \
-d '{
"from": "0xYOUR_WALLET",
"exact": "input",
"tokenIn": { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "chainId": 42161, "amount": "1000000" },
"tokenOut": { "address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "chainId": 42161, "minAmount": "990000" }
}'
Joaquim Verges

New package: @thirdweb-dev/ai-sdk-provider - A thin provider that lets you plug thirdweb AI into the Vercel AI SDK.

It standardizes message parts, exposes wallet-aware tools (sign_transaction, sign_swap), and ships with types/utilities so you can build chat UIs that execute on-chain actions from AI responses.


If you’re using the Vercel AI SDK (ai / @ai-sdk/react) and want your agent to request blockchain actions safely, this provider gives you:

  • A server wrapper that streams AI output and tools.
  • A message schema (ThirdwebAiMessage) compatible with useChat.
  • Ready-made thirdweb tools wired for signing and swaps.

Installation

npm add @thirdweb-dev/ai-sdk-provider ai @ai-sdk/react

Usage with the AI SDK core

Create a thirdweb ai provider instance and compatible with the AI SDK core by calling createThirdwebAI() with your project secret key.

import { streamText } from "ai";
import { createThirdwebAI } from "@thirdweb-dev/ai-sdk-provider";
const thirdwebAI = createThirdwebAI({
secretKey: "<your-project-secret-key>",
});
const result = streamText({
model: thirdwebAI.chat({
context: {
chain_ids: [8453], // optional chain ids
from: "0x...", // optional from address
auto_execute_transactions: true, // optional, defaults to false
},
}),
messages: [
{
role: "user",
content: "Swap 0.01 ETH to USDC",
},
],
});

Usage with the AI SDK UI (React)

You can call useChat<ThirdwebAiMessage>() to get typed responses and tools. This works nicely with the AI elements components to quickly build a chat UI with blockchain capabilities.

"use client";
import { useState } from "react";
import { useChat, DefaultChatTransport } from "@ai-sdk/react";
import type { ThirdwebAiMessage } from "@thirdweb-dev/ai-sdk-provider";
export function Chat() {
const { messages, sendMessage } = useChat<ThirdwebAiMessage>();
// When a tool part arrives (e.g., type === "tool-sign_transaction"),
// render a thirdweb `TransactionButton` wired to the provided input.
return /* your UI */;
}

Checkout the playground example, for a more complete example, including how it handles session_id, renders reasoning text, and handles transaction confirmations.


Resources

Joaquim Verges

We’ve introduced Auto Execution to the /ai/chat endpoint.
When enabled, the AI will not only prepare transactions, swaps, or deployments — it will automatically execute them on behalf of the authenticated user or server wallet.

This dramatically reduces friction: no extra signing steps, no manual execution flows. Just describe what you want done, and it happens.


How it works

Enable Auto Execution by setting the flag in the context object:

"context": {
"from": "0x...", // the wallet address that will perform the transaction
"chain_ids": [1], // optional, but recommended
"auto_execute_transactions": true // enable auto execution
}

If the auto execute flag is false, or no "from" address is passed in, thirdweb AI will return the prepared transactions to be signed manually like before.


Authentication

Auto execution requires wallet authentication:

  • User wallets → pass Authorization: Bearer <user-jwt>
  • Server wallets → pass your project x-secret-key

Example Request

curl --location 'https://api.thirdweb.com/ai/chat' --header 'Authorization: Bearer <user-wallet-jwt>' --header 'x-client-id: <your-client-id>' --header 'Content-Type: application/json' --data '{
"messages": [
{
"content": "approve 5 USDC to joenrv.eth",
"role": "user"
}
],
"context": {
"from": "0x...",
"chain_ids": [8453],
"auto_execute_transactions": true
}
}'

Example Response

Approval transaction submitted!
- **Token:** USD Coin (USDC) (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
- **Amount:** 5 USDC (5,000,000 base units)
- **Approved Spender:** joenrv.eth (`0x2247d5d238d0f9d37184d8332aE0289d1aD9991b`)
- **Function:** approve(address,uint256)
- **Transaction ID:** 72bb183e-9bb0-4ef4-9b52-d8df73f39ed3
- **Network:** Base
Would you like to check the status of this transaction or approve a different amount?

Monitoring & Follow-ups

  • Each execution returns a Transaction ID
  • You can monitor this ID in your project dashboard or via the API
  • You can ask the Chat API follow-up questions about this transaction:
    • “What’s the status of my approval?”
    • “Give me the transaction receipt”
    • “Show me the explorer link”

Links

Firekeeper

Added

  • New Social Auth Endpoint: Introduced GET /v1/auth/social for simplified OAuth authentication
    • Single-step OAuth flow with automatic redirect handling
    • Supports all 12 OAuth providers: Google, Apple, Facebook, Discord, GitHub, X, Coinbase, Farcaster, Telegram, LINE, Twitch, Steam
    • Complete documentation with callback examples and JWT extraction guide

Deprecated

  • OAuth via /auth/initiate: The OAuth method in /v1/auth/initiate is now deprecated
    • Still functional but will show deprecation warnings
    • Please migrate to the new /v1/auth/social endpoint

Migration Guide

Before (Deprecated):

// Old OAuth initiation
POST /v1/auth/initiate
{
"method": "oauth",
"provider": "google",
"redirectUrl": "https://myapp.com/callback"
}
// Handle the rest yourself

After (Recommended):

// New simplified OAuth - just redirect user to:
GET /v1/auth/social?provider=google&redirectUrl=https://myapp.com/callback

Callback Handling:

// Extract the JWT token in your callback
const urlParams = new URLSearchParams(window.location.search);
const authResultString = urlParams.get("authResult");
const authResult = JSON.parse(authResultString!);
// Extract the JWT token
const token = authResult.storedToken.cookieString;
// Verify and use the JWT token
fetch("/v1/wallets/me", {
headers: {
Authorization: "Bearer " + jwtToken,
"x-secret-key": "your-secret-key",
},
});

Benefits of Migration

  • Simpler Integration: One-step OAuth flow instead of separate POST + redirecting yourself
  • Better Documentation: Clear (and AI-friendly) callback handling examples and JWT extraction
  • Consistent API: Follows standard OAuth redirect patterns
  • Future-Proof: The new endpoint will receive ongoing support and improvements
Greg

Earlier this week we launched the ability to deploy your own token right from the dashboard, complete with a liquidity pool and developer rewards. Today, we're releasing this same capability via the thirdweb API.

You can now programmatically:
  • Launch your token on a decentralized exchange
  • Set up a Uniswap V3 pool with a pairing and starting price of your choice
  • Earn rewards automatically on every trade
  • Get a token page that your community can use to purchase the token with crypto or fiat payments
fetch("https://api.thirdweb.com/v1/tokens", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-secret-key": "YOUR_SECRET_TOKEN",
},
body: JSON.stringify({
chainId: 42161,
name: "MyToken",
symbol: "MT",
description: "My very own token",
imageUrl: "https://picsum.photos/200",
from: "0xEfc38EF8C09535b25e364b6d1a7C406D3972f2A9",
maxSupply: 1000000000,
sale: {
type: "pool",
startingPrice: "100000",
amount: 1000000,
developerFeeBps: 10,
currency: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
},
}),
});

Your token becomes instantly available in the thirdweb dashboard and tradable via thirdweb Payments.

Supported Chains

This new flow is available on Ethereum, Base, Unichain, Arbitrum, Optimism, Polygon, , BNB, Avalanche C Chain, CELO, Blast, ZKsync, Zora, WorldChain and AppChain mainnets and their respective testnets


Try it out

To get started, check out the thirdweb API reference, or feed the LLMs.txt to your LLM of choice.

curl https://api.thirdweb.com/v1/tokens \
--request POST \
--header 'Content-Type: application/json' \
--header 'x-secret-key: YOUR_SECRET_TOKEN' \
--data '{
"chainId": 42161,
"name": "MyToken",
"symbol": "MT",
"description": "My very own token",
"imageUrl": "https://picsum.photos/200",
"from": "0xEfc38EF8C09535b25e364b6d1a7C406D3972f2A9",
"maxSupply": 1000000000,
"sale": {
"type": "pool",
"startingPrice": "100000",
"amount": 1000000,
"developerFeeBps": 10,
"currency": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
}
}'
Manan Tank
Yash Kumar

Launching an ERC20 token is now faster, easier, and more rewarding. Your community can start buying, trading, and holding from day one — while you earn fees in the background!

The new ERC20 token creation flow, you can:
  • Launch your token on a decentralized exchange
  • Set up a Uniswap V3 pool with your token
  • Earn rewards automatically on every trade
  • Airdrop certain supply tokens on launch
  • Get a token page that your community can use to purchase the token with crypto or fiat payments. Here's an Example
Token Distribution configuration UI

How it works

When you create your token, you set the lifetime total supply. Then, simply decide how to allocate it:

Airdrop Tokens

Reserve a portion of tokens for airdrops to a pre-selected list of recipients. Perfect for rewarding your early supporters

Uniswap Liquidity Pool

Make your token instantly tradable on launch and earn revenue from every trade

  • Allocate some supply to the pool.
  • Pair it with ETH or any ERC20 (no upfront liquidity needed).
  • Earn fees automatically (1% fee per trade — 70% goes directly to you).
Mint to your wallet

Any leftover supply is automatically minted to your wallet


Claim Rewards

Each trade earns 1% fee - 70% of which is earned by your wallet. You can easily claim the rewards by going to thirdweb Dashboard > Your Team > Your Project > Tokens > Select Token > Rewards and Click “Distribute Rewards” button

Rewards Page

Supported Chains

This new flow is available on Ethereum, Base, Unichain, Arbitrum, Optimism, Polygon, , BNB, Avalanche C Chain, CELO, Blast, ZKsync, Zora, WorldChain and AppChain mainnets and their respective testnets


Try it out

You can try out the new ERC20 token creation flow in thirdweb Dashboard > Your Team > Your Project > Tokens > Create Coin

Create Coin Page

Firekeeper

What's New

Instant Wallet Creation - Users can now create ephemeral wallets instantly without providing email, phone, or social accounts. Perfect for demos, testing, or onboarding new users to your dApp.

How It Works

// Create a guest wallet instantly
const response = await fetch(
"https://api.thirdweb.com/v1/auth/complete",
{
method: "POST",
headers: {
"x-secret-key": "your-secret-key",
"Content-Type": "application/json",
},
body: JSON.stringify({
method: "guest",
sessionId: "optional-session-id", // Auto-generated if not provided
}),
},
);
const { walletAddress, token } = await response.json();

Key Benefits

  • Zero Friction - No user information required
  • Instant Setup - Wallets created in milliseconds
  • Session Support - Optional sessionId for temporary persistence
  • Full Functionality - Sign messages, send transactions, interact with contracts
  • Easy Migration - Users can upgrade to permanent accounts later

Use Cases

  • Demo Applications - Let users try your dApp immediately
  • Testing Environments - Quick wallet creation for integration tests
  • Onboarding Flows - Reduce barriers for new users
  • Temporary Sessions - Perfect for short-lived interactions

API Endpoints

  • POST /v1/auth/complete - Create guest wallet
  • GET /v1/wallets/me - Get wallet info (with Bearer token)
  • All existing wallet operations work with guest wallets

Try it yourself

Ready to reduce onboarding friction? Get started with guest auth →

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 FieldSecond API FieldNotes
messagemessages[].contentSingle string → Array of message objects
session_idcontext.session_idMoved inside context object (optional)
context (string)context (object)String format → Structured object
walletAddresscontext.fromRenamed field
chainIdscontext.chain_idsRenamed 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 FieldNew FieldRequiredNotes
walletAddresscontext.fromOptionalWallet that executes transactions
chainIdscontext.chain_idsOptionalArray of chain IDs
session_idcontext.session_idOptionalNow 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
Joaquim Verges

We’ve added an OpenAI-compatible AI Chat endpoint specialized for blockchain interactions, powered by thirdweb’s 't0' model. It can query live on-chain data, analyze transactions, prepare contract calls, swaps, and more via a single /ai/chat call.

Docs: https://portal.thirdweb.com/ai/chat
Playground: https://playground.thirdweb.com/ai/chat
API reference: https://api.thirdweb.com/reference#tag/ai/post/ai/chat


Capabilities

  • Realtime chain data: balances, prices, metadata, transaction & contract insights.
  • Prepare on-chain operations: contract writes, native/token transfers, swaps, and deployments. Generates call data & parameters.
  • Actionable outputs: returns structured actions (e.g., sign_transaction) you can pass to your signing/execution flow.
  • Context-aware: include wallet + chain context for targeted answers.
  • OpenAI-compatible: works with standard Chat Completions clients using model: "t0".

Common use cases

  1. Explore blockchain data — find interesting contract and tokens, analyze transactions, follow transfers, etc
  2. Wallet assistant — “Send 10 USDC on Base to vitalik.eth”, "Swap 0.1 ETH to USDT on Arbitrum", etc
  3. Token launcher — Create tradeable tokens with natural language, generate images for the metadata.

Get started

1) HTTP example

const res = await fetch("https://api.thirdweb.com/ai/chat", {
method: "POST",
headers: {
"content-type": "application/json",
"x-secret-key": process.env.THIRDWEB_SECRET_KEY!, // project secret
},
body: JSON.stringify({
messages: [
{
role: "user",
content: "Transfer 0.01 ETH to vitalik.eth on Base",
},
],
stream: false,
context: {
from: "0xYourWallet",
chain_ids: [8453], // Base
},
}),
});
const json = await res.json();
// json.actions[0] may be { type: "sign_transaction", data: { to, value, data, chainId } }

2) OpenAI-compatible client (Python)

from openai import OpenAI
client = OpenAI(
base_url="https://api.thirdweb.com/ai", # uses OpenAI-compatible interface
api_key="YOUR_TW_SECRET_KEY", # maps to x-secret-key
)
resp = client.chat.completions.create(
model="t0",
messages=[{"role": "user", "content": "What's my USDC balance?"}],
stream=False,
extra_body={ "context": { "from": "0xYourWallet", "chain_ids": [8453] } },
)
print(resp)

Response shape

{
"message": "I've prepared a native transfer. Do you want to execute it?",
"session_id": "123",
"request_id": "456",
"actions": [
{
"type": "sign_transaction",
"data": {
"chainId": 8453,
"to": "0x...",
"value": "10000000000000000",
"data": "0x"
},
"source": "model"
}
]
}

Links

Docs: https://portal.thirdweb.com/ai/chat
Playground: https://playground.thirdweb.com/ai/chat
API reference: https://api.thirdweb.com/reference#tag/ai/post/ai/chat

Greg

We’ve expanded the Thirdweb API with three new endpoints that make it easier than ever to swap, send, and execute payments in just a few calls. Whether you’re moving tokens across chains, building custom checkout flows, or resuming a previously prepared payment, these new endpoints give you full control over the payment lifecycle — all with the same developer-friendly API.


Swap API

Instantly swap between tokens and across chains using any thirdweb wallet via POST /v1/payments/swap. Use the exact parameter to specify whether your amount is the input (pay) or output (receive) side.

curl -sS -X POST "https://api.thirdweb.com/v1/payments/swap" \
-H "Content-Type: application/json" \
-H "x-secret-key: <YOUR_SECRET_KEY>" \
-d '{
"from": "0xYOUR_WALLET",
"exact": "input",
"tokenIn": { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "chainId": 42161, "amount": "1000000" },
"tokenOut": { "address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "chainId": 42161, "minAmount": "990000" }
}'

API Reference →


Create Payment

Create an end-to-end payment that can bridge and/or swap under the hood with POST /v1/payments. Perfect for P2P transfers, checkouts, and payouts when you want a single call that returns the prepared steps to execute. Supports metadata and webhooks.

curl -sS -X POST "https://api.thirdweb.com/v1/payments" \
-H "Content-Type: application/json" \
-H "x-secret-key: <YOUR_SECRET_KEY>" \
-d '{
"name": "Course",
"description": "The complete JS course",
"imageUrl": "https://example.com/course.png",
"recipient": "0xMERCHANT_WALLET",
"token": { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "chainId": 42161, "amount": "1000000" }
}'

API Reference →


Execute Payment

Submit a previously created payment with POST /v1/payments/{id}. Use this to continue processing a payment you created earlier (for example after client-side signing/approval), while preserving the same payment ID for tracking and webhooks.

curl -sS -X POST "https://api.thirdweb.com/v1/payments/<ID>" \
-H "Content-Type: application/json" \
-H "x-secret-key: <YOUR_SECRET_KEY>" \
-d '{ "from": "0xBUYER_WALLET" }'

API Reference →

Greg

We've added Stargate to our growing list of supported providers in thirdweb Payments. This unlocks a number of chains such as Fuse, Kaia, and more. This will also augment all existing routes to provide better prices (when possible).

thirdweb Payments are built with a "single input" philosophy, meaning you will only need to hold one input token to complete a payment. Stargate and other LayerZero-based bridges require fees to be paid in the native token, which normally breaks the "single input" philosophy. We've rolled Stargate's fees into the input token, allowing for even LayerZero bridges to be used with a single input token.

Try Stargate and all other payments in the HTTP API or the SDK.