### Local Development Environment Setup

Source: https://github.com/vechain/vechain-kit/blob/main/README.md

Commands to initialize the development environment. This includes installing dependencies across the workspace, starting the build watcher, and launching the Next.js development server.

```bash
yarn install:all
yarn watch
yarn dev
```

--------------------------------

### Implement Complete Theme Configuration

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

A comprehensive example showing how to define a full VechainKitThemeConfig, including colors, buttons, fonts, and glass effects, then applying it via the VeChainKitProvider.

```typescript
import type { VechainKitThemeConfig } from '@vechain/vechain-kit';

const theme: VechainKitThemeConfig = {
    modal: {
        backgroundColor: isDarkMode ? '#1f1f1e' : '#ffffff',
    },
    textColor: isDarkMode ? 'rgb(223, 223, 221)' : '#2e2e2e',
    overlay: {
        backgroundColor: isDarkMode ? 'rgba(0, 0, 0, 0.6)' : 'rgba(0, 0, 0, 0.4)',
        blur: 'blur(3px)',
    },
    buttons: {
        secondaryButton: {
            bg: isDarkMode ? 'rgba(255, 255, 255, 0.05)' : 'rgba(0, 0, 0, 0.1)',
            color: isDarkMode ? 'rgb(223, 223, 221)' : '#2e2e2e',
            border: 'none',
        },
        primaryButton: {
            bg: isDarkMode ? '#3182CE' : '#2B6CB0',
            color: 'white',
            border: 'none',
        },
        loginButton: {
            bg: 'transparent',
            color: isDarkMode ? 'white' : '#1a1a1a',
            border: isDarkMode ? '1px solid rgba(255, 255, 255, 0.1)' : '1px solid #ebebeb',
        },
    },
    fonts: {
        family: 'Inter, sans-serif',
        sizes: { small: '12px', medium: '14px', large: '16px' },
        weights: { normal: 400, medium: 500, bold: 700 },
    },
    effects: {
        glass: { enabled: true, intensity: 'low' },
    },
};

<VeChainKitProvider theme={theme} {...otherProps}>
    {children}
</VeChainKitProvider>;
```

--------------------------------

### Run Development Server (Bash)

Source: https://github.com/vechain/vechain-kit/blob/main/examples/test-tailwind-vck/README.md

Commands to start the Next.js development server using different package managers. This allows for local development and testing.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Install VeChain Kit dependencies

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/README.md

Installs the core VeChain Kit package along with necessary peer dependencies including Chakra UI, TanStack Query, and DApp Kit.

```bash
yarn add @vechain/vechain-kit \
  @chakra-ui/react@^2.8.2 \
  @emotion/react@^11.14.0 \
  @emotion/styled@^11.14.0 \
  @tanstack/react-query@^5.64.2 \
  @vechain/dapp-kit-react@2.1.0-rc.1 \
  framer-motion@^11.15.0
```

--------------------------------

### VeTrade API Quote Request Example

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/src/utils/swap/README.md

This example demonstrates a GET request to the VeTrade API to retrieve a swap quote. It includes essential query parameters like token addresses, amount, recipient, slippage, and network type.

```text
GET https://vetrade.vet/api/quote/vck?fromAddress={tokenAddress}&toAddress={tokenAddress}&amountIn={amount}&recipient={userAddress}&slippageBps={basisPoints}&network={networkType}
```

--------------------------------

### JSON API Quote Response Example

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/src/utils/swap/README.md

Provides a concrete example of a JSON response from the VeTrade API for a swap quote. This illustrates the expected data format for `amountOut`, `amountOutMin`, `clauses`, and `path`.

```json
{
  "amountOut": "1000000000000000000",
  "amountOutMin": "990000000000000000",
  "clauses": [
    {
      "to": "0xE5fA980a6EfE5B79C2150a529da06AeF455963b6",
      "value": "0",
      "comment": "Swap on VeTrade",
      "functionCall": {
        "functionName": "swapExactTokensForTokens",
        "abi": [
          {
            "name": "amountIn",
            "type": "uint256"
          },
          {
            "name": "amountOutMin",
            "type": "uint256"
          },
          {
            "name": "path",
            "type": "address[]"
          },
          {
            "name": "to",
            "type": "address"
          },
          {
            "name": "deadline",
            "type": "uint256"
          }
        ],
        "args": [
          "1000000000000000000",
          "990000000000000000",
          ["0xTokenA", "0xTokenB"],
          "0xUserAddress",
          "1234567890"
        ]
      }
    }
  ],
  "path": ["0xTokenA", "0xTokenB"]
}
```

--------------------------------

### Apply Partial Theme Configurations

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Demonstrates how to override specific parts of the theme without providing a full configuration object. This allows for minimal code changes while maintaining default styles.

```typescript
// Minimal config - just enable glass effects
theme={{
    effects: {
        glass: { enabled: true, intensity: 'medium' },
    },
}}

// Customize overlay only
theme={{
    overlay: {
        backgroundColor: 'rgba(0, 0, 0, 0.5)',
        blur: 'blur(5px)',
    },
}}

// Customize secondary buttons only
theme={{
    buttons: {
        secondaryButton: { bg: '#6366f1', color: '#ffffff', border: 'none' },
    },
}}
```

--------------------------------

### Project Development Commands

Source: https://github.com/vechain/vechain-kit/blob/main/CLAUDE.md

Standardized Yarn scripts for managing the VeChain Kit monorepo, including dependency installation, building, linting, and running development environments.

```bash
yarn install:all
yarn kit:build
yarn kit:typecheck
yarn lint
yarn dev:next-template
yarn clean
yarn purge
```

--------------------------------

### End-to-End Testing with Playwright

Source: https://github.com/vechain/vechain-kit/blob/main/README.md

Commands to manage and execute E2E tests. Includes installing required browser binaries, running tests in headless or headed modes, and generating test reports.

```bash
cd tests/e2e
yarn install-browsers
yarn test
yarn test:headed
yarn report
```

--------------------------------

### Configure Modal Overlay Styles in VeChain Kit

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Shows how to customize the modal overlay's appearance, including its background color and blur effect. This configuration allows for visual adjustments to the modal backdrop.

```tsx
overlay: {
    backgroundColor: 'rgba(0, 0, 0, 0.6)', // Overlay background color
    blur: 'blur(10px)', // Overlay blur effect
}
```

--------------------------------

### GET /api/quote/vck

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/src/utils/swap/README.md

Retrieves a swap quote from the VeTrade aggregator, providing expected output amounts and transaction clauses for execution.

```APIDOC
## GET /api/quote/vck

### Description
Fetches a token swap quote from the VeTrade aggregator. It returns the expected output amount and the necessary transaction clauses to execute the swap on-chain.

### Method
GET

### Endpoint
/api/quote/vck

### Parameters
#### Query Parameters
- **fromAddress** (string) - Required - Source token address (hex string)
- **toAddress** (string) - Required - Destination token address (hex string)
- **amountIn** (string) - Required - Input amount as decimal string
- **recipient** (string) - Required - User address receiving output tokens
- **slippageBps** (number) - Required - Slippage in basis points (e.g., 100 = 1%)
- **network** (string) - Required - Network type (main, test, or solo)

### Request Example
GET https://vetrade.vet/api/quote/vck?fromAddress=0xTokenA&toAddress=0xTokenB&amountIn=1000000000000000000&recipient=0xUserAddress&slippageBps=100&network=main

### Response
#### Success Response (200)
- **amountOut** (string) - Expected output amount (decimal string)
- **amountOutMin** (string) - Minimum output with slippage (decimal string)
- **clauses** (Array) - List of transaction clauses to execute
- **path** (Array) - Token swap path

#### Response Example
{
  "amountOut": "1000000000000000000",
  "amountOutMin": "990000000000000000",
  "clauses": [
    {
      "to": "0xE5fA980a6EfE5B79C2150a529da06AeF455963b6",
      "value": "0",
      "comment": "Swap on VeTrade",
      "functionCall": {
        "functionName": "swapExactTokensForTokens",
        "abi": [
          { "name": "amountIn", "type": "uint256" },
          { "name": "amountOutMin", "type": "uint256" },
          { "name": "path", "type": "address[]" },
          { "name": "to", "type": "address" },
          { "name": "deadline", "type": "uint256" }
        ],
        "args": ["1000000000000000000", "990000000000000000", ["0xTokenA", "0xTokenB"], "0xUserAddress", "1234567890"]
      }
    }
  ],
  "path": ["0xTokenA", "0xTokenB"]
}
```

--------------------------------

### Customize VeChain Kit Theme with React Provider

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Demonstrates how to apply a custom theme to VeChain Kit components using the VeChainKitProvider. It shows configuration for modal background, text color, overlay, buttons, and glass effects. This is the primary method for theme customization.

```tsx
<VeChainKitProvider
    theme={{
        modal: {
            backgroundColor: isDarkMode ? '#1f1f1e' : '#ffffff',
        },
        textColor: isDarkMode ? 'rgb(223, 223, 221)' : '#2e2e2e',
        overlay: {
            backgroundColor: 'rgba(0, 0, 0, 0.6)',
            blur: 'blur(3px)',
        },
        buttons: {
            secondaryButton: {
                bg: 'rgba(255, 255, 255, 0.1)',
                color: '#ffffff',
                border: 'none',
            },
        },
        effects: {
            glass: {
                enabled: true,
                intensity: 'low',
            },
        },
    }}
    // ... other props
>
    {children}
</VeChainKitProvider>
```

--------------------------------

### Configure VechainKit Theme with TypeScript

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Use the VechainKitThemeConfig type to define custom theme properties such as modal background colors and text colors. This provides full IDE autocomplete support for your configuration object.

```tsx
import type { VechainKitThemeConfig } from '@vechain/vechain-kit';

const myTheme: VechainKitThemeConfig = {
    modal: {
        backgroundColor: '#ffffff',
    },
    textColor: '#2e2e2e',
    // ... your config
};
```

--------------------------------

### Configure Glass Morphism Effects

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Defines the structure for enabling glass effects and setting intensity levels. The system automatically adjusts blur and opacity based on the chosen intensity.

```typescript
effects: {
    glass: {
        enabled: true, // Enable glass effects
        intensity: 'low' | 'medium' | 'high', // Glass intensity
    },
    backdropFilter: {
        modal: 'blur(15px)', // Optional: override modal blur
    },
}
```

--------------------------------

### Combine Multiple Button Styles in VeChain Kit Theme

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Illustrates how to define styles for multiple button types within a single `buttons` configuration object. This allows for consolidated theming of various button variants like secondary, primary, and login buttons.

```tsx
buttons: {
    secondaryButton: {
        bg: 'rgba(255, 255, 255, 0.1)',
        color: '#ffffff',
        border: 'none',
    },
    primaryButton: {
        bg: '#3182CE',
        color: '#ffffff',
        border: 'none',
    },
    loginButton: {
        bg: 'transparent',
        color: '#ffffff',
        border: '1px solid rgba(255, 255, 255, 0.1)',
    },
}
```

--------------------------------

### Customize Login Button Styles in VeChain Kit

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Defines the styling for login buttons within VeChain Kit, specifying background color, text color, and border. This applies to the `loginIn` button variant. Hover and active states are managed automatically.

```tsx
buttons: {
    loginButton: {
        bg: 'transparent', // Background color
        color: '#ffffff', // Text color
        border: '1px solid rgba(255, 255, 255, 0.1)', // Border (full CSS string)
    },
}
```

--------------------------------

### Customize Secondary Button Styles in VeChain Kit

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Defines the styling for secondary buttons within VeChain Kit components. This includes setting the background color, text color, and border properties. Hover and active states are managed automatically.

```tsx
buttons: {
    secondaryButton: {
        bg: 'rgba(255, 255, 255, 0.1)', // Background color
        color: '#ffffff', // Text color
        border: '1px solid rgba(255, 255, 255, 0.2)', // Border (full CSS string)
    },
}
```

--------------------------------

### Customize Only Font Family in VeChain Kit

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Demonstrates how to customize only the font family within the VeChain Kit theme configuration. This approach allows for targeted font changes without affecting other font properties like size or weight.

```tsx
fonts: {
    family: 'Inter, sans-serif',
}
```

--------------------------------

### Customize Primary Button Styles in VeChain Kit

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Specifies the styling for primary buttons in VeChain Kit, including background color, text color, and border. These styles apply to elements with the `vechainKitPrimary` variant. Hover and active states are handled by default.

```tsx
buttons: {
    primaryButton: {
        bg: '#3182CE', // Background color
        color: '#ffffff', // Text color
        border: 'none', // Border (full CSS string)
    },
}
```

--------------------------------

### Customize Tertiary Button Styles in VeChain Kit

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Configures the appearance of tertiary buttons in VeChain Kit, setting their background color, text color, and border. These styles are applied to `vechainKitTertiary` buttons. Automatic handling of hover and active states is included.

```tsx
buttons: {
    tertiaryButton: {
        bg: 'transparent', // Background color
        color: '#ffffff', // Text color
        border: 'none', // Border (full CSS string)
    },
}
```

--------------------------------

### Configure Font Properties in VeChain Kit Theme

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Shows how to customize font family, sizes, and weights for VeChain Kit components. This configuration affects only VeChain Kit elements and does not leak into the host application's styles. Unspecified properties will use default values.

```tsx
fonts: {
    family: 'Inter, sans-serif', // Font family (e.g., "Inter, sans-serif", "'Roboto', sans-serif")
    sizes: {
        small: '12px', // Font size for small text
        medium: '14px', // Font size for medium text
        large: '16px', // Font size for large text
    },
    weights: {
        normal: 400, // Normal font weight
        medium: 500, // Medium font weight
        bold: 700, // Bold font weight
    },
}
```

--------------------------------

### Customize Only Font Sizes in VeChain Kit

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/THEME_CUSTOMIZATION.md

Shows how to selectively customize font sizes for different text scales (small, medium, large) within the VeChain Kit theme. This enables fine-grained control over text appearance without altering font family or weight.

```tsx
fonts: {
    sizes: {
        medium: '15px',
        large: '18px',
    },
}
```

--------------------------------

### Configure VeChainKitProvider for React Applications

Source: https://context7.com/vechain/vechain-kit/llms.txt

Initializes the global context for the VeChain Kit SDK. It manages network settings, Privy social login configurations, fee delegation for gasless transactions, and UI theming.

```typescript
'use client';

import { VeChainKitProvider } from '@vechain/vechain-kit';

export function Providers({ children }: { children: React.ReactNode }) {
    return (
        <VeChainKitProvider
            network={{
                type: 'main',
                nodeUrl: 'https://mainnet.vechain.org',
            }}
            privy={{
                appId: 'your-privy-app-id',
                clientId: 'your-privy-client-id',
                appearance: {
                    loginMessage: 'Sign in to My dApp',
                    logo: 'https://example.com/logo.png',
                    accentColor: '#3182CE',
                },
                loginMethods: ['email', 'google', 'github', 'passkey'],
                embeddedWallets: {
                    createOnLogin: 'all-users',
                },
            }}
            feeDelegation={{
                delegatorUrl: 'https://sponsor.vechain.energy/by/123',
                delegateAllTransactions: true,
            }}
            dappKit={{
                allowedWallets: ['veworld', 'sync2', 'wallet-connect'],
                walletConnectOptions: {
                    projectId: 'your-walletconnect-project-id',
                    metadata: {
                        name: 'My dApp',
                        description: 'A VeChain dApp',
                        url: 'https://mydapp.com',
                        icons: ['https://mydapp.com/icon.png'],
                    },
                },
            }}
            loginMethods={[
                { method: 'vechain', gridColumn: 4 },
                { method: 'ecosystem', gridColumn: 4 },
                { method: 'dappkit', gridColumn: 4 },
                { method: 'email', gridColumn: 2 },
                { method: 'google', gridColumn: 2 },
            ]}
            darkMode={true}
            language="en"
            defaultCurrency="usd"
            allowCustomTokens={true}
            legalDocuments={{
                termsAndConditions: [{
                    url: 'https://example.com/terms',
                    version: 1,
                    required: true,
                }],
                privacyPolicy: [{
                    url: 'https://example.com/privacy',
                    version: 1,
                    required: true,
                }],
            }}
        >
            {children}
        </VeChainKitProvider>
    );
}
```

--------------------------------

### Configure VeChainKitProvider

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/README.md

Wraps the React application with the VeChainKitProvider to enable blockchain connectivity and wallet integration features.

```typescript
'use client';

import { VeChainKitProvider } from '@vechain/vechain-kit';

export function Providers({ children }: { children: React.ReactNode }) {
    return (
        <VeChainKitProvider>
            {children}
        </VeChainKitProvider>
    );
}
```

--------------------------------

### Initialize Swap Aggregators

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/src/utils/swap/README.md

Initializes the swap aggregator system for a specific network. Returns an array of available aggregators such as VeTrade.vet or BetterSwap.io.

```typescript
const aggregators = getSwapAggregators(networkType);
```

--------------------------------

### Implement WalletButton for Authentication UI

Source: https://context7.com/vechain/vechain-kit/llms.txt

Renders a pre-built UI component for handling wallet connections. It supports multiple display variants for mobile and desktop and allows customization via Chakra UI props.

```typescript
'use client';

import { WalletButton } from '@vechain/vechain-kit';

export function Header() {
    return (
        <nav>
            <WalletButton
                mobileVariant="iconAndDomain"
                desktopVariant="iconDomainAndAddress"
                connectionVariant="modal"
                label="Connect Wallet"
                buttonStyle={{
                    colorScheme: 'blue',
                    size: 'md',
                    borderRadius: 'full',
                }}
            />
        </nav>
    );
}
```

--------------------------------

### Access Configuration with useVeChainKitConfig

Source: https://context7.com/vechain/vechain-kit/llms.txt

The useVeChainKitConfig hook provides access to the current VeChainKit environment settings, including network, theme, language, and currency. It also exposes setter functions to update configuration state dynamically.

```typescript
'use client';

import { useVeChainKitConfig } from '@vechain/vechain-kit';

export function ConfigDisplay() {
    const {
        network,
        darkMode,
        currentLanguage,
        currentCurrency,
        setLanguage,
        setCurrency,
        privy,
        feeDelegation,
        allowCustomTokens,
    } = useVeChainKitConfig();

    return (
        <div>
            <h3>Current Configuration</h3>
            <p>Network: {network.type}</p>
            <p>Node URL: {network.nodeUrl}</p>
            <p>Dark Mode: {darkMode ? 'Yes' : 'No'}</p>
            <p>Language: {currentLanguage}</p>
            <p>Currency: {currentCurrency}</p>
            <p>Fee Delegation: {feeDelegation ? 'Enabled' : 'Disabled'}</p>
            <p>Privy: {privy ? 'Configured' : 'Not configured'}</p>

            {/* Change language */}
            <select
                value={currentLanguage}
                onChange={(e) => setLanguage(e.target.value)}
            >
                <option value="en">English</option>
                <option value="de">Deutsch</option>
                <option value="fr">Francais</option>
                <option value="zh">Chinese</option>
            </select>

            {/* Change currency */}
            <select
                value={currentCurrency}
                onChange={(e) => setCurrency(e.target.value)}
            >
                <option value="usd">USD</option>
                <option value="eur">EUR</option>
                <option value="gbp">GBP</option>
            </select>
        </div>
    );
}
```

--------------------------------

### Project Release Management

Source: https://github.com/vechain/vechain-kit/blob/main/README.md

Commands to automate the release process, including version bumping, dependency management, and publishing packages to the registry.

```bash
yarn prepare:release X.Y.Z
yarn publish:release X.Y.Z
```

--------------------------------

### Implement WalletButton component

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/README.md

Adds a pre-built WalletButton component to the UI, allowing users to connect their wallets to the application.

```typescript
'use client';

import { WalletButton } from '@vechain/vechain-kit';

export function Page() {
    return <WalletButton />;
}
```

--------------------------------

### Query Single Contract Call with useCallClause (TypeScript)

Source: https://github.com/vechain/vechain-kit/blob/main/CLAUDE.md

Demonstrates how to perform a single contract call using the `useCallClause` hook. It includes options for enabling the query conditionally, transforming data with `select`, setting `staleTime`, and configuring retry logic based on error messages. Dependencies include `useVeChainKitConfig`, `getConfig`, and `ethers`.

```typescript
export const useTokenBalance = (address?: string) => {
  const { network } = useVeChainKitConfig();
  return useCallClause({
    abi: VOT3__factory.abi,
    address: getConfig(network.type).contractAddress as `0x${string}`,
    method: 'balanceOf' as const,
    args: [address ?? ''],
    queryOptions: {
      enabled: !!address,  // Always enable conditionally
      select: (data) => ethers.formatEther(data[0]),  // Transform in select, not component
      staleTime: 30000,
      retry: (failureCount, error) => !error.message.includes('reverted') && failureCount < 3,
    },
  });
};
```

--------------------------------

### Manage Wallet State with useWallet Hook

Source: https://context7.com/vechain/vechain-kit/llms.txt

The useWallet hook provides access to the current connection state, account information, and smart account details. It allows developers to monitor connection status, retrieve user data from social logins, and trigger disconnection.

```typescript
'use client';

import { useWallet } from '@vechain/vechain-kit';

export function AccountInfo() {
    const {
        account,
        connectedWallet,
        smartAccount,
        privyUser,
        connection,
        disconnect,
    } = useWallet();

    if (connection.isLoading) {
        return <div>Loading...</div>;
    }

    if (!connection.isConnected) {
        return <div>Please connect your wallet</div>;
    }

    return (
        <div>
            <p>Address: {account?.address}</p>
            <p>Domain: {account?.domain || 'No domain set'}</p>
            <p>Connected via: {connection.source.displayName}</p>
            <p>Network: {connection.network}</p>
            <p>Chain ID: {connection.chainId}</p>
            {connection.isConnectedWithSocialLogin && (
                <p>Logged in as: {privyUser?.email?.address}</p>
            )}
            {smartAccount.isActive && (
                <div>
                    <p>Smart Account: {smartAccount.address}</p>
                    <p>Version: {smartAccount.version}</p>
                    <p>Deployed: {smartAccount.isDeployed ? 'Yes' : 'No'}</p>
                </div>
            )}
            <button onClick={disconnect}>Disconnect</button>
        </div>
    );
}
```

--------------------------------

### Implement Type-Safe Contract Calls

Source: https://github.com/vechain/vechain-kit/blob/main/CLAUDE.md

Best practices for interacting with smart contracts using TypeScript. This approach ensures type safety by using contract factories instead of manual ABI definitions.

```typescript
import { VOT3__factory } from '@vechain/vechain-kit/contracts';

const contractAddress = config.contractAddress as `0x${string}`;
const method = 'balanceOf' as const;

const abi = VOT3__factory.abi;
```

--------------------------------

### Build and Send Transactions with useBuildTransaction (TypeScript)

Source: https://github.com/vechain/vechain-kit/blob/main/CLAUDE.md

Illustrates how to construct and send blockchain transactions using the `useBuildTransaction` hook. This hook allows defining transaction clauses dynamically based on parameters and includes a callback (`onTxConfirmed`) for actions to perform after a transaction is confirmed, such as invalidating queries.

```typescript
const { sendTransaction } = useBuildTransaction({
  clauseBuilder: (params) => {
    if (!account?.address) return [];
    return [
      {
        ...thor.contracts.load(tokenAddress, ERC20__factory.abi)
          .clause.approve(spender, amount).clause,
        comment: 'Approve spending',
      },
      {
        ...thor.contracts.load(contractAddress, Contract__factory.abi)
          .clause.execute(params).clause,
        comment: 'Execute action',
      },
    ];
  },
  onTxConfirmed: () => {
    queryClient.invalidateQueries({ queryKey: getTokenBalanceQueryKey(address, networkType) });
  },
});
```

--------------------------------

### Fetch Swap Quotes with useSwapQuotes Hook

Source: https://context7.com/vechain/vechain-kit/llms.txt

The useSwapQuotes hook enables fetching and simulating swap quotes across multiple aggregators. It requires source and destination tokens, the swap amount, and slippage tolerance, returning the best quote and a list of available options.

```typescript
'use client';

import { useSwapQuotes, useTokensWithValues, useWallet } from '@vechain/vechain-kit';
import { useState } from 'react';

export function TokenSwap() {
    const { account } = useWallet();
    const { tokens } = useTokensWithValues(account?.address);
    const [amountIn, setAmountIn] = useState('');

    const vetToken = tokens.find(t => t.symbol === 'VET');
    const vthoToken = tokens.find(t => t.symbol === 'VTHO');

    const {
        bestQuote,
        quotes,
        isLoading,
        error,
        from,
        to,
    } = useSwapQuotes(
        vetToken || null,
        vthoToken || null,
        amountIn,
        account?.address || '',
        1,
        !!amountIn && parseFloat(amountIn) > 0
    );

    return (
        <div>
            <h2>Swap VET to VTHO</h2>
            <input
                type="number"
                placeholder="Amount to swap"
                value={amountIn}
                onChange={(e) => setAmountIn(e.target.value)}
            />
            {isLoading && <p>Fetching quotes...</p>}
            {bestQuote && (
                <div>
                    <h3>Best Quote</h3>
                    <p>Aggregator: {bestQuote.aggregator?.name}</p>
                    <p>Output: {bestQuote.outputAmount?.toString()} VTHO</p>
                    <p>Gas Cost: {bestQuote.gasCostVTHO} VTHO</p>
                </div>
            )}
        </div>
    );
}
```

--------------------------------

### Manage Account Actions with useAccountModal

Source: https://context7.com/vechain/vechain-kit/llms.txt

The useAccountModal hook provides control over the account management interface, allowing users to trigger specific sections like send, receive, or settings. It requires an active wallet connection to function properly.

```typescript
'use client';

import { useAccountModal, useWallet } from '@vechain/vechain-kit';

export function AccountActions() {
    const { connection } = useWallet();
    const { open, close, isOpen } = useAccountModal();

    if (!connection.isConnected) {
        return null;
    }

    return (
        <div>
            <button onClick={() => open()}>
                Open Account
            </button>

            {/* Open to specific section */}
            <button onClick={() => open('send')}>
                Send Tokens
            </button>

            <button onClick={() => open('receive')}>
                Receive
            </button>

            <button onClick={() => open('settings')}>
                Settings
            </button>
        </div>
    );
}
```

--------------------------------

### Automated Translation Workflow

Source: https://github.com/vechain/vechain-kit/blob/main/README.md

Command to trigger automated translation for missing keys in the project's localization files. Requires an OPENAI_API_KEY environment variable.

```bash
cd packages/vechain-kit
yarn translate
```

--------------------------------

### Execute Multiple Contract Calls (TypeScript)

Source: https://github.com/vechain/vechain-kit/blob/main/CLAUDE.md

Shows how to execute multiple contract calls concurrently using `executeMultipleClausesCall`. This is efficient for fetching data from several contracts or methods at once. It takes a `thor` instance and an array of call configurations as input.

```typescript
const results = await executeMultipleClausesCall({
  thor,
  calls: addresses.map((addr) => ({
    abi: ERC20__factory.abi,
    functionName: 'balanceOf',
    address: addr as `0x${string}`,
    args: [userAddress],
  })),
});
```

--------------------------------

### Registering a New Swap Aggregator in TypeScript

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/src/utils/swap/README.md

Illustrates how to add a new swap aggregator to the VeChain Kit by creating a module, implementing the `SwapAggregator` interface, and registering it in `swapAggregators.ts`.

```typescript
import { createMyAggregator } from '@/utils/swap/myAggregator';

export const getSwapAggregators = (networkType: NETWORK_TYPE): SwapAggregator[] => [
    createVeTradeAggregator(networkType),
    createBetterSwapAggregator(networkType),
    createMyAggregator(networkType), // Add here
];
```

--------------------------------

### Fetch Token Balances with useTokenBalances Hook (TypeScript)

Source: https://context7.com/vechain/vechain-kit/llms.txt

A hook designed to retrieve all token balances (including VET, VTHO, B3TR, VOT3, veDelegate, and custom tokens) for a specified VeChainThor address. It requires the address as input and returns the balances along with a loading state. This is useful for displaying a user's token portfolio.

```typescript
'use client';

import { useTokenBalances, useWallet } from '@vechain/vechain-kit';

export function WalletBalances() {
    const { account } = useWallet();
    const { balances, isLoading } = useTokenBalances(account?.address);

    if (isLoading) {
        return <div>Loading balances...</div>;
    }

    return (
        <div>
            <h2>Token Balances</h2>
            <ul>
                {balances.map((token) => (
                    <li key={token.address}>
                        <strong>{token.symbol}:</strong> {token.balance}
                    </li>
                ))}
            </ul>
        </div>
    );
}

// Example output:
// Token Balances
// - VET: 1000.5
// - VTHO: 523.123
// - B3TR: 150.0
// - VOT3: 75.5
// - veDelegate: 0

```

--------------------------------

### Configure VeChain MCP Server

Source: https://github.com/vechain/vechain-kit/blob/main/CLAUDE.md

Configuration for the VeChain MCP server to enable blockchain interactions within the development environment. This JSON structure defines the command and environment variables required for the MCP endpoint.

```json
{
  "mcpServers": {
    "vechain": {
      "command": "npx",
      "args": ["-y", "@vechain/mcp-server@latest"],
      "env": { "VECHAIN_NETWORK": "mainnet" }
    }
  }
}
```

--------------------------------

### Simulate Swap Transactions

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/src/utils/swap/README.md

Simulates a swap transaction to estimate gas costs and verify execution success on the VeChain network. Returns the gas cost in VTHO and a success status.

```typescript
const simulation = await aggregator.simulateSwap(params, quote, thor);
```

--------------------------------

### Resolve VNS Domains with useVechainDomain

Source: https://context7.com/vechain/vechain-kit/llms.txt

The useVechainDomain hook allows developers to resolve VeChain Name Service (VNS) domains to blockchain addresses and vice versa. It provides real-time status updates including loading states, primary domain detection, and validation results.

```typescript
'use client';

import { useVechainDomain } from '@vechain/vechain-kit';
import { useState } from 'react';

export function DomainResolver() {
    const [input, setInput] = useState('');

    const {
        data,
        isLoading,
        error
    } = useVechainDomain(input || null);

    return (
        <div>
            <input
                placeholder="Enter address or domain (e.g., alice.vet)"
                value={input}
                onChange={(e) => setInput(e.target.value)}
            />

            {isLoading && <p>Resolving...</p>}

            {data && (
                <div>
                    <p>Address: {data.address || 'Not found'}</p>
                    <p>Domain: {data.domain || 'No domain'}</p>
                    <p>Is Primary: {data.isPrimaryDomain ? 'Yes' : 'No'}</p>
                    <p>Valid: {data.isValidAddressOrDomain ? 'Yes' : 'No'}</p>
                </div>
            )}

            {error && <p>Error: {error.message}</p>}
        </div>
    );
}
```

--------------------------------

### Control Connect Modal with useConnectModal

Source: https://context7.com/vechain/vechain-kit/llms.txt

The useConnectModal hook allows programmatic control over the wallet connection modal. It provides methods to open, close, and check the status of the modal, supporting specific views like main options or wallet-only views.

```typescript
'use client';

import { useConnectModal, useWallet } from '@vechain/vechain-kit';

export function CustomLoginButton() {
    const { connection } = useWallet();
    const { open, close, isOpen } = useConnectModal();

    if (connection.isConnected) {
        return <p>Already connected!</p>;
    }

    return (
        <div>
            <button onClick={() => open()}>
                Custom Login Button
            </button>

            {/* Open to specific content */}
            <button onClick={() => open('main')}>
                Show Main Options
            </button>

            <button onClick={() => open('dappkit')}>
                Show Wallet Options Only
            </button>
        </div>
    );
}
```

--------------------------------

### Interact with Blockchain via useThor

Source: https://context7.com/vechain/vechain-kit/llms.txt

The useThor hook grants access to the Thor client, enabling direct blockchain queries and interactions. It is commonly used to fetch block data, account information, or perform contract calls.

```typescript
'use client';

import { useThor } from '@vechain/vechain-kit';
import { useEffect, useState } from 'react';

export function BlockchainInfo() {
    const thor = useThor();
    const [blockInfo, setBlockInfo] = useState<any>(null);

    useEffect(() => {
        const fetchBlock = async () => {
            if (!thor) return;

            // Get latest block
            const block = await thor.blocks.getBlockCompressed('best');
            setBlockInfo(block);
        };

        fetchBlock();
    }, [thor]);

    if (!blockInfo) {
        return <div>Loading blockchain info...</div>;
    }

    return (
        <div>
            <h3>Latest Block</h3>
            <p>Number: {blockInfo.number}</p>
            <p>ID: {blockInfo.id}</p>
            <p>Timestamp: {new Date(blockInfo.timestamp * 1000).toLocaleString()}</p>
            <p>Gas Limit: {blockInfo.gasLimit}</p>
            <p>Transactions: {blockInfo.transactions?.length || 0}</p>
        </div>
    );
}
```

--------------------------------

### Sign Messages with useSignMessage

Source: https://context7.com/vechain/vechain-kit/llms.txt

The useSignMessage hook enables users to sign arbitrary messages using their connected wallet. It supports both Privy and DAppKit wallet connections and provides methods to handle the signing process, track pending states, and manage resulting signatures.

```typescript
'use client';

import { useSignMessage, useWallet } from '@vechain/vechain-kit';
import { useState } from 'react';

export function MessageSigner() {
    const { account } = useWallet();
    const [message, setMessage] = useState('');

    const {
        signMessage,
        isSigningPending,
        signature,
        error,
        reset,
    } = useSignMessage();

    const handleSign = async () => {
        try {
            const sig = await signMessage(message);
            console.log('Signature:', sig);
        } catch (err) {
            console.error('Signing failed:', err);
        }
    };

    return (
        <div>
            <textarea
                placeholder="Enter message to sign"
                value={message}
                onChange={(e) => setMessage(e.target.value)}
            />

            <button
                onClick={handleSign}
                disabled={isSigningPending || !message}
            >
                {isSigningPending ? 'Signing...' : 'Sign Message'}
            </button>

            {signature && (
                <div>
                    <p>Signature:</p>
                    <code>{signature}</code>
                    <button onClick={reset}>Clear</button>
                </div>
            )}

            {error && <p>Error: {error.message}</p>}
        </div>
    );
}
```

--------------------------------

### Input Validation for Security (TypeScript)

Source: https://github.com/vechain/vechain-kit/blob/main/CLAUDE.md

Demonstrates essential input validation checks to enhance security. It includes verifying if a recipient address is valid and ensuring that a transaction amount is positive before proceeding. These checks help prevent common vulnerabilities.

```typescript
// Always validate inputs
if (!isAddress(recipient)) throw new Error('Invalid address');
if (BigInt(amount) <= 0n) throw new Error('Amount must be positive');
```

--------------------------------

### Execute Swap Transaction

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/src/utils/swap/README.md

Builds the final transaction clauses using the selected aggregator and sends them to the network for execution.

```typescript
const clauses = await quote.aggregator.buildSwapTransaction(params, quote);
await sendTransaction(clauses);
```

--------------------------------

### Generate Query Key for Invalidation (TypeScript)

Source: https://github.com/vechain/vechain-kit/blob/main/CLAUDE.md

Provides a function to generate a query key for invalidating cached data, specifically for token balance queries. This is useful for ensuring that UI updates correctly after a transaction. It requires the contract ABI, address, method name, and arguments.

```typescript
export const getTokenBalanceQueryKey = (address: string, networkType: NETWORK_TYPE)
  getCallClauseQueryKeyWithArgs({
    abi: VOT3__factory.abi,
    address: getConfig(networkType).contractAddress as `0x${string}`,
    method: 'balanceOf' as const,
    args: [address],
  });
```

--------------------------------

### Fetch Swap Quotes

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/src/utils/swap/README.md

Retrieves a swap quote from a specific aggregator. It requires swap parameters and a THOR client instance to calculate expected output and slippage.

```typescript
const quote = await aggregator.getQuote(params, thor);
```

--------------------------------

### Manage Transactions with TransactionModal

Source: https://context7.com/vechain/vechain-kit/llms.txt

The TransactionModal component provides a standardized UI for tracking transaction states including pending, success, and error. It integrates with the useSendTransaction hook to handle execution and status updates.

```typescript
'use client';

import { TransactionModal, useSendTransaction, useWallet } from '@vechain/vechain-kit';
import { useState } from 'react';

export function TransactionWithModal() {
    const { account } = useWallet();
    const [isModalOpen, setIsModalOpen] = useState(false);

    const { sendTransaction, status, txReceipt, error, resetStatus } = useSendTransaction({
        signerAccountAddress: account?.address,
    });

    const handleSubmit = async () => {
        setIsModalOpen(true);
        const clauses = [{ to: '0xRecipient...', value: '1000000000000000000', data: '0x' }];
        await sendTransaction(clauses);
    };

    return (
        <div>
            <button onClick={handleSubmit}>Send Transaction</button>
            <TransactionModal
                isOpen={isModalOpen}
                onClose={() => { setIsModalOpen(false); resetStatus(); }}
                status={status}
                txReceipt={txReceipt}
                txError={error}
                uiConfig={{ title: 'Sending VET' }}
            />
        </div>
    );
}
```

--------------------------------

### Transfer VET Tokens with useTransferVET Hook (TypeScript)

Source: https://context7.com/vechain/vechain-kit/llms.txt

A specialized hook for transferring VET tokens on the VeChainThor blockchain. It includes built-in validation and transaction handling. Requires @vechain/vechain-kit and React's useState. It takes sender address, receiver address, and amount as inputs, and provides functions to send transactions, track their status, and handle success or error callbacks.

```typescript
'use client';

import { useTransferVET, useWallet } from '@vechain/vechain-kit';
import { useState } from 'react';

export function SendVET() {
    const { account } = useWallet();
    const [recipient, setRecipient] = useState('');
    const [amount, setAmount] = useState('');

    const {
        sendTransaction,
        isTransactionPending,
        status,
        txReceipt,
        error,
        resetStatus,
        clauses, // Pre-built clauses for the transfer
    } = useTransferVET({
        fromAddress: account?.address || '',
        receiverAddress: recipient,
        amount: amount,
        onSuccess: () => {
            alert('Transfer successful!');
            setRecipient('');
            setAmount('');
        },
        onError: (error) => {
            alert(`Transfer failed: ${error}`);
        },
    });

    return (
        <form onSubmit={(e) => { e.preventDefault(); sendTransaction(); }}>
            <input
                placeholder="Recipient address (0x...)"
                value={recipient}
                onChange={(e) => setRecipient(e.target.value)}
            />
            <input
                placeholder="Amount (VET)"
                type="number"
                step="0.01"
                value={amount}
                onChange={(e) => setAmount(e.target.value)}
            />
            <button type="submit" disabled={isTransactionPending}>
                {isTransactionPending ? 'Sending...' : 'Send VET'}
            </button>

            {status === 'success' && txReceipt && (
                <a
                    href={`https://explore.vechain.org/transactions/${txReceipt.meta.txID}`}
                    target="_blank"
                >
                    View on Explorer
                </a>
            )}
        </form>
    );
}

```

--------------------------------

### Execute Transactions with useSendTransaction Hook

Source: https://context7.com/vechain/vechain-kit/llms.txt

The useSendTransaction hook facilitates sending transactions on the VeChainThor blockchain. It supports complex clause execution, gas padding, and provides lifecycle callbacks for transaction confirmation or failure.

```typescript
'use client';

import { useSendTransaction, useWallet } from '@vechain/vechain-kit';
import { Clause, Address, ABIContract } from '@vechain/sdk-core';

export function ContractInteraction() {
    const { account } = useWallet();

    const { sendTransaction, isTransactionPending, isWaitingForWalletConfirmation, txReceipt, status, error } = useSendTransaction({
        signerAccountAddress: account?.address,
        onTxConfirmed: () => console.log('Transaction confirmed!'),
        onTxFailedOrCancelled: (error) => console.error('Transaction failed:', error),
        gasPadding: 0.2
    });

    const handleContractCall = async () => {
        const clauses = [
            { to: '0xRecipientAddress...', value: '1000000000000000000', data: '0x' },
            Clause.callFunction(Address.of('0xContractAddress...'), ABIContract.ofAbi(contractABI).getFunction('myFunction'), [arg1, arg2])
        ];
        await sendTransaction(clauses);
    };

    return (
        <button onClick={handleContractCall} disabled={isTransactionPending}>
            {isWaitingForWalletConfirmation ? 'Waiting...' : isTransactionPending ? 'Processing...' : 'Execute'}
        </button>
    );
}
```

--------------------------------

### TypeScript API Quote Response Interface

Source: https://github.com/vechain/vechain-kit/blob/main/packages/vechain-kit/src/utils/swap/README.md

Defines the TypeScript interface for the API response when requesting a swap quote. It specifies the structure of expected output amounts, transaction clauses, and the token swap path.

```typescript
interface APIQuoteResponse {
    amountOut: string;              // Expected output amount (decimal string)
    amountOutMin: string;            // Minimum output with slippage (decimal string)
    clauses: Array<{ 
        to: string;                 // Contract address to call
        value: string;              // VET value to send (hex or decimal string)
        comment?: string;           // Optional description
        functionCall: {
            functionName?: string;  // Function name (or use 'name')
            name?: string;          // Alternative function name field
            abi: Abi | Array<{      // Function ABI or inputs array
                name: string;
                type: string;
                internalType?: string;
                components?: Array<{...}>; // For struct types
            }>;
            args: unknown[];        // Function arguments
        };
    }>;
    path: string[];                 // Token swap path
}
```