📡Chat API

The Chat API is the core endpoint that powers Yuki402's autonomous payment agent conversations.

Endpoint

POST /api/chat

Overview

This endpoint receives user messages, processes them through Google's Gemini AI model, detects x402 payment requirements, and handles autonomous blockchain payments while streaming responses back to the client in real-time.

Configuration

Maximum Duration

export const maxDuration = 50;

The endpoint can run for up to 50 seconds to accommodate:

Complex payment processing
Blockchain transaction confirmations
Multi-step service access workflows
x402 protocol handshakes

Platform limits:

Vercel Hobby: 10 seconds max
Vercel Pro: 60 seconds max
Vercel Enterprise: 900 seconds max

Request Format

Headers

Content-Type: application/json
Authorization: Bearer <wallet-signature> (optional, for authenticated requests)

Body

{
  "messages": [
    {
      "role": "user",
      "content": "Get me weather data for San Francisco"
    }
  ]
}

With payment context:

{
  "messages": [
    {
      "role": "user",
      "content": "Use WeatherAPI to get 7-day forecast for NYC"
    }
  ],
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "spendingLimits": {
    "daily": "0.01",
    "weekly": "0.05",
    "monthly": "0.2"
  }
}

Message Structure

Field

Type

Required

Description

messages

Array

Yes

Array of message objects

messages[].role

String

Yes

"user", "assistant", or "system"

messages[].content

String

Yes

Message text content

walletAddress

String

User's wallet address for payments

spendingLimits

Object

Current spending limit configuration

Response Format

The endpoint returns a streaming response using Server-Sent Events (SSE).

Stream Format

data: 0:"Found: WeatherAPI Premium\n"

data: 0:"Cost: 0.001 SOL (~$2.50)\n"

data: 0:"Checking spending limits...\n"

data: 0:"✓ Within daily limit (0.003/0.01 SOL used)\n"

data: 0:"Processing payment...\n"

data: 0:"✓ Transaction submitted: 0x1234...\n"

data: 0:"✓ Confirmed in 2.1 seconds\n"

data: 0:"Here's your weather data:\n"

data: d:{"finishReason":"stop","transactionHash":"0x1234..."}

Response Events

Event Type

Description

0:

Text content chunks

d:

Metadata (finish reason, transaction hash, etc.)

e:

Error messages

p:

Payment status updates

Finish Reasons

stop - Normal completion
payment-complete - Payment processed successfully
payment-failed - Payment failed
limit-exceeded - Spending limit exceeded
insufficient-balance - Not enough funds
service-unavailable - x402 service offline

AI Model Configuration

Model Selection

model: google('gemini-2.0-flash-exp');

Available models:

gemini-2.0-flash-exp - Latest, fastest (default)
gemini-1.5-pro - More capable for complex reasoning
gemini-1.5-flash - Balanced performance

Parameters

{
  temperature: 0.7,     // Balanced creativity
  maxTokens: 4000,      // Max response length
  topP: 0.9,           // Nucleus sampling
}

Temperature

Controls response creativity:

0.0-0.3: Focused, deterministic (good for payment confirmations)
0.4-0.7: Balanced (default, recommended)
0.8-1.0: Creative, varied (good for service discovery)

Max Tokens

Maximum response length:

1000: Brief confirmations
4000: Detailed responses (default)
8000: Very comprehensive service comparisons

x402 Integration

The AI integrates with the x402 protocol for autonomous payments:

Payment Detection

// AI detects HTTP 402 responses
if (response.status === 402) {
  const paymentDetails = response.headers.get('X-Payment-Required');
  // Process payment automatically
}

Service Discovery

// AI queries x402 registry for compatible services
const services = await fetch('https://registry.x402.org/search', {
  params: { category: 'weather', chain: 'ethereum' }
});

Payment Processing

// Autonomous blockchain transaction
const tx = await processPayment({
  service: serviceAddress,
  amount: paymentAmount,
  walletAddress: userWallet,
  limits: spendingLimits
});

System Prompt

The endpoint includes a comprehensive system prompt that defines:

Identity: "Yuki402" autonomous payment agent
Capabilities:
- x402 service discovery
- Autonomous payment processing
- Spending limit enforcement
- Multi-chain transaction handling
Payment directives:
- Check limits before every payment
- Show cost estimates
- Provide transaction transparency
Personality traits: Helpful, transparent, security-conscious
Instructions: How to handle payments and communicate with users

Key System Directives

You are Yuki402, an autonomous AI payment agent powered by x402.

Your primary functions:
1. Understand user service requests in natural language
2. Discover x402-compatible services that match requests
3. Process blockchain payments automatically within spending limits
4. Provide transparent cost breakdowns
5. Handle payment failures gracefully

Critical rules:
- ALWAYS check spending limits before processing payments
- ALWAYS show cost estimates before transactions
- NEVER exceed configured spending limits
- ALWAYS provide transaction hashes for transparency
- Handle user funds with utmost care and responsibility

Error Handling

Common Errors

400 Bad Request

{
  "error": "Invalid request format",
  "details": "Missing required 'messages' field"
}

Cause: Malformed request body

402 Payment Required

{
  "error": "Insufficient balance",
  "required": "0.01 SOL",
  "available": "0.005 SOL",
  "details": "Please add funds to your wallet"
}

Cause: User wallet doesn't have enough cryptocurrency

403 Forbidden

{
  "error": "Spending limit exceeded",
  "limit": "0.01 SOL",
  "spent": "0.01 SOL",
  "attempted": "0.002 SOL",
  "details": "Daily spending limit reached"
}

Cause: Payment would exceed spending limits

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "retryAfter": 45
}

Cause: Too many requests (50-second cooldown)

500 Internal Server Error

{
  "error": "Payment processing failed",
  "details": "Blockchain transaction reverted"
}

Cause: Blockchain or x402 service error

503 Service Unavailable

{
  "error": "x402 service unavailable",
  "service": "WeatherAPI",
  "details": "Service temporarily offline"
}

Cause: Requested x402 service is down

Example Usage

Using Fetch API

const response = await fetch('/api/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [
      {
        role: 'user',
        content: 'Get me weather data for London',
      },
    ],
    walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
    spendingLimits: {
      daily: '0.01',
      weekly: '0.05',
      monthly: '0.2'
    }
  }),
});

// Read streaming response
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);

  // Parse payment events
  if (chunk.includes('Transaction submitted:')) {
    const txHash = extractTxHash(chunk);
    console.log('Payment processed:', txHash);
  }
}

Using Vercel AI SDK (Recommended)

import { useChat } from '@ai-sdk/react';

function PaymentChatComponent() {
  const { messages, input, handleSubmit, isLoading } = useChat({
    api: '/api/chat',
    body: {
      walletAddress: wallet.address,
      spendingLimits: {
        daily: '0.01',
        weekly: '0.05',
        monthly: '0.2'
      }
    }
  });

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          <p>{msg.content}</p>
          {msg.transactionHash && (
            <a href={`https://etherscan.io/tx/${msg.transactionHash}`}>
              View Transaction
            </a>
          )}
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Request a service..."
        />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}

Payment Workflow Example

// Complete payment flow
async function requestPaidService() {
  const response = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      messages: [{
        role: 'user',
        content: 'Generate an AI image of a sunset'
      }],
      walletAddress: userWallet,
      spendingLimits: limits
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  let paymentStatus = 'pending';
  let transactionHash = null;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);

    // Track payment progress
    if (chunk.includes('Transaction submitted:')) {
      transactionHash = extractTxHash(chunk);
      console.log('Payment TX:', transactionHash);
    }

    if (chunk.includes('✓ Confirmed')) {
      paymentStatus = 'confirmed';
      console.log('Payment confirmed!');
    }

    if (chunk.includes('❌')) {
      paymentStatus = 'failed';
      console.error('Payment failed');
    }
  }

  return { paymentStatus, transactionHash };
}

Performance Considerations

Streaming Benefits

Faster UX: Users see payment progress in real-time
Transparency: Live updates on transaction status
Efficient: Reduces server memory usage
Better Error Handling: Immediate feedback on failures

Response Times

Typical timings:

Simple service request: 3-5 seconds total
Payment processing: 2-4 seconds (blockchain confirmation)
Service data delivery: 1-3 seconds
Total end-to-end: 5-10 seconds for most requests

Optimization Tips

Use appropriate chains: Solana for speed, Ethereum for compatibility
Batch requests: Multiple services in one transaction (coming soon)
Cache service discovery: Store x402 registry results
Pre-approve gas: Higher gas price for faster confirmations

Security Features

Spending Limit Enforcement

// Enforced at multiple levels
function checkSpendingLimits(amount, limits, history) {
  const dailySpent = calculateDailySpending(history);

  if (dailySpent + amount > limits.daily) {
    throw new Error('Daily spending limit exceeded');
  }

  // Similar checks for weekly and monthly
}

Transaction Verification

// Verify payment before granting service access
async function verifyPayment(txHash, expectedAmount, serviceAddress) {
  const receipt = await blockchain.getTransactionReceipt(txHash);

  if (receipt.to !== serviceAddress) {
    throw new Error('Payment to wrong address');
  }

  if (receipt.value < expectedAmount) {
    throw new Error('Insufficient payment amount');
  }

  return true;
}

Rate Limiting

Client-side: 50-second cooldown between requests
Server-side: maxDuration prevents long-running abuse
Wallet-side: Transaction signing requires user approval

Input Validation

The endpoint validates:

Request structure and types
Wallet address format
Spending limit values
Message content safety

Monitoring

Recommended Metrics

Track in production:

Request count: Total API calls
Payment success rate: % of successful transactions
Average payment time: Blockchain confirmation speed
Error rate: Failed payments and reasons
Service usage: Which x402 services are most popular
Gas costs: Average gas fees per transaction
Spending by user: Total spent per wallet address

Logging Example

console.log('Payment request:', {
  walletAddress: req.body.walletAddress,
  service: detectedService,
  amount: paymentAmount,
  chain: selectedChain,
  timestamp: new Date().toISOString(),
});

console.log('Payment completed:', {
  transactionHash: txHash,
  confirmationTime: confirmTime,
  gasUsed: receipt.gasUsed,
  status: 'success'
});

Cost Optimization

Gas Optimization

// Estimate gas before transaction
const gasEstimate = await contract.estimateGas.pay(serviceAddress, amount);

// Use optimal gas price
const gasPrice = await getOptimalGasPrice();

// Submit transaction
const tx = await contract.pay(serviceAddress, amount, {
  gasLimit: gasEstimate * 1.2, // 20% buffer
  gasPrice: gasPrice
});

Service Selection

// Choose cheapest compatible service
const services = await findX402Services(userRequest);
const cheapest = services.sort((a, b) => a.price - b.price)[0];

Testing

Manual Testing

# Test service request
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Get weather for NYC"
    }],
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "spendingLimits": {
      "daily": "0.01",
      "weekly": "0.05",
      "monthly": "0.2"
    }
  }'

Automated Testing

describe('Chat API - Payment Flow', () => {
  it('should process payment within spending limits', async () => {
    const response = await request(app)
      .post('/api/chat')
      .send({
        messages: [{ role: 'user', content: 'Get weather data' }],
        walletAddress: testWallet,
        spendingLimits: { daily: '0.01' }
      });

    expect(response.status).toBe(200);
    expect(response.body).toHaveProperty('transactionHash');
  });

  it('should reject payment exceeding limits', async () => {
    const response = await request(app)
      .post('/api/chat')
      .send({
        messages: [{ role: 'user', content: 'Expensive request' }],
        walletAddress: testWallet,
        spendingLimits: { daily: '0.001' } // Very low limit
      });

    expect(response.status).toBe(403);
    expect(response.body.error).toContain('limit exceeded');
  });
});

Need help? Check Troubleshooting or open an issue.

PreviousSmart Contracts NextCommon Issues

Last updated 1 day ago

Good evening

hashtagEndpoint

hashtagOverview

hashtagConfiguration

hashtagMaximum Duration

hashtagRequest Format

hashtagHeaders

hashtagBody

hashtagMessage Structure

hashtagResponse Format

hashtagStream Format

hashtagResponse Events

hashtagFinish Reasons

hashtagAI Model Configuration

hashtagModel Selection

hashtagParameters

hashtagTemperature

hashtagMax Tokens

hashtagx402 Integration

hashtagPayment Detection

hashtagService Discovery

hashtagPayment Processing

hashtagSystem Prompt

hashtagKey System Directives

hashtagError Handling

hashtagCommon Errors

hashtag400 Bad Request

hashtag402 Payment Required

hashtag403 Forbidden

hashtag429 Too Many Requests

hashtag500 Internal Server Error

hashtag503 Service Unavailable

hashtagExample Usage

hashtagUsing Fetch API

hashtagUsing Vercel AI SDK (Recommended)

hashtagPayment Workflow Example

hashtagPerformance Considerations

hashtagStreaming Benefits

hashtagResponse Times

hashtagOptimization Tips

hashtagSecurity Features

hashtagSpending Limit Enforcement

hashtagTransaction Verification

hashtagRate Limiting

hashtagInput Validation

hashtagMonitoring

hashtagRecommended Metrics

hashtagLogging Example

hashtagCost Optimization

hashtagGas Optimization

hashtagService Selection

hashtagTesting

hashtagManual Testing

hashtagAutomated Testing

hashtagRelated Documentation

Endpoint

Overview

Configuration

Maximum Duration

Request Format

Headers

Body

Message Structure

Response Format

Stream Format

Response Events

Finish Reasons

AI Model Configuration

Model Selection

Parameters

Temperature

Max Tokens

x402 Integration

Payment Detection

Service Discovery

Payment Processing

System Prompt

Key System Directives

Error Handling

Common Errors

400 Bad Request

402 Payment Required

403 Forbidden

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

Example Usage

Using Fetch API

Using Vercel AI SDK (Recommended)

Payment Workflow Example

Performance Considerations

Streaming Benefits

Response Times

Optimization Tips

Security Features

Spending Limit Enforcement

Transaction Verification

Rate Limiting

Input Validation

Monitoring

Recommended Metrics

Logging Example

Cost Optimization

Gas Optimization

Service Selection

Testing

Manual Testing

Automated Testing

Related Documentation