Token-Based AI Chat

What is Token-Based Pricing?

Traditional AI API pricing charges based on tokens - the units of text processed by language models. A token is roughly 4 characters or 0.75 words. For example:

• "Hello, how are you?" ≈ 6 tokens
• A detailed response might use 200-500 tokens

The x402 starter kit demonstrates pay-per-token pricing where you only pay for the actual tokens consumed in each interaction.

The "Upto" Payment Scheme

Unlike the "exact" scheme used in human payment mode (pay exactly $0.01), token-based chat uses the "upto" scheme:

1. Authorize maximum: You sign for up to $0.50 per message
2. Pay actual cost: You're only charged for tokens used (e.g., $0.03)
3. Refund difference: The unused authorization is never spent

This protects you from unexpected costs while enabling variable pricing.

Pricing Details

• Rate: $0.001 per 1,000 tokens
• Maximum: $0.50 per message (500,000 tokens cap)
• Typical cost: $0.01-0.05 for most interactions

Step-by-Step: Using Token-Based Chat

Step 1: Switch to AI Agent Mode

1. Open the starter kit at http://localhost:3000
2. Click the "AI Agent" tab at the top
3. Select "Token-Chat" from the sub-navigation

Step 2: Connect Your Wallet

1. Click "Connect Wallet"
2. Ensure you're on Avalanche Fuji Testnet
3. Verify you have test USDC (get from Circle Faucet if needed)

Step 3: Send a Message

1. Type a message in the chat input (e.g., "What is blockchain?")
2. Click Send or press Enter
3. Your wallet will prompt for a signature

Step 4: Observe Variable Pricing

After signing, watch the response:

• The AI generates a response
• Token count is displayed (input + output tokens)
• Actual cost shows what you paid (e.g., "$0.02")
• This is typically much less than the $0.50 maximum authorized

Step 5: Compare Different Messages

Try sending messages of varying complexity:

• Short question: "What is AVAX?" → Low token cost
• Detailed request: "Explain how smart contracts work with examples" → Higher token cost

Notice how the cost scales with response length.

How It Works

The token-based chat uses OpenRouter to access AI models. The payment flow:

1. Request: Client sends message to /api/ai-chat
2. 402 Response: Server returns payment requirements with "upto" scheme
3. Authorization: User signs for maximum amount ($0.50)
4. Processing: Server calls OpenRouter, counts tokens
5. Settlement: Only actual token cost is settled on-chain
6. Response: AI response delivered to user

The "upto" scheme is defined in the x402 specification for scenarios where the exact cost isn't known until after processing.

Verifying Your Payment

After each chat interaction:

1. Check the Transaction Log in the starter kit UI
2. View the actual amount charged vs. authorized
3. Verify on Thirdweb Dashboard transaction history

You'll see that even though you authorized $0.50, only the actual token cost was transferred.