Chat API

The Chat API is the core endpoint that powers Miko402's autonomous payment agent. It processes user messages, handles x402 payment flows, and streams responses in real-time.

Endpoint

POST /api/chat

Overview

This endpoint receives user messages, processes them through Google's Gemini AI model, detects x402 payment requirements, executes autonomous blockchain payments within spending limits, and streams responses back to the client.

Configuration

Maximum Duration

export const maxDuration = 50;

The endpoint can run for up to 50 seconds to accommodate complex payment processing, blockchain confirmations, and multi-step x402 workflows.

Vercel platform limits:

• Hobby: 10 seconds

• Pro: 60 seconds

• Enterprise: 900 seconds

Request Format

Headers

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

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 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:"✓ Confirmed in 2.1 seconds\n"
data: d:{"finishReason":"stop","transactionHash":"0x1234..."}

Response Events

Event	Description
0:	Text content chunks
d:	Metadata (finish reason, transaction hash)
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

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

Parameters

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

Temperature guidance:

• 0.0–0.3: Deterministic, factual (payment confirmations)

• 0.4–0.7: Balanced (default)

• 0.8–1.0: Creative, varied (service discovery)

x402 Integration

Payment Detection

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

Service Discovery

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

Payment Processing

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

System Prompt

The system prompt defines Miko's identity and behavior:

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

Primary functions:
1. Understand user service requests in natural language
2. Discover x402-compatible services
3. Process blockchain payments 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

Error Handling

400 Bad Request

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

402 Payment Required

{ "error": "Insufficient balance", "required": "0.01 SOL", "available": "0.005 SOL" }

403 Forbidden

{ "error": "Spending limit exceeded", "limit": "0.01 SOL", "spent": "0.01 SOL" }

429 Too Many Requests

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

500 Internal Server Error

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

503 Service Unavailable

{ "error": "x402 service unavailable", "service": "WeatherAPI" }

Usage Examples

Using Vercel AI SDK (Recommended)

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

function PaymentChat() {
  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://solscan.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>
  );
}

Using Fetch API

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

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);
  // Process streaming chunks
}

Manual Testing

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

Performance

Typical Response Times

Operation	Duration
Service discovery	1–2 seconds
Payment processing	2–4 seconds (blockchain confirmation)
Data delivery	1–3 seconds
Total end-to-end	3–8 seconds

Streaming Benefits

• Users see payment progress in real-time

• Immediate feedback on transaction status

• Reduced server memory usage

• Better error handling with instant feedback

Security Features

Spending Limit Enforcement

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
}

Rate Limiting

• Client-side: 50-second cooldown

• Server-side: maxDuration prevents long-running abuse

• Wallet-side: Transaction signing requires user approval

Input Validation

The endpoint validates request structure, wallet address format, spending limit values, and message content safety.

Automated Testing

describe('Chat API', () => {
  it('should process payment within 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);
  });

  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' }
      });
    expect(response.status).toBe(403);
  });
});

Related Documentation

• Autonomous Payments — Payment flow details

• Spending Limits — Limit configuration

• Making Payments — User guide

• Smart Contracts — On-chain infrastructure

---

Need help? Check Troubleshooting or open an issue.