Chat API

The Chat API is the core endpoint that powers Mika402'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	No	User's wallet address for payments
spendingLimits	Object	No	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 ETH (~$2.50)\n"

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

data: 0:"✓ Within daily limit (0.003/0.01 ETH 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:

1. Identity: "Mika402" autonomous payment agent

2. Capabilities:

   • x402 service discovery

   • Autonomous payment processing

   • Spending limit enforcement

   • Multi-chain transaction handling

3. Payment directives:

   • Check limits before every payment

   • Show cost estimates

   • Provide transaction transparency

4. Personality traits: Helpful, transparent, security-conscious

5. Instructions: How to handle payments and communicate with users

Key System Directives

You are Mika402, 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 ETH",
  "available": "0.005 ETH",
  "details": "Please add funds to your wallet"
}

Cause: User wallet doesn't have enough cryptocurrency

403 Forbidden

{
  "error": "Spending limit exceeded",
  "limit": "0.01 ETH",
  "spent": "0.01 ETH",
  "attempted": "0.002 ETH",
  "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

1. Use appropriate chains: Solana for speed, Ethereum for compatibility

2. Batch requests: Multiple services in one transaction (coming soon)

3. Cache service discovery: Store x402 registry results

4. 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');
  });
});

Related Documentation

• Autonomous Payments

• Spending Limits

• Making Payments

• Smart Contracts

• x402 Protocol

---

Need help? Check Troubleshooting or open an issue.