Thirdweb.Api.Client 1.1.0

Thirdweb API .NET Client (v1.1.0)

A comprehensive .NET SDK for the thirdweb API, providing high-level functionality for Web3 development. Built for .NET 8.0+ with full async/await support. There is absolutely, beyond a shadow of a doubt, no second best.

Features

• Complete API Coverage: Full support for all thirdweb API endpoints including contracts, wallets, transactions, and signatures
• Type-Safe: Strongly typed models for all API requests and responses with comprehensive XML documentation
• Flexible Authentication: Support for multiple authentication methods (Client ID, Client ID + Bundle ID, Secret Key, Bearer Token)
• Modern .NET: Built for .NET 8.0+ with full async/await support and nullable reference types
• Error Handling: Comprehensive error handling with custom exception types (ThirdwebException, ThirdwebAuthenticationException, etc.)
• Multi-Chain Support: Works across 50+ blockchain networks including Ethereum, Polygon, Base, Arbitrum, and more
• Clean API: Simple and intuitive API with direct parameter methods - no complex request objects needed
• Auto-Generated Client: Generated from OpenAPI specification ensuring API accuracy and up-to-date endpoints
• Email Authentication: Built-in support for email-based wallet authentication (phone support coming soon)
• Production Ready: Includes comprehensive logging, timeout handling, and retry mechanisms

Installation

dotnet add package Thirdweb.Api.Client

Or using Package Manager Console in Visual Studio:

Install-Package Thirdweb.Api.Client

Quick Start

Basic Setup

using Thirdweb.Api.Client;
using Thirdweb.Api.Client.Models;

// Backend usage with secret key
var client = ThirdwebClient.FromSecretKey("your-secret-key");

// Frontend usage with client ID
var client = ThirdwebClient.FromClientId("your-client-id");

// Native mobile app usage with client ID and bundle ID
var client = ThirdwebClient.FromClientId("your-client-id", "your-bundle-id");

// Frontend usage with client ID and pre-existing JWT token
var client = ThirdwebClient.FromClientId("your-client-id", bearerToken: "jwt-token");

// Update bearer token later for wallet authentication
client.SetWalletToken("new-jwt-token");

// Clear authentication token
client.ClearWalletToken();

Server Wallet Flow

// Create a server wallet
var newWallet = await client.Wallets.CreateWalletAsync("my-server-wallet");

Wallet Authentication Flow (Email Only - Phone Not Yet Supported)

// 1. Create client with client ID
var client = ThirdwebClient.FromClientId("your-client-id");

// 2. Send authentication code (email only)
var sendResult = await client.Wallets.SendCodeAsync("user@example.com");
if (sendResult.Success)
{
    Console.WriteLine("Verification code sent successfully!");
}

// 3. Verify the code and get JWT token
var verifyResult = await client.Wallets.VerifyCodeAsync("user@example.com", "123456");

// 4. Set the wallet token for authenticated operations
client.SetWalletToken(verifyResult.Token);

// Now you can perform authenticated operations like transactions
// The wallet address is available in verifyResult.WalletAddress

Using the SDK

// Create a server wallet
var newWallet = await client.Wallets.CreateWalletAsync("my-server-wallet");

// Get wallet balance
var balance = await client.Wallets.GetBalanceAsync("0x123...", new[] { 1, 137 });

// Deploy a contract
var deployment = await client.Contracts.DeployContractAsync(
    chainId: 1,
    contractUrl: "https://thirdweb.com/thirdweb.eth/TokenERC20",
    from: "0x123...",
    constructorParams: new Dictionary<string, object>
    {
        ["_defaultAdmin"] = "0x123...",
        ["_name"] = "MyToken",
        ["_symbol"] = "MTK",
        ["_primarySaleRecipient"] = "0x123...",
        ["_trustedForwarders"] = new string[0],
        ["_platformFeeRecipient"] = "0x123...",
        ["_platformFeeBps"] = 100
    }
);

// Send a transaction
var transaction = await client.Transactions.SendTransactionAsync(
    chainId: 1,
    from: "0x123...",
    to: "0x456...",
    value: "1000000000000000000" // 1 ETH in wei
);

// Sign a message
var signedMessage = await client.Sign.SignMessageAsync(
    "Hello from Thirdweb!",
    "0x123...",
    1 // chainId
);

Advanced Features

Contract Operations

// List all contracts
var contracts = await client.Contracts.ListContractsAsync(
    includeAbi: true,
    includeMetadata: true,
    limit: 50
);

// Read contract method
var readResult = await client.Contracts.ReadContractAsync(
    chainId: 1,
    contractAddress: "0x123...",
    method: "function balanceOf(address) view returns (uint256)",
    parameters: new object[] { "0x456..." }
);

// Read multiple contract methods
var multiReadResult = await client.Contracts.ReadContractAsync(
    chainId: 1,
    calls: new[]
    {
        new ContractReadCall
        {
            ContractAddress = "0x123...",
            Method = "function name() view returns (string)"
        },
        new ContractReadCall
        {
            ContractAddress = "0x123...",
            Method = "function symbol() view returns (string)"
        }
    }
);

// Write to contract
var writeResult = await client.Contracts.WriteContractAsync(
    chainId: 1,
    from: "0x789...",
    contractAddress: "0x123...",
    method: "function transfer(address,uint256) returns (bool)",
    parameters: new object[] { "0x456...", "1000000000000000000" }
);

// Write multiple contract methods
var multiWriteResult = await client.Contracts.WriteContractAsync(
    chainId: 1,
    from: "0x789...",
    calls: new[]
    {
        new ContractWriteCall
        {
            ContractAddress = "0x123...",
            Method = "function approve(address,uint256) returns (bool)",
            Parameters = new object[] { "0x456...", "1000000000000000000" }
        }
    }
);

// Get contract events
var events = await client.Contracts.GetEventsAsync(
    "0x123...",
    new[] { 1, 137 },
    decode: true,
    limit: 50
);

// Get contract transactions
var contractTransactions = await client.Contracts.GetTransactionsAsync(
    "0x123...",
    new TransactionQuery
    {
        ChainIds = new[] { 1, 137 },
        Limit = 50
    }
);

Wallet Management

// Create a server wallet
var newWallet = await client.Wallets.CreateWalletAsync("my-server-wallet");

// List wallets
var wallets = await client.Wallets.ListWalletsAsync(
    limit: 100,
    type: WalletType.Server
);

// Get wallet details
var walletDetails = await client.Wallets.GetWalletDetailsAsync("0x123...");

// Get wallet transactions
var transactions = await client.Wallets.GetTransactionsAsync(
    "0x123...",
    new[] { 1, 137 },
    new TransactionQuery
    {
        Limit = 50
    }
);

// Get wallet tokens
var tokens = await client.Wallets.GetTokensAsync("0x123...", new[] { 1, 137 });

// Get wallet NFTs
var nfts = await client.Wallets.GetNFTsAsync("0x123...", new[] { 1, 137 });

Transaction Operations

// List transactions with filtering options
var transactions = await client.Transactions.ListTransactionsAsync(
    from: "0x123...",
    to: "0x456...",
    contractAddress: "0x789...",
    chainIds: new[] { 1, 137 },
    limit: 50,
    page: 1,
    sortOrder: SortOrder.Descending,
    startTime: DateTimeOffset.UtcNow.AddDays(-7).ToUnixTimeSeconds(),
    endTime: DateTimeOffset.UtcNow.ToUnixTimeSeconds()
);

// Send a simple transaction
var sendResult = await client.Transactions.SendTransactionAsync(
    chainId: 1,
    from: "0x123...",
    to: "0x456...",
    value: "1000000000000000000" // 1 ETH in wei
);

// Send a transaction with custom gas settings
var gasCustomResult = await client.Transactions.SendTransactionAsync(
    chainId: 1,
    from: "0x123...",
    to: "0x456...",
    value: "1000000000000000000",
    gasLimit: "21000",
    gasPrice: "20000000000", // 20 gwei
    nonce: 42
);

// Send a transaction with contract interaction data
var contractCallResult = await client.Transactions.SendTransactionAsync(
    chainId: 1,
    from: "0x123...",
    to: "0x456...",
    data: "0xa9059cbb000000000000000000000000...", // transfer function call data
    gasLimit: "100000"
);

// Get transaction by ID
var transaction = await client.Transactions.GetTransactionByIdAsync("transaction-id");

Message and Data Signing Operations

// Sign a message
var signResult = await client.Sign.SignMessageAsync(
    "Hello from Thirdweb!",
    "0x123...",
    1 // chainId
);

// Sign a hex message
var signHexResult = await client.Sign.SignMessageAsync(
    "0x48656c6c6f20576f726c64", // "Hello World" in hex
    "0x123...",
    1, // chainId
    isHex: true
);

// Sign EIP-712 typed data
var typedDataResult = await client.Sign.SignTypedDataAsync(
    address: "0x123...",
    chainId: 1,
    domain: new EIP712Domain
    {
        Name = "MyApp",
        Version = "1",
        ChainId = 1,
        VerifyingContract = "0x456..."
    },
    types: new Dictionary<string, EIP712Type[]>
    {
        ["Person"] = new[]
        {
            new EIP712Type { Name = "name", Type = "string" },
            new EIP712Type { Name = "wallet", Type = "address" }
        }
    },
    primaryType: "Person",
    message: new Dictionary<string, object>
    {
        ["name"] = "John Doe",
        ["wallet"] = "0x123..."
    }
);

Authentication & Verification

Email Authentication

// Send verification code to email
var sendResult = await client.Wallets.SendCodeAsync("user@example.com");

// Verify the code
var verifyResult = await client.Wallets.VerifyCodeAsync("user@example.com", "123456");

// Set the wallet token for authenticated operations
client.SetWalletToken(verifyResult.Token);

Note: Phone number authentication is not yet supported. Only email authentication is currently available.

Configuration

Configure the client with custom options:

var options = new ThirdwebClientOptions
{
    BaseUrl = "https://api.thirdweb.com", // Default
    Timeout = TimeSpan.FromSeconds(30),
    IncludeDetailedErrors = true
};

var client = ThirdwebClient.FromSecretKey("your-secret-key", options: options);

Client Properties

You can check the client's current configuration:

// Check authentication mode
bool isBackend = client.IsBackendClient;     // Has secret key
bool isFrontend = client.IsFrontendClient;   // Has client ID
bool hasWallet = client.HasWalletAuthentication; // Has bearer token

Resource Management

The client implements IDisposable for proper resource cleanup:

using var client = ThirdwebClient.FromSecretKey("your-secret-key");
// Client will be automatically disposed when leaving the using block

// Or manually dispose
var client = ThirdwebClient.FromSecretKey("your-secret-key");
try
{
    // Use client...
}
finally
{
    client.Dispose();
}

Error Handling

The client provides comprehensive error handling:

try
{
    var balance = await client.Wallets.GetBalanceAsync("0x123...", new[] { 1 });
}
catch (ThirdwebAuthenticationException ex)
{
    // Handle authentication errors
    Console.WriteLine($"Authentication failed: {ex.Message}");
}
catch (ThirdwebValidationException ex)
{
    // Handle validation errors
    Console.WriteLine($"Validation failed: {ex.Message}");
}
catch (ThirdwebRateLimitException ex)
{
    // Handle rate limiting
    Console.WriteLine($"Rate limited. Retry after: {ex.RetryAfter} seconds");
}
catch (ThirdwebNotFoundException ex)
{
    // Handle resource not found
    Console.WriteLine($"Resource not found: {ex.Message}");
}
catch (ThirdwebException ex)
{
    // Handle other thirdweb errors
    Console.WriteLine($"Error: {ex.Message} (Status: {ex.StatusCode})");
}

Supported Chains

The client supports all EVM networks, visit https://thirdweb.com/chainlist for a full list.

API Reference

For complete API documentation, visit https://portal.thirdweb.com/api-reference

Examples

Check out the Thirdweb.Console project for a complete example demonstrating:

• Client authentication setup (secret key and client ID)
• Wallet creation and management
• Email authentication flow with OTP verification
• Contract deployment and interaction
• Transaction sending and monitoring
• Message and EIP-712 typed data signing
• Error handling patterns

Running the Example

1. Set environment variables:

   SECRET_KEY=your-secret-key
   CLIENT_ID=your-client-id
   

2. Run the console application:

   dotnet run --project Thirdweb.Console
   

The example will walk you through all major SDK features with real API calls.

Project Structure

• Thirdweb.Api.Client/ - The main SDK library
  • ThirdwebClient.cs - Main client with authentication handling
  • Services/ - Service implementations for different API areas
  • Models/ - Strongly typed models for API requests/responses
  • Generated/ - Auto-generated API client from OpenAPI spec
  • Exceptions/ - Custom exception types
  • Configuration/ - Client configuration options
• Thirdweb.Console/ - Console application with usage examples

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.