feat: Claw402 x402 payment provider + Telegram agent + x402 refactoring (#1409)

* feat(telegram): add AI agent bot with streaming and account context - Add Telegram bot with long-polling and AI agent loop (api_call tool) - SSE streaming with real-time message editing and ⏳ placeholder - Account state injection at conversation start (models, exchanges, strategies, traders, per-trader PnL and statistics) - Lane semaphore per chat serializes concurrent messages (60s timeout) - Idle timeout watchdog (60s) prevents hung streaming connections - Look-ahead buffer prevents partial <api_call> tag leaking to user - Fix PUT /strategies/:id to merge config (read-then-merge pattern) - Add route registry with full API schema for LLM documentation - Add TelegramConfig store and Web UI config modal - Add GetAnyEnabled to AIModel store for bot LLM client selection * fix(telegram): eliminate narration, add full-setup workflow and tests - Rewrite NO NARRATION rule: response is EITHER api_call tag alone OR final text reply — no text before api_call under any circumstances - Ban all narration patterns: 现在我将/好的/正在/I will/Let me etc. - Add 'create strategy + create trader + start' full setup workflow - Add 12 automated tests covering: - No narration leaking to user (5 narration variants tested) - api_call tag never leaks to user - Full setup workflow: POST strategy → verify → POST trader → start - Start existing trader workflow - Max iterations safety, tag stripping, parser edge cases * refactor(agent): replace XML api_call with native function calling Migrate the Telegram bot agent from an XML tag hack (<api_call>) to OpenAI-native function calling via CallWithRequestFull. Key changes: - mcp/interface.go: add parseMCPResponseFull to clientHooks interface - mcp/client.go: route callWithRequestFull through hooks for overridability - mcp/claude_client.go: override parseMCPResponseFull for Claude response format (tool_use blocks instead of choices[].message.tool_calls) - telegram/agent/agent.go: rewrite Run() to use CallWithRequestFull; define api_request tool with JSON Schema; implement tool-call loop with role="tool" result messages; remove XML parsing entirely - telegram/agent/apicall.go: remove parseAPICall (dead code) - telegram/agent/prompt.go: simplify — remove XML format instructions, replace with concise api_request tool usage instructions - telegram/agent/agent_test.go: rebuild all tests using LLMResponse objects; add TestNarrationStructurallyImpossible, TestOnChunkCalledWithFinalReply, TestToolCallIDPropagated; remove XML-specific tests Architecture advantage: with native function calling, the LLM returns EITHER ToolCalls OR Content — never both. Narration is now structurally impossible at the protocol level, not just enforced by prompt rules. All 11 agent tests pass. mcp package tests pass. * refactor(mcp): route buildRequestBodyFromRequest through hooks + full Anthropic format Problem: callWithRequest/Full/Stream all called client.buildRequestBodyFromRequest directly (not via hooks), so ClaudeClient could never override it. This meant tool calling sent OpenAI format to Anthropic (wrong field names, wrong roles). Changes: mcp/interface.go - Add buildRequestBodyFromRequest(*Request) map[string]any to clientHooks - Improve comments: document what each hook group does and why mcp/client.go - All three paths (callWithRequest, callWithRequestFull, CallWithRequestStream) now call client.hooks.buildRequestBodyFromRequest — ClaudeClient picks up mcp/claude_client.go - Full rewrite with format comparison table in package doc - buildRequestBodyFromRequest: produces correct Anthropic wire format * system prompt → top-level "system" field * tools: parameters → input_schema, no "type:function" wrapper * tool_choice "auto" → {"type":"auto"} object * assistant tool calls → content[{type:tool_use, id, name, input}] * role=tool results → role=user content[{type:tool_result,...}] * consecutive tool results merged into single user turn - convertMessagesToAnthropic: handles all three message types - parseMCPResponseFull: extracts text + tool_use blocks - parseMCPResponse: delegates to parseMCPResponseFull All mcp and agent tests pass. * fix(telegram): fix claude client dispatch + strategy creation workflow - telegram/bot.go: clientForProvider now returns NewClaudeClient() for 'claude' provider (was incorrectly falling back to DeepSeekClient which uses OpenAI wire format, breaking Anthropic API calls) - api/server.go: fix scan_interval_minutes schema default (3, not 60); POST /api/strategies now clearly states config is OPTIONAL with complete working defaults; POST /api/traders removes redundant GET workflow note - telegram/agent/prompt.go: simplify strategy creation — just POST {name} without config (backend applies full working defaults automatically); only include config when user requests custom settings * test(mcp): add ClaudeClient wire format tests Tests cover all Anthropic-specific format conversions: - system prompt lifted to top-level field - tools use input_schema (not parameters) - tool_choice is object {type:auto} not string - assistant tool calls → content[{type:tool_use}] - consecutive tool results merged into single user turn - parseMCPResponseFull: text, tool_use, and error cases - x-api-key header (not Authorization: Bearer) - /messages endpoint URL * fix(telegram): clientForProvider returns correct client for all 7 providers Previously qwen/kimi/grok/gemini all fell back to DeepSeekClient. Each provider now gets its own dedicated client with correct default base URL and model. All 7 providers now fully supported: openai, deepseek, claude, qwen, kimi, grok, gemini * fix(telegram): newLLMClient uses bound user's model, not any user's model GetAnyEnabled() searched across all users in DB — if user B has an enabled model, bot could use their API key while acting as user A. Now uses GetDefault(botUserID) which only looks up the bound user's enabled model, matching the same user scope as all API calls. * fix(auth): single-user deployment by default, no open registration Registration logic redesigned: - Empty DB (first-time setup): registration always open, no config needed - After first user exists: registration closed by default - Multi-user opt-in: set REGISTRATION_ENABLED=true + MAX_USERS=N in .env Config defaults changed: - RegistrationEnabled: true → false (closed after first user) - MaxUsers: 10 → 1 (single-user deployment default) This eliminates the confusion of multiple users appearing in a personal deployment where Telegram is bound to a single admin account. * feat(solo): beginner-friendly onboarding — smart setup guide + direct config commands start.sh: - Interactive Telegram Bot Token prompt on first run - Token format validation (must match 12345:ABC... pattern) - Friendly step-by-step startup instructions after launch telegram/bot.go: - /start now shows context-aware setup guide based on actual config state: - No AI model → explains how to configure, lists all providers - AI model OK but no exchange → guides to configure exchange via chat - All configured → full capabilities welcome message - New: direct setup commands ('配置 deepseek sk-xxx') bypass LLM entirely so AI model can be configured even before any model exists (bootstrap fix) - All messages now in Chinese (匹配用户语言) telegram/agent/prompt.go: - Added first-time setup detection section - Agent told to never ask user to visit web UI — everything via chat * feat(i18n): bilingual EN/ZH setup guide with language selection store/telegram_config.go: - Add Language field to TelegramConfig (persisted in DB) - Add SetLanguage(lang) and GetLanguage() methods - Default language: English (en) telegram/bot.go: - First /start triggers language selection (1=English, 2=中文) - /lang command to change language at any time - awaitingLang state machine handles language choice before any other input - buildSetupGuide() now fully bilingual (EN/ZH), context-aware: Step 1: configure AI model (no model yet) Step 2: configure exchange (model OK, no exchange) Ready: show full capabilities - tryHandleSetupCommand() bilingual: 'configure/配置 <provider> <key>' - helpMessage(lang) fully bilingual - All error/status messages bilingual Default: English. isLangDefault() detects whether user has explicitly chosen a language vs falling back to the 'en' default. * fix(telegram): use Markdown rendering + simplify language selection condition - sendMarkdownMsg() helper: sends with ParseMode=Markdown, falls back to plain text - All formatted messages (langSelectionMsg, buildSetupGuide, helpMessage) now render bold text and code blocks correctly in Telegram - Simplify /start language check: isLangDefault(st) alone is sufficient (lang == 'en' && isLangDefault was redundant — GetLanguage returns 'en' when empty) * fix(start.sh): translate all user-facing text to English Entire script was in Chinese. Now English-first throughout: - startup banner, prompts, success/error messages - setup_telegram(): English instructions and validation messages - start(): English next-steps after launch - stop/restart/clean/update/regenerate-keys/show_help: all English * fix(telegram): remove 'default' user fallback — resolve user dynamically - botUserID no longer captured once at startup (was 'default' if no user yet) - resolveBotUser() reads first registered user from DB on demand: * called on every /start (handles: registered after bot launch) * called before every AI message (handles mid-session registration) - If no user registered: clear English error 'No account found. Please register on the web UI first' - start.sh: fix set_env_var appending without newline (token was concatenated to prev line) * refactor(telegram): clean onboarding — web UI for setup, Telegram for operations - /start shows clean status: 'setup required → open web UI' or 'ready → examples' - Removed tryHandleSetupCommand (no more CLI-style 'configure deepseek sk-xxx') - Removed automatic language selection on /start (use /lang anytime instead) - newLLMClient returns nil when no model → clear guard, not fallback - statusMsg() replaces buildSetupGuide(): two states only (missing config / ready) - Bot is now purely an operations interface; config lives in the web UI * refactor: single-user web-based setup — replace env config with Settings UI Move from multi-user env-var config to single-user web-first architecture: - Add SetupPage for first-time initialization (replaces /register) - Add SettingsPage for AI models, exchanges, Telegram, and password management - Enrich all API route schemas with exact ID usage documentation - Add PUT /user/password endpoint for in-app password changes - Remove REGISTRATION_ENABLED, MAX_USERS, TELEGRAM_BOT_TOKEN from env config - Simplify LoginPage design, remove admin mode and registration links - Telegram bot now resolves user email for identity display - start.sh no longer runs interactive Telegram setup * feat: add blockRun (x402 USDC) support to all AI model consumers - telegram/bot.go: add blockrun-base, blockrun-sol, minimax to clientForProvider; fix newLLMClient to prefer TelegramConfig.ModelID over GetDefault; log USDC payment provider usage - debate/engine.go: add blockrun-base, blockrun-sol to InitializeClients - api/strategy.go: add blockrun-base, blockrun-sol to runRealAITest - backtest/ai_client.go: add blockrun-base, blockrun-sol to configureMCPClient * feat: add Claw402 (claw402.ai) x402 USDC payment provider Add Claw402Client for claw402.ai's x402 micropayment gateway (Base USDC). Supports 15+ AI models (GPT-5.4, Claude Opus, DeepSeek, Qwen, Grok, etc.) with per-model endpoint routing. - mcp/claw402.go: new client with model→endpoint mapping, x402 v2 payment flow - mcp/blockrun_base.go: extract shared signX402Payment() for reuse - Register "claw402" provider in all 6 consumer switch statements: api/server.go, api/strategy.go, trader/auto_trader.go, telegram/bot.go, debate/engine.go, backtest/ai_client.go * feat: redesign Claw402 model config UI — friendly wallet setup, USDC guide, official logo, nginx no-cache for index.html * refactor: centralize x402 payment flow into shared mcp/x402.go Extract duplicated doRequestWithPayment/call/CallWithRequestFull/buildRequest/ setAuthHeader (~165 lines x3) into shared helpers in mcp/x402.go. Consolidate shared types (x402v2PaymentRequired, x402AcceptOption, x402Resource) and remove duplicate Solana types. Fix validAfter to 0 (official SDK standard), drain 402 body before retry, log Payment-Response tx hash, check Payment-Required before X-Payment-Required. * fix: stop PR template bot from overwriting user-written descriptions The pr-template-suggester workflow was triggered on opened/edited/synchronize events and forcefully replaced the PR body with a template when body < 100 chars. This caused user-written descriptions to be overwritten. Replace with a lightweight labeler (OpenClaw-style) that: - Only adds labels (backend/frontend/docs, size: XS/S/M/L/XL) - Never modifies the PR body - Simplified unified PR template at .github/pull_request_template.md * chore: simplify PR template (OpenClaw-style)
2026-07-15 08:46:58 +08:00 · 2026-03-11 16:01:42 +08:00
parent 6f77ed2fcb
commit 9c5c976d9a
53 changed files with 7572 additions and 1093 deletions
--- a/mcp/blockrun_base.go
+++ b/mcp/blockrun_base.go
@@ -1,14 +1,12 @@
 package mcp

 import (
-	"bytes"
 	"crypto/ecdsa"
 	"crypto/rand"
 	"encoding/base64"
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
-	"io"
 	"math/big"
 	"net/http"
 	"strings"
@@ -97,120 +95,24 @@ func (c *BlockRunBaseClient) SetAPIKey(apiKey string, customURL string, customMo
 	}
 }

-func (c *BlockRunBaseClient) setAuthHeader(reqHeaders http.Header) {
-	// No Bearer token — payment is via x402 signing
-}
+func (c *BlockRunBaseClient) setAuthHeader(h http.Header) { x402SetAuthHeader(h) }

-// call overrides the base call to handle HTTP 402 x402 v2 payment flow.
 func (c *BlockRunBaseClient) call(systemPrompt, userPrompt string) (string, error) {
-	c.logger.Infof("📡 [BlockRun Base] Request AI Server: %s", c.BaseURL)
-
-	requestBody := c.hooks.buildMCPRequestBody(systemPrompt, userPrompt)
-	jsonData, err := c.hooks.marshalRequestBody(requestBody)
-	if err != nil {
-		return "", err
-	}
-
-	url := c.hooks.buildUrl()
-	req, err := c.hooks.buildRequest(url, jsonData)
-	if err != nil {
-		return "", fmt.Errorf("failed to create request: %w", err)
-	}
-
-	resp, err := c.httpClient.Do(req)
-	if err != nil {
-		return "", fmt.Errorf("failed to send request: %w", err)
-	}
-	defer resp.Body.Close()
-
-	// Handle x402 v2 Payment Required
-	if resp.StatusCode == http.StatusPaymentRequired {
-		paymentHeader := resp.Header.Get("X-Payment-Required")
-		if paymentHeader == "" {
-			return "", fmt.Errorf("received 402 but no X-Payment-Required header")
-		}
-
-		paymentSig, err := c.signPayment(paymentHeader)
-		if err != nil {
-			return "", fmt.Errorf("failed to sign x402 payment: %w", err)
-		}
-
-		req2, err := c.hooks.buildRequest(url, jsonData)
-		if err != nil {
-			return "", fmt.Errorf("failed to build retry request: %w", err)
-		}
-		req2.Header.Set("X-Payment", paymentSig)
-
-		resp2, err := c.httpClient.Do(req2)
-		if err != nil {
-			return "", fmt.Errorf("failed to send payment retry: %w", err)
-		}
-		defer resp2.Body.Close()
-
-		body2, err := io.ReadAll(resp2.Body)
-		if err != nil {
-			return "", fmt.Errorf("failed to read payment retry response: %w", err)
-		}
-		if resp2.StatusCode != http.StatusOK {
-			return "", fmt.Errorf("BlockRun payment retry failed (status %d): %s", resp2.StatusCode, string(body2))
-		}
-		return c.hooks.parseMCPResponse(body2)
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", fmt.Errorf("failed to read response: %w", err)
-	}
-	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("BlockRun API error (status %d): %s", resp.StatusCode, string(body))
-	}
-	return c.hooks.parseMCPResponse(body)
+	return x402Call(c.Client, c.signPayment, "BlockRun Base", systemPrompt, userPrompt)
 }

-// x402v2PaymentRequired is the structure of the X-Payment-Required header (x402 v2).
-type x402v2PaymentRequired struct {
-	X402Version int `json:"x402Version"`
-	Accepts     []struct {
-		Scheme            string            `json:"scheme"`
-		Network           string            `json:"network"`
-		Amount            string            `json:"amount"`
-		Asset             string            `json:"asset"`
-		PayTo             string            `json:"payTo"`
-		MaxTimeoutSeconds int               `json:"maxTimeoutSeconds"`
-		Extra             map[string]string `json:"extra"`
-	} `json:"accepts"`
-	Resource *struct {
-		URL         string `json:"url"`
-		Description string `json:"description"`
-		MimeType    string `json:"mimeType"`
-	} `json:"resource"`
+func (c *BlockRunBaseClient) CallWithRequestFull(req *Request) (*LLMResponse, error) {
+	return x402CallFull(c.Client, c.signPayment, "BlockRun Base", req)
 }

-// signPayment parses the X-Payment-Required header (x402 v2) and returns a signed X-Payment value.
+// signPayment parses the Payment-Required header (x402 v2) and returns a signed payment value.
 func (c *BlockRunBaseClient) signPayment(paymentHeaderB64 string) (string, error) {
-	if c.privateKey == nil {
-		return "", fmt.Errorf("no private key set for BlockRun Base wallet")
-	}
+	return signBasePaymentHeader(c.privateKey, paymentHeaderB64, "BlockRun Base")
+}

-	// Decode base64 → JSON
-	decoded, err := base64.RawStdEncoding.DecodeString(paymentHeaderB64)
-	if err != nil {
-		decoded, err = base64.StdEncoding.DecodeString(paymentHeaderB64)
-		if err != nil {
-			return "", fmt.Errorf("failed to base64-decode payment header: %w", err)
-		}
-	}
-
-	var req x402v2PaymentRequired
-	if err := json.Unmarshal(decoded, &req); err != nil {
-		return "", fmt.Errorf("failed to parse x402 v2 payment header: %w", err)
-	}
-
-	if len(req.Accepts) == 0 {
-		return "", fmt.Errorf("no payment options in x402 response")
-	}
-
-	opt := req.Accepts[0]
+// signX402Payment is the shared EIP-712 signing logic for x402 v2 on Base USDC.
+// Used by both BlockRunBaseClient and Claw402Client.
+func signX402Payment(privateKey *ecdsa.PrivateKey, senderAddr string, opt x402AcceptOption, resource *x402Resource) (string, error) {
 	recipient := opt.PayTo
 	amount := opt.Amount
 	network := opt.Network
@@ -224,28 +126,22 @@ func (c *BlockRunBaseClient) signPayment(paymentHeaderB64 string) (string, error
 	resourceURL := ""
 	resourceDesc := ""
 	resourceMime := "application/json"
-	if req.Resource != nil {
-		resourceURL = req.Resource.URL
-		resourceDesc = req.Resource.Description
-		resourceMime = req.Resource.MimeType
+	if resource != nil {
+		resourceURL = resource.URL
+		resourceDesc = resource.Description
+		resourceMime = resource.MimeType
 	}

-	// Timestamps: validAfter = now-600 (clock skew), validBefore = now+maxTimeout
 	now := time.Now().Unix()
-	validAfter := now - 600
+	validAfter := int64(0)
 	validBefore := now + int64(maxTimeout)

-	// Random nonce (bytes32)
 	nonceBytes := make([]byte, 32)
 	if _, err := rand.Read(nonceBytes); err != nil {
 		return "", fmt.Errorf("failed to generate nonce: %w", err)
 	}
 	nonce := "0x" + hex.EncodeToString(nonceBytes)

-	// Sender address
-	senderAddr := crypto.PubkeyToAddress(c.privateKey.PublicKey).Hex()
-
-	// Build EIP-712 domain separator
 	domainName := "USD Coin"
 	domainVersion := "2"
 	if extra != nil {
@@ -262,7 +158,6 @@ func (c *BlockRunBaseClient) signPayment(paymentHeaderB64 string) (string, error
 		return "", fmt.Errorf("failed to build domain separator: %w", err)
 	}

-	// Build struct hash
 	amountBig, err := parseBigInt(amount)
 	if err != nil {
 		return "", fmt.Errorf("invalid amount: %w", err)
@@ -273,26 +168,22 @@ func (c *BlockRunBaseClient) signPayment(paymentHeaderB64 string) (string, error
 		return "", fmt.Errorf("failed to build struct hash: %w", err)
 	}

-	// EIP-712 digest
 	digest := make([]byte, 0, 66)
 	digest = append(digest, 0x19, 0x01)
 	digest = append(digest, domainSeparator...)
 	digest = append(digest, structHash...)
 	hash := keccak256Bytes(digest)

-	// Sign with secp256k1
-	sig, err := crypto.Sign(hash, c.privateKey)
+	sig, err := crypto.Sign(hash, privateKey)
 	if err != nil {
 		return "", fmt.Errorf("failed to sign: %w", err)
 	}
-	// Adjust V: go-ethereum returns 0/1, EIP-712 expects 27/28
 	if sig[64] < 27 {
 		sig[64] += 27
 	}

 	sigHex := "0x" + hex.EncodeToString(sig)

-	// Build x402 v2 payment payload
 	paymentData := map[string]interface{}{
 		"x402Version": 2,
 		"resource": map[string]string{
@@ -419,10 +310,14 @@ func hexToBytes32(s string) ([]byte, error) {
 }

 func parseBigInt(s string) (*big.Int, error) {
-	s = strings.TrimPrefix(s, "0x")
 	n := new(big.Int)
-	if _, ok := n.SetString(s, 16); ok {
-		return n, nil
+	// Only treat as hex when explicitly prefixed with 0x/0X.
+	// x402 amounts are always decimal strings (e.g. "3000" = 0.003 USDC).
+	if strings.HasPrefix(s, "0x") || strings.HasPrefix(s, "0X") {
+		if _, ok := n.SetString(s[2:], 16); ok {
+			return n, nil
+		}
+		return nil, fmt.Errorf("cannot parse hex big.Int from %q", s)
 	}
 	if _, ok := n.SetString(s, 10); ok {
 		return n, nil
@@ -445,12 +340,6 @@ func (c *BlockRunBaseClient) buildUrl() string {
 	return DefaultBlockRunBaseURL + BlockRunChatEndpoint
 }

-// buildRequest creates the HTTP request without an Authorization header.
 func (c *BlockRunBaseClient) buildRequest(url string, jsonData []byte) (*http.Request, error) {
-	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
-	if err != nil {
-		return nil, fmt.Errorf("fail to build request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-	return req, nil
+	return x402BuildRequest(url, jsonData)
 }
--- a/mcp/blockrun_sol.go
+++ b/mcp/blockrun_sol.go
@@ -1,12 +1,10 @@
 package mcp

 import (
-	"bytes"
 	"context"
 	"encoding/base64"
 	"encoding/json"
 	"fmt"
-	"io"
 	"net/http"
 	"strings"

@@ -76,120 +74,34 @@ func (c *BlockRunSolClient) SetAPIKey(apiKey string, customURL string, customMod
 	}
 }

-func (c *BlockRunSolClient) setAuthHeader(reqHeaders http.Header) {
-	// No Bearer token — payment is via x402 signing
-}
+func (c *BlockRunSolClient) setAuthHeader(h http.Header) { x402SetAuthHeader(h) }

-// call overrides the base call to handle HTTP 402 x402 v2 Solana payment flow.
 func (c *BlockRunSolClient) call(systemPrompt, userPrompt string) (string, error) {
-	c.logger.Infof("📡 [BlockRun Sol] Request AI Server: %s", c.BaseURL)
-
-	requestBody := c.hooks.buildMCPRequestBody(systemPrompt, userPrompt)
-	jsonData, err := c.hooks.marshalRequestBody(requestBody)
-	if err != nil {
-		return "", err
-	}
-
-	url := c.hooks.buildUrl()
-	req, err := c.hooks.buildRequest(url, jsonData)
-	if err != nil {
-		return "", fmt.Errorf("failed to create request: %w", err)
-	}
-
-	resp, err := c.httpClient.Do(req)
-	if err != nil {
-		return "", fmt.Errorf("failed to send request: %w", err)
-	}
-	defer resp.Body.Close()
-
-	// Handle x402 v2 Payment Required
-	if resp.StatusCode == http.StatusPaymentRequired {
-		paymentHeader := resp.Header.Get("X-Payment-Required")
-		if paymentHeader == "" {
-			return "", fmt.Errorf("received 402 but no X-Payment-Required header")
-		}
-
-		paymentSig, err := c.signSolanaPayment(paymentHeader)
-		if err != nil {
-			return "", fmt.Errorf("failed to sign Solana x402 payment: %w", err)
-		}
-
-		req2, err := c.hooks.buildRequest(url, jsonData)
-		if err != nil {
-			return "", fmt.Errorf("failed to build retry request: %w", err)
-		}
-		req2.Header.Set("X-Payment", paymentSig)
-
-		resp2, err := c.httpClient.Do(req2)
-		if err != nil {
-			return "", fmt.Errorf("failed to send payment retry: %w", err)
-		}
-		defer resp2.Body.Close()
-
-		body2, err := io.ReadAll(resp2.Body)
-		if err != nil {
-			return "", fmt.Errorf("failed to read payment retry response: %w", err)
-		}
-		if resp2.StatusCode != http.StatusOK {
-			return "", fmt.Errorf("BlockRun Sol payment retry failed (status %d): %s", resp2.StatusCode, string(body2))
-		}
-		return c.hooks.parseMCPResponse(body2)
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", fmt.Errorf("failed to read response: %w", err)
-	}
-	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("BlockRun Sol API error (status %d): %s", resp.StatusCode, string(body))
-	}
-	return c.hooks.parseMCPResponse(body)
+	return x402Call(c.Client, c.signSolanaPayment, "BlockRun Sol", systemPrompt, userPrompt)
 }

-// solanaPaymentOption is an entry in the accepts[] array of the x402 v2 response.
-type solanaPaymentOption struct {
-	Scheme            string            `json:"scheme"`
-	Network           string            `json:"network"`
-	Amount            string            `json:"amount"`
-	Asset             string            `json:"asset"`
-	PayTo             string            `json:"payTo"`
-	MaxTimeoutSeconds int               `json:"maxTimeoutSeconds"`
-	Extra             map[string]string `json:"extra"`
+func (c *BlockRunSolClient) CallWithRequestFull(req *Request) (*LLMResponse, error) {
+	return x402CallFull(c.Client, c.signSolanaPayment, "BlockRun Sol", req)
 }

-// x402v2SolanaRequired is the parsed X-Payment-Required header for Solana.
-type x402v2SolanaRequired struct {
-	X402Version int                   `json:"x402Version"`
-	Accepts     []solanaPaymentOption `json:"accepts"`
-	Resource    *struct {
-		URL         string `json:"url"`
-		Description string `json:"description"`
-		MimeType    string `json:"mimeType"`
-	} `json:"resource"`
-}
-
-// signSolanaPayment parses the X-Payment-Required header and builds a signed x402 v2 Solana payload.
+// signSolanaPayment parses the Payment-Required header and builds a signed x402 v2 Solana payload.
 func (c *BlockRunSolClient) signSolanaPayment(paymentHeaderB64 string) (string, error) {
 	if c.keypair == nil {
 		return "", fmt.Errorf("no private key set for BlockRun Sol wallet")
 	}

-	// Decode base64 → JSON
-	decoded, err := base64.RawStdEncoding.DecodeString(paymentHeaderB64)
+	decoded, err := x402DecodeHeader(paymentHeaderB64)
 	if err != nil {
-		decoded, err = base64.StdEncoding.DecodeString(paymentHeaderB64)
-		if err != nil {
-			return "", fmt.Errorf("failed to base64-decode payment header: %w", err)
-		}
+		return "", err
 	}

-	var req x402v2SolanaRequired
+	var req x402v2PaymentRequired
 	if err := json.Unmarshal(decoded, &req); err != nil {
 		return "", fmt.Errorf("failed to parse x402 v2 Solana header: %w", err)
 	}

 	// Find the Solana option
-	var opt *solanaPaymentOption
+	var opt *x402AcceptOption
 	for i := range req.Accepts {
 		if strings.HasPrefix(req.Accepts[i].Network, "solana:") {
 			opt = &req.Accepts[i]
@@ -360,12 +272,6 @@ func (c *BlockRunSolClient) buildUrl() string {
 	return DefaultBlockRunSolURL + BlockRunChatEndpoint
 }

-// buildRequest creates the HTTP request without an Authorization header.
 func (c *BlockRunSolClient) buildRequest(url string, jsonData []byte) (*http.Request, error) {
-	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
-	if err != nil {
-		return nil, fmt.Errorf("fail to build request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-	return req, nil
+	return x402BuildRequest(url, jsonData)
 }
--- a/mcp/claude_client.go
+++ b/mcp/claude_client.go
@@ -1,3 +1,19 @@
+// Package mcp — ClaudeClient implements the Anthropic Messages API.
+//
+// Wire-format differences from the OpenAI-compatible base Client:
+//
+//	┌─────────────────────┬───────────────────────────┬─────────────────────────────────┐
+//	│ Concept             │ OpenAI format              │ Anthropic format                │
+//	├─────────────────────┼───────────────────────────┼─────────────────────────────────┤
+//	│ Endpoint            │ /v1/chat/completions       │ /v1/messages                    │
+//	│ Auth header         │ Authorization: Bearer xxx  │ x-api-key: xxx                  │
+//	│ System prompt       │ messages[0] role=system    │ top-level "system" field        │
+//	│ Tool definition     │ type=function + parameters │ name + description + input_schema│
+//	│ Tool choice         │ "auto" (string)            │ {"type":"auto"} (object)        │
+//	│ Assistant tool call │ tool_calls array           │ content[{type:tool_use,...}]    │
+//	│ Tool result         │ role=tool + tool_call_id   │ role=user content[tool_result]  │
+//	│ Max tokens          │ max_tokens                 │ max_tokens (same)               │
+//	└─────────────────────┴───────────────────────────┴─────────────────────────────────┘
 package mcp

 import (
@@ -12,75 +28,64 @@ const (
 	DefaultClaudeModel   = "claude-opus-4-6"
 )

+// ClaudeClient wraps the base Client and overrides the methods that differ
+// for the Anthropic Messages API.  All other behaviour (retry, timeout,
+// logging) is inherited unchanged.
 type ClaudeClient struct {
 	*Client
 }

-// NewClaudeClient creates Claude client (backward compatible)
+// NewClaudeClient creates a ClaudeClient with default settings.
 func NewClaudeClient() AIClient {
 	return NewClaudeClientWithOptions()
 }

-// NewClaudeClientWithOptions creates Claude client (supports options pattern)
+// NewClaudeClientWithOptions creates a ClaudeClient with optional overrides.
 func NewClaudeClientWithOptions(opts ...ClientOption) AIClient {
-	// 1. Create Claude preset options
-	claudeOpts := []ClientOption{
+	baseClient := NewClient(append([]ClientOption{
 		WithProvider(ProviderClaude),
 		WithModel(DefaultClaudeModel),
 		WithBaseURL(DefaultClaudeBaseURL),
-	}
+	}, opts...)...).(*Client)

-	// 2. Merge user options (user options have higher priority)
-	allOpts := append(claudeOpts, opts...)
-
-	// 3. Create base client
-	baseClient := NewClient(allOpts...).(*Client)
-
-	// 4. Create Claude client
-	claudeClient := &ClaudeClient{
-		Client: baseClient,
-	}
-
-	// 5. Set hooks to point to ClaudeClient (implement dynamic dispatch)
-	baseClient.hooks = claudeClient
-
-	return claudeClient
+	c := &ClaudeClient{Client: baseClient}
+	baseClient.hooks = c // wire dynamic dispatch to ClaudeClient
+	return c
 }

-func (c *ClaudeClient) SetAPIKey(apiKey string, customURL string, customModel string) {
-	c.APIKey = apiKey
+// ── Hook overrides ────────────────────────────────────────────────────────────

+// SetAPIKey stores credentials and optional custom endpoint / model.
+func (c *ClaudeClient) SetAPIKey(apiKey, customURL, customModel string) {
+	c.APIKey = apiKey
 	if len(apiKey) > 8 {
 		c.logger.Infof("🔧 [MCP] Claude API Key: %s...%s", apiKey[:4], apiKey[len(apiKey)-4:])
 	}
 	if customURL != "" {
 		c.BaseURL = customURL
-		c.logger.Infof("🔧 [MCP] Claude using custom BaseURL: %s", customURL)
-	} else {
-		c.logger.Infof("🔧 [MCP] Claude using default BaseURL: %s", c.BaseURL)
+		c.logger.Infof("🔧 [MCP] Claude BaseURL: %s", customURL)
 	}
 	if customModel != "" {
 		c.Model = customModel
-		c.logger.Infof("🔧 [MCP] Claude using custom Model: %s", customModel)
-	} else {
-		c.logger.Infof("🔧 [MCP] Claude using default Model: %s", c.Model)
+		c.logger.Infof("🔧 [MCP] Claude Model: %s", customModel)
 	}
 }

-// setAuthHeader Claude uses x-api-key header instead of Authorization Bearer
-func (c *ClaudeClient) setAuthHeader(reqHeaders http.Header) {
-	reqHeaders.Set("x-api-key", c.APIKey)
-	reqHeaders.Set("anthropic-version", "2023-06-01")
+// setAuthHeader uses x-api-key instead of Authorization: Bearer.
+func (c *ClaudeClient) setAuthHeader(h http.Header) {
+	h.Set("x-api-key", c.APIKey)
+	h.Set("anthropic-version", "2023-06-01")
 }

-// buildUrl Claude uses /messages endpoint
+// buildUrl targets /messages instead of /chat/completions.
 func (c *ClaudeClient) buildUrl() string {
 	return fmt.Sprintf("%s/messages", c.BaseURL)
 }

-// buildMCPRequestBody Claude has different request format
+// buildMCPRequestBody builds the Anthropic wire format for the simple
+// CallWithMessages path (no tool support).
 func (c *ClaudeClient) buildMCPRequestBody(systemPrompt, userPrompt string) map[string]any {
-	requestBody := map[string]any{
+	return map[string]any{
 		"model":      c.Model,
 		"max_tokens": c.MaxTokens,
 		"system":     systemPrompt,
@@ -88,16 +93,175 @@ func (c *ClaudeClient) buildMCPRequestBody(systemPrompt, userPrompt string) map[
 			{"role": "user", "content": userPrompt},
 		},
 	}
-
-	return requestBody
 }

-// parseMCPResponse Claude has different response format
+// buildRequestBodyFromRequest converts a *Request into the Anthropic Messages
+// API wire format.  This is the key override that makes tool calling work
+// correctly with Claude.
+//
+// Conversions applied:
+//
+//   - System messages are lifted to the top-level "system" field.
+//   - Tool definitions: parameters → input_schema, wrapper removed.
+//   - Assistant messages with ToolCalls → content[{type:tool_use,...}].
+//   - Tool result messages (role=tool) → role=user with tool_result blocks.
+//     Consecutive tool results are merged into a single user turn (Anthropic
+//     requires strictly alternating user/assistant turns).
+//   - tool_choice "auto"/"any" → {"type":"auto"/"any"} object.
+func (c *ClaudeClient) buildRequestBodyFromRequest(req *Request) map[string]any {
+	// ── 1. Separate system prompt from conversation messages ──────────────────
+	var systemPrompt string
+	var convMsgs []Message
+	for _, m := range req.Messages {
+		if m.Role == "system" {
+			systemPrompt = m.Content
+		} else {
+			convMsgs = append(convMsgs, m)
+		}
+	}
+
+	// ── 2. Convert messages to Anthropic format ───────────────────────────────
+	anthropicMsgs := convertMessagesToAnthropic(convMsgs)
+
+	// ── 3. Convert tool definitions (parameters → input_schema) ──────────────
+	var anthropicTools []map[string]any
+	for _, t := range req.Tools {
+		anthropicTools = append(anthropicTools, map[string]any{
+			"name":         t.Function.Name,
+			"description":  t.Function.Description,
+			"input_schema": t.Function.Parameters,
+		})
+	}
+
+	// ── 4. Assemble request body ──────────────────────────────────────────────
+	body := map[string]any{
+		"model":      req.Model,
+		"max_tokens": c.MaxTokens,
+		"system":     systemPrompt,
+		"messages":   anthropicMsgs,
+	}
+
+	if len(anthropicTools) > 0 {
+		body["tools"] = anthropicTools
+	}
+
+	// tool_choice: Anthropic uses an object, not a string.
+	switch req.ToolChoice {
+	case "auto":
+		body["tool_choice"] = map[string]any{"type": "auto"}
+	case "any":
+		body["tool_choice"] = map[string]any{"type": "any"}
+	case "none", "":
+		// omit — no tool_choice sent
+	}
+
+	if req.Temperature != nil {
+		body["temperature"] = *req.Temperature
+	}
+
+	return body
+}
+
+// convertMessagesToAnthropic translates from the OpenAI-shaped mcp.Message
+// slice to Anthropic's messages array.
+//
+// Rules:
+//  1. role=assistant + ToolCalls → role=assistant, content=[tool_use, ...]
+//  2. role=tool (result)         → role=user, content=[tool_result, ...]
+//     Consecutive tool-result messages are merged into one user turn so the
+//     conversation always alternates user/assistant.
+//  3. All other messages         → {role, content} as-is.
+func convertMessagesToAnthropic(msgs []Message) []map[string]any {
+	var out []map[string]any
+
+	for i := 0; i < len(msgs); {
+		msg := msgs[i]
+
+		switch {
+		// ── Assistant message carrying tool calls ─────────────────────────────
+		case msg.Role == "assistant" && len(msg.ToolCalls) > 0:
+			var blocks []map[string]any
+			for _, tc := range msg.ToolCalls {
+				// Arguments are a JSON string; Claude wants a parsed object.
+				var input map[string]any
+				if err := json.Unmarshal([]byte(tc.Function.Arguments), &input); err != nil {
+					input = map[string]any{"_raw": tc.Function.Arguments}
+				}
+				blocks = append(blocks, map[string]any{
+					"type":  "tool_use",
+					"id":    tc.ID,
+					"name":  tc.Function.Name,
+					"input": input,
+				})
+			}
+			out = append(out, map[string]any{
+				"role":    "assistant",
+				"content": blocks,
+			})
+			i++
+
+		// ── Tool result message(s) → single user turn ─────────────────────────
+		case msg.Role == "tool":
+			// Collect all consecutive tool-result messages.
+			var blocks []map[string]any
+			for i < len(msgs) && msgs[i].Role == "tool" {
+				blocks = append(blocks, map[string]any{
+					"type":        "tool_result",
+					"tool_use_id": msgs[i].ToolCallID,
+					"content":     msgs[i].Content,
+				})
+				i++
+			}
+			out = append(out, map[string]any{
+				"role":    "user",
+				"content": blocks,
+			})
+
+		// ── Regular user / assistant text message ─────────────────────────────
+		default:
+			out = append(out, map[string]any{
+				"role":    msg.Role,
+				"content": msg.Content,
+			})
+			i++
+		}
+	}
+
+	return out
+}
+
+// ── Response parsers ──────────────────────────────────────────────────────────
+
+// parseMCPResponse extracts the plain-text reply from an Anthropic response.
+// Used by CallWithMessages / CallWithRequest (no tool support).
 func (c *ClaudeClient) parseMCPResponse(body []byte) (string, error) {
-	var response struct {
+	r, err := c.parseMCPResponseFull(body)
+	if err != nil {
+		return "", err
+	}
+	return r.Content, nil
+}
+
+// parseMCPResponseFull extracts both text and tool calls from an Anthropic
+// response envelope.
+//
+// Anthropic response shape:
+//
+//	{
+//	  "content": [
+//	    {"type": "text",     "text": "..."},
+//	    {"type": "tool_use", "id": "...", "name": "...", "input": {...}}
+//	  ],
+//	  "stop_reason": "tool_use" | "end_turn"
+//	}
+func (c *ClaudeClient) parseMCPResponseFull(body []byte) (*LLMResponse, error) {
+	var raw struct {
 		Content []struct {
-			Type string `json:"type"`
-			Text string `json:"text"`
+			Type  string          `json:"type"`
+			Text  string          `json:"text,omitempty"`
+			ID    string          `json:"id,omitempty"`
+			Name  string          `json:"name,omitempty"`
+			Input json.RawMessage `json:"input,omitempty"`
 		} `json:"content"`
 		Usage struct {
 			InputTokens  int `json:"input_tokens"`
@@ -109,36 +273,46 @@ func (c *ClaudeClient) parseMCPResponse(body []byte) (string, error) {
 		} `json:"error"`
 	}

-	if err := json.Unmarshal(body, &response); err != nil {
-		return "", fmt.Errorf("failed to parse Claude response: %w, body: %s", err, string(body))
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return nil, fmt.Errorf("failed to parse Anthropic response: %w — body: %s", err, body)
+	}
+	if raw.Error != nil {
+		return nil, fmt.Errorf("Anthropic API error: %s — %s", raw.Error.Type, raw.Error.Message)
 	}

-	if response.Error != nil {
-		return "", fmt.Errorf("Claude API error: %s - %s", response.Error.Type, response.Error.Message)
-	}
-
-	if len(response.Content) == 0 {
-		return "", fmt.Errorf("Claude returned empty content, body: %s", string(body))
-	}
-
-	// Report token usage if callback is set
-	totalTokens := response.Usage.InputTokens + response.Usage.OutputTokens
-	if TokenUsageCallback != nil && totalTokens > 0 {
+	total := raw.Usage.InputTokens + raw.Usage.OutputTokens
+	if TokenUsageCallback != nil && total > 0 {
 		TokenUsageCallback(TokenUsage{
 			Provider:         c.Provider,
 			Model:            c.Model,
-			PromptTokens:     response.Usage.InputTokens,
-			CompletionTokens: response.Usage.OutputTokens,
-			TotalTokens:      totalTokens,
+			PromptTokens:     raw.Usage.InputTokens,
+			CompletionTokens: raw.Usage.OutputTokens,
+			TotalTokens:      total,
 		})
 	}

-	// Find text content
-	for _, content := range response.Content {
-		if content.Type == "text" {
-			return content.Text, nil
+	result := &LLMResponse{}
+	for _, block := range raw.Content {
+		switch block.Type {
+		case "text":
+			result.Content = block.Text
+
+		case "tool_use":
+			// Input is a JSON object; serialise back to a JSON string so it
+			// matches the ToolCallFunction.Arguments field (always a string).
+			argsJSON, err := json.Marshal(block.Input)
+			if err != nil {
+				argsJSON = []byte("{}")
+			}
+			result.ToolCalls = append(result.ToolCalls, ToolCall{
+				ID:   block.ID,
+				Type: "function",
+				Function: ToolCallFunction{
+					Name:      block.Name,
+					Arguments: string(argsJSON),
+				},
+			})
 		}
 	}
-
-	return "", fmt.Errorf("no text content in Claude response")
+	return result, nil
 }
--- a/mcp/claude_client_test.go
+++ b/mcp/claude_client_test.go
@@ -0,0 +1,248 @@
+package mcp
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+)
+
+// ── buildRequestBodyFromRequest ────────────────────────────────────────────────
+
+func TestClaudeClient_BuildRequestBody_SystemPromptLifted(t *testing.T) {
+	c := newTestClaudeClient()
+	req := &Request{
+		Model: "claude-opus-4-6",
+		Messages: []Message{
+			{Role: "system", Content: "You are helpful."},
+			{Role: "user", Content: "Hello"},
+		},
+	}
+	body := c.buildRequestBodyFromRequest(req)
+
+	if body["system"] != "You are helpful." {
+		t.Errorf("system not lifted to top level: %v", body["system"])
+	}
+	msgs := body["messages"].([]map[string]any)
+	if len(msgs) != 1 || msgs[0]["role"] != "user" {
+		t.Errorf("system message should be removed from messages array: %v", msgs)
+	}
+}
+
+func TestClaudeClient_BuildRequestBody_ToolsUseInputSchema(t *testing.T) {
+	c := newTestClaudeClient()
+	req := &Request{
+		Model:   "claude-opus-4-6",
+		Messages: []Message{{Role: "user", Content: "hi"}},
+		Tools: []Tool{{
+			Type: "function",
+			Function: FunctionDef{
+				Name:        "my_tool",
+				Description: "does stuff",
+				Parameters:  map[string]any{"type": "object"},
+			},
+		}},
+	}
+	body := c.buildRequestBodyFromRequest(req)
+
+	tools, ok := body["tools"].([]map[string]any)
+	if !ok || len(tools) != 1 {
+		t.Fatalf("tools not set correctly: %v", body["tools"])
+	}
+	tool := tools[0]
+	if tool["name"] != "my_tool" {
+		t.Errorf("tool name wrong: %v", tool["name"])
+	}
+	if tool["input_schema"] == nil {
+		t.Error("tool must use input_schema, not parameters")
+	}
+	if _, hasParams := tool["parameters"]; hasParams {
+		t.Error("tool must NOT have parameters key (Anthropic uses input_schema)")
+	}
+}
+
+func TestClaudeClient_BuildRequestBody_ToolChoiceObject(t *testing.T) {
+	c := newTestClaudeClient()
+	req := &Request{
+		Model:      "claude-opus-4-6",
+		Messages:   []Message{{Role: "user", Content: "hi"}},
+		ToolChoice: "auto",
+	}
+	body := c.buildRequestBodyFromRequest(req)
+
+	tc, ok := body["tool_choice"].(map[string]any)
+	if !ok {
+		t.Fatalf("tool_choice must be an object, got: %T %v", body["tool_choice"], body["tool_choice"])
+	}
+	if tc["type"] != "auto" {
+		t.Errorf("tool_choice.type must be 'auto', got: %v", tc["type"])
+	}
+}
+
+// ── convertMessagesToAnthropic ─────────────────────────────────────────────────
+
+func TestConvertMessages_AssistantToolCall(t *testing.T) {
+	msgs := []Message{
+		{
+			Role: "assistant",
+			ToolCalls: []ToolCall{{
+				ID:   "tc1",
+				Type: "function",
+				Function: ToolCallFunction{Name: "api_request", Arguments: `{"method":"GET","path":"/api/x","body":{}}`},
+			}},
+		},
+	}
+	out := convertMessagesToAnthropic(msgs)
+
+	if len(out) != 1 {
+		t.Fatalf("expected 1 message, got %d", len(out))
+	}
+	msg := out[0]
+	if msg["role"] != "assistant" {
+		t.Errorf("role should be assistant: %v", msg["role"])
+	}
+	blocks := msg["content"].([]map[string]any)
+	if len(blocks) != 1 || blocks[0]["type"] != "tool_use" {
+		t.Errorf("content should be tool_use block: %v", blocks)
+	}
+	if blocks[0]["id"] != "tc1" {
+		t.Errorf("tool_use id wrong: %v", blocks[0]["id"])
+	}
+	// Input must be parsed JSON object, not a string.
+	input, ok := blocks[0]["input"].(map[string]any)
+	if !ok {
+		t.Errorf("tool_use input must be map, got %T", blocks[0]["input"])
+	}
+	if input["method"] != "GET" {
+		t.Errorf("input.method wrong: %v", input)
+	}
+}
+
+func TestConvertMessages_ToolResultMergedIntoUserTurn(t *testing.T) {
+	// Anthropic requires strictly alternating turns; consecutive tool results
+	// must be merged into a single user message.
+	msgs := []Message{
+		{Role: "tool", ToolCallID: "tc1", Content: `{"result":"a"}`},
+		{Role: "tool", ToolCallID: "tc2", Content: `{"result":"b"}`},
+	}
+	out := convertMessagesToAnthropic(msgs)
+
+	if len(out) != 1 {
+		t.Fatalf("consecutive tool results must be merged into one user turn, got %d messages", len(out))
+	}
+	if out[0]["role"] != "user" {
+		t.Errorf("tool results must become role=user: %v", out[0]["role"])
+	}
+	blocks := out[0]["content"].([]map[string]any)
+	if len(blocks) != 2 {
+		t.Errorf("expected 2 tool_result blocks, got %d", len(blocks))
+	}
+	if blocks[0]["type"] != "tool_result" || blocks[1]["type"] != "tool_result" {
+		t.Errorf("blocks should be tool_result: %v", blocks)
+	}
+	if blocks[0]["tool_use_id"] != "tc1" || blocks[1]["tool_use_id"] != "tc2" {
+		t.Errorf("tool_use_id mismatch: %v", blocks)
+	}
+}
+
+// ── parseMCPResponseFull ───────────────────────────────────────────────────────
+
+func TestClaudeClient_ParseResponse_TextOnly(t *testing.T) {
+	c := newTestClaudeClient()
+	body := []byte(`{
+		"content": [{"type":"text","text":"Hello from Claude"}],
+		"usage": {"input_tokens": 10, "output_tokens": 5}
+	}`)
+	resp, err := c.parseMCPResponseFull(body)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp.Content != "Hello from Claude" {
+		t.Errorf("content mismatch: %q", resp.Content)
+	}
+	if len(resp.ToolCalls) != 0 {
+		t.Errorf("expected no tool calls: %v", resp.ToolCalls)
+	}
+}
+
+func TestClaudeClient_ParseResponse_ToolUse(t *testing.T) {
+	c := newTestClaudeClient()
+	body := []byte(`{
+		"content": [{
+			"type": "tool_use",
+			"id": "toolu_01abc",
+			"name": "api_request",
+			"input": {"method":"POST","path":"/api/strategies","body":{"name":"BTC策略"}}
+		}],
+		"usage": {"input_tokens": 100, "output_tokens": 30}
+	}`)
+	resp, err := c.parseMCPResponseFull(body)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(resp.ToolCalls) != 1 {
+		t.Fatalf("expected 1 tool call, got %d", len(resp.ToolCalls))
+	}
+	tc := resp.ToolCalls[0]
+	if tc.ID != "toolu_01abc" {
+		t.Errorf("tool call ID wrong: %v", tc.ID)
+	}
+	if tc.Function.Name != "api_request" {
+		t.Errorf("function name wrong: %v", tc.Function.Name)
+	}
+	// Arguments must be a valid JSON string.
+	var args map[string]any
+	if err := json.Unmarshal([]byte(tc.Function.Arguments), &args); err != nil {
+		t.Errorf("arguments not valid JSON: %q — %v", tc.Function.Arguments, err)
+	}
+	if args["method"] != "POST" {
+		t.Errorf("args.method wrong: %v", args)
+	}
+}
+
+func TestClaudeClient_ParseResponse_APIError(t *testing.T) {
+	c := newTestClaudeClient()
+	body := []byte(`{"error":{"type":"authentication_error","message":"invalid x-api-key"}}`)
+	_, err := c.parseMCPResponseFull(body)
+	if err == nil {
+		t.Fatal("expected error for API error response")
+	}
+	if err.Error() == "" {
+		t.Error("error message should not be empty")
+	}
+}
+
+// ── Auth header ────────────────────────────────────────────────────────────────
+
+func TestClaudeClient_SetAuthHeader(t *testing.T) {
+	c := newTestClaudeClient()
+	c.APIKey = "sk-ant-test123"
+
+	// net/http.Header canonicalizes keys (x-api-key → X-Api-Key).
+	h := make(http.Header)
+	c.setAuthHeader(h)
+
+	if got := h.Get("x-api-key"); got != "sk-ant-test123" {
+		t.Errorf("x-api-key header not set correctly: %q", got)
+	}
+	if h.Get("anthropic-version") == "" {
+		t.Error("anthropic-version header must be set")
+	}
+	// Must NOT use Authorization: Bearer (that's OpenAI format).
+	if h.Get("Authorization") != "" {
+		t.Error("Claude must use x-api-key, not Authorization header")
+	}
+}
+
+func TestClaudeClient_BuildUrl(t *testing.T) {
+	c := newTestClaudeClient()
+	url := c.buildUrl()
+	if url != DefaultClaudeBaseURL+"/messages" {
+		t.Errorf("URL should be /messages endpoint, got: %s", url)
+	}
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────────
+
+func newTestClaudeClient() *ClaudeClient {
+	return NewClaudeClientWithOptions().(*ClaudeClient)
+}
--- a/mcp/claw402.go
+++ b/mcp/claw402.go
@@ -0,0 +1,166 @@
+package mcp
+
+import (
+	"crypto/ecdsa"
+	"net/http"
+	"strings"
+
+	"github.com/ethereum/go-ethereum/crypto"
+)
+
+const (
+	ProviderClaw402    = "claw402"
+	DefaultClaw402URL  = "https://claw402.ai"
+	DefaultClaw402Model = "deepseek"
+)
+
+// claw402ModelEndpoints maps user-friendly model names to claw402 API paths.
+var claw402ModelEndpoints = map[string]string{
+	// OpenAI
+	"gpt-5.4":     "/api/v1/ai/openai/chat/5.4",
+	"gpt-5.4-pro": "/api/v1/ai/openai/chat/5.4-pro",
+	"gpt-5.3":     "/api/v1/ai/openai/chat/5.3",
+	"gpt-5-mini":  "/api/v1/ai/openai/chat/5-mini",
+	// Anthropic
+	"claude-opus": "/api/v1/ai/anthropic/messages/opus",
+	// DeepSeek
+	"deepseek":          "/api/v1/ai/deepseek/chat",
+	"deepseek-reasoner": "/api/v1/ai/deepseek/chat/reasoner",
+	// Qwen
+	"qwen-max":   "/api/v1/ai/qwen/chat/max",
+	"qwen-plus":  "/api/v1/ai/qwen/chat/plus",
+	"qwen-turbo": "/api/v1/ai/qwen/chat/turbo",
+	"qwen-flash": "/api/v1/ai/qwen/chat/flash",
+	// Grok
+	"grok-4.1": "/api/v1/ai/grok/chat/4.1",
+	// Gemini
+	"gemini-3.1-pro": "/api/v1/ai/gemini/chat/3.1-pro",
+	// Kimi
+	"kimi-k2.5": "/api/v1/ai/kimi/chat/k2.5",
+}
+
+// Claw402Client implements AIClient using claw402.ai's x402 v2 USDC payment gateway.
+// Reuses the same EIP-712 signing as BlockRunBaseClient (same Base chain + USDC contract).
+// When the selected model routes to an Anthropic endpoint, it automatically uses
+// the Anthropic wire format for requests and responses (via an internal ClaudeClient).
+type Claw402Client struct {
+	*Client
+	privateKey  *ecdsa.PrivateKey
+	claudeProxy *ClaudeClient // non-nil when endpoint is /anthropic/
+}
+
+// NewClaw402Client creates a claw402 client (backward compatible).
+func NewClaw402Client() AIClient {
+	return NewClaw402ClientWithOptions()
+}
+
+// NewClaw402ClientWithOptions creates a claw402 client with options.
+func NewClaw402ClientWithOptions(opts ...ClientOption) AIClient {
+	baseOpts := []ClientOption{
+		WithProvider(ProviderClaw402),
+		WithModel(DefaultClaw402Model),
+		WithBaseURL(DefaultClaw402URL),
+	}
+	allOpts := append(baseOpts, opts...)
+	baseClient := NewClient(allOpts...).(*Client)
+	baseClient.UseFullURL = true
+	baseClient.BaseURL = DefaultClaw402URL + claw402ModelEndpoints[DefaultClaw402Model]
+
+	c := &Claw402Client{Client: baseClient}
+	baseClient.hooks = c
+	return c
+}
+
+// SetAPIKey stores the EVM private key and selects the model endpoint.
+func (c *Claw402Client) SetAPIKey(apiKey string, _ string, customModel string) {
+	hexKey := strings.TrimPrefix(apiKey, "0x")
+	privKey, err := crypto.HexToECDSA(hexKey)
+	if err != nil {
+		c.logger.Warnf("⚠️  [MCP] Claw402: invalid private key: %v", err)
+	} else {
+		c.privateKey = privKey
+		c.APIKey = apiKey
+		addr := crypto.PubkeyToAddress(privKey.PublicKey).Hex()
+		c.logger.Infof("🔧 [MCP] Claw402 wallet: %s", addr)
+	}
+	if customModel != "" {
+		c.Model = customModel
+	}
+	endpoint := c.resolveEndpoint()
+	c.BaseURL = DefaultClaw402URL + endpoint
+
+	// Anthropic endpoints need different wire format (Messages API)
+	if strings.Contains(endpoint, "/anthropic/") {
+		c.claudeProxy = &ClaudeClient{Client: c.Client}
+		c.logger.Infof("🔧 [MCP] Claw402 model: %s → %s (Anthropic format)", c.Model, endpoint)
+	} else {
+		c.claudeProxy = nil
+		c.logger.Infof("🔧 [MCP] Claw402 model: %s → %s", c.Model, endpoint)
+	}
+}
+
+// resolveEndpoint returns the API path for the configured model.
+func (c *Claw402Client) resolveEndpoint() string {
+	if ep, ok := claw402ModelEndpoints[c.Model]; ok {
+		return ep
+	}
+	// Allow raw path override (e.g. "/api/v1/ai/openai/chat/5.4")
+	if strings.HasPrefix(c.Model, "/api/") {
+		return c.Model
+	}
+	return claw402ModelEndpoints[DefaultClaw402Model]
+}
+
+func (c *Claw402Client) setAuthHeader(h http.Header) { x402SetAuthHeader(h) }
+
+func (c *Claw402Client) call(systemPrompt, userPrompt string) (string, error) {
+	return x402Call(c.Client, c.signPayment, "Claw402", systemPrompt, userPrompt)
+}
+
+func (c *Claw402Client) CallWithRequestFull(req *Request) (*LLMResponse, error) {
+	return x402CallFull(c.Client, c.signPayment, "Claw402", req)
+}
+
+// signPayment signs x402 v2 EIP-712 payment (same Base chain + USDC as BlockRunBase).
+func (c *Claw402Client) signPayment(paymentHeaderB64 string) (string, error) {
+	return signBasePaymentHeader(c.privateKey, paymentHeaderB64, "Claw402")
+}
+
+// ── Format overrides for Anthropic endpoints ─────────────────────────────────
+
+func (c *Claw402Client) buildMCPRequestBody(systemPrompt, userPrompt string) map[string]any {
+	if c.claudeProxy != nil {
+		return c.claudeProxy.buildMCPRequestBody(systemPrompt, userPrompt)
+	}
+	return c.Client.buildMCPRequestBody(systemPrompt, userPrompt)
+}
+
+func (c *Claw402Client) buildRequestBodyFromRequest(req *Request) map[string]any {
+	if c.claudeProxy != nil {
+		return c.claudeProxy.buildRequestBodyFromRequest(req)
+	}
+	return c.Client.buildRequestBodyFromRequest(req)
+}
+
+func (c *Claw402Client) parseMCPResponse(body []byte) (string, error) {
+	if c.claudeProxy != nil {
+		return c.claudeProxy.parseMCPResponse(body)
+	}
+	return c.Client.parseMCPResponse(body)
+}
+
+func (c *Claw402Client) parseMCPResponseFull(body []byte) (*LLMResponse, error) {
+	if c.claudeProxy != nil {
+		return c.claudeProxy.parseMCPResponseFull(body)
+	}
+	return c.Client.parseMCPResponseFull(body)
+}
+
+// buildUrl returns the full claw402 endpoint URL.
+func (c *Claw402Client) buildUrl() string {
+	return c.BaseURL
+}
+
+func (c *Claw402Client) buildRequest(url string, jsonData []byte) (*http.Request, error) {
+	return x402BuildRequest(url, jsonData)
+}
--- a/mcp/client.go
+++ b/mcp/client.go
@@ -1,7 +1,9 @@
 package mcp

 import (
+	"bufio"
 	"bytes"
+	"context"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -232,10 +234,21 @@ func (client *Client) marshalRequestBody(requestBody map[string]any) ([]byte, er
 }

 func (client *Client) parseMCPResponse(body []byte) (string, error) {
+	r, err := client.parseMCPResponseFull(body)
+	if err != nil {
+		return "", err
+	}
+	return r.Content, nil
+}
+
+// parseMCPResponseFull parses the OpenAI-format response body and returns both
+// the text content and any tool calls.
+func (client *Client) parseMCPResponseFull(body []byte) (*LLMResponse, error) {
 	var result struct {
 		Choices []struct {
 			Message struct {
-				Content string `json:"content"`
+				Content   string     `json:"content"`
+				ToolCalls []ToolCall `json:"tool_calls"`
 			} `json:"message"`
 		} `json:"choices"`
 		Usage struct {
@@ -246,11 +259,11 @@ func (client *Client) parseMCPResponse(body []byte) (string, error) {
 	}

 	if err := json.Unmarshal(body, &result); err != nil {
-		return "", fmt.Errorf("failed to parse response: %w", err)
+		return nil, fmt.Errorf("failed to parse response: %w", err)
 	}

 	if len(result.Choices) == 0 {
-		return "", fmt.Errorf("API returned empty response")
+		return nil, fmt.Errorf("API returned empty response")
 	}

 	// Report token usage if callback is set
@@ -264,7 +277,11 @@ func (client *Client) parseMCPResponse(body []byte) (string, error) {
 		})
 	}

-	return result.Choices[0].Message.Content, nil
+	msg := result.Choices[0].Message
+	return &LLMResponse{
+		Content:   msg.Content,
+		ToolCalls: msg.ToolCalls,
+	}, nil
 }

 func (client *Client) buildUrl() string {
@@ -425,50 +442,106 @@ func (client *Client) CallWithRequest(req *Request) (string, error) {
 	return "", fmt.Errorf("still failed after %d retries: %w", maxRetries, lastErr)
 }

+// CallWithRequestFull calls the AI API and returns both text content and tool calls.
+func (client *Client) CallWithRequestFull(req *Request) (*LLMResponse, error) {
+	if client.APIKey == "" {
+		return nil, fmt.Errorf("AI API key not set, please call SetAPIKey first")
+	}
+	if req.Model == "" {
+		req.Model = client.Model
+	}
+
+	var lastErr error
+	maxRetries := client.config.MaxRetries
+	for attempt := 1; attempt <= maxRetries; attempt++ {
+		if attempt > 1 {
+			client.logger.Warnf("⚠️  AI API call failed, retrying (%d/%d)...", attempt, maxRetries)
+		}
+		result, err := client.callWithRequestFull(req)
+		if err == nil {
+			return result, nil
+		}
+		lastErr = err
+		if !client.hooks.isRetryableError(err) {
+			return nil, err
+		}
+		if attempt < maxRetries {
+			waitTime := client.config.RetryWaitBase * time.Duration(attempt)
+			time.Sleep(waitTime)
+		}
+	}
+	return nil, fmt.Errorf("still failed after %d retries: %w", maxRetries, lastErr)
+}
+
+// callWithRequestFull single call that returns LLMResponse (content + tool calls).
+func (client *Client) callWithRequestFull(req *Request) (*LLMResponse, error) {
+	client.logger.Infof("📡 [%s] Request AI Server (full): BaseURL: %s", client.String(), client.BaseURL)
+
+	requestBody := client.hooks.buildRequestBodyFromRequest(req)
+	jsonData, err := client.hooks.marshalRequestBody(requestBody)
+	if err != nil {
+		return nil, err
+	}
+
+	url := client.hooks.buildUrl()
+	httpReq, err := client.hooks.buildRequest(url, jsonData)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	resp, err := client.httpClient.Do(httpReq)
+	if err != nil {
+		return nil, fmt.Errorf("failed to send request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("API returned error (status %d): %s", resp.StatusCode, string(body))
+	}
+
+	return client.hooks.parseMCPResponseFull(body)
+}
+
 // callWithRequest single AI API call (using Request object)
 func (client *Client) callWithRequest(req *Request) (string, error) {
 	// Print current AI configuration
 	client.logger.Infof("📡 [%s] Request AI Server with Builder: BaseURL: %s", client.String(), client.BaseURL)
 	client.logger.Debugf("[%s] Messages count: %d", client.String(), len(req.Messages))

-	// Build request body (from Request object)
-	requestBody := client.buildRequestBodyFromRequest(req)
+	requestBody := client.hooks.buildRequestBodyFromRequest(req)

-	// Serialize request body
 	jsonData, err := client.hooks.marshalRequestBody(requestBody)
 	if err != nil {
 		return "", err
 	}

-	// Build URL
 	url := client.hooks.buildUrl()
 	client.logger.Infof("📡 [MCP %s] Request URL: %s", client.String(), url)

-	// Create HTTP request
 	httpReq, err := client.hooks.buildRequest(url, jsonData)
 	if err != nil {
 		return "", fmt.Errorf("failed to create request: %w", err)
 	}

-	// Send HTTP request
 	resp, err := client.httpClient.Do(httpReq)
 	if err != nil {
 		return "", fmt.Errorf("failed to send request: %w", err)
 	}
 	defer resp.Body.Close()

-	// Read response body
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
 		return "", fmt.Errorf("failed to read response: %w", err)
 	}

-	// Check HTTP status code
 	if resp.StatusCode != http.StatusOK {
 		return "", fmt.Errorf("API returned error (status %d): %s", resp.StatusCode, string(body))
 	}

-	// Parse response
 	result, err := client.hooks.parseMCPResponse(body)
 	if err != nil {
 		return "", fmt.Errorf("fail to parse AI server response: %w", err)
@@ -479,13 +552,23 @@ func (client *Client) callWithRequest(req *Request) (string, error) {

 // buildRequestBodyFromRequest builds request body from Request object
 func (client *Client) buildRequestBodyFromRequest(req *Request) map[string]any {
-	// Convert Message to API format
-	messages := make([]map[string]string, 0, len(req.Messages))
+	// Convert Message to API format — must use map[string]any to support
+	// tool-call messages (tool_calls, tool_call_id fields).
+	messages := make([]map[string]any, 0, len(req.Messages))
 	for _, msg := range req.Messages {
-		messages = append(messages, map[string]string{
-			"role":    msg.Role,
-			"content": msg.Content,
-		})
+		m := map[string]any{"role": msg.Role}
+		if len(msg.ToolCalls) > 0 {
+			// Assistant message that contains tool invocations.
+			// content must be null/omitted for OpenAI compatibility.
+			m["tool_calls"] = msg.ToolCalls
+		} else if msg.ToolCallID != "" {
+			// Tool result message (role="tool").
+			m["tool_call_id"] = msg.ToolCallID
+			m["content"] = msg.Content
+		} else {
+			m["content"] = msg.Content
+		}
+		messages = append(messages, m)
 	}

 	// Build basic request body
@@ -544,3 +627,124 @@ func (client *Client) buildRequestBodyFromRequest(req *Request) map[string]any {

 	return requestBody
 }
+
+// CallWithRequestStream streams the LLM response via SSE (Server-Sent Events).
+// onChunk is called with the full accumulated text so far after each received chunk.
+// Returns the complete final text when the stream ends.
+//
+// Idle timeout: if no chunk arrives for 30 seconds the stream is cancelled automatically.
+// This prevents the scanner from blocking indefinitely on a hung or stalled connection.
+func (client *Client) CallWithRequestStream(req *Request, onChunk func(string)) (string, error) {
+	if client.APIKey == "" {
+		return "", fmt.Errorf("AI API key not set")
+	}
+	if req.Model == "" {
+		req.Model = client.Model
+	}
+	req.Stream = true
+
+	requestBody := client.hooks.buildRequestBodyFromRequest(req)
+	jsonData, err := client.hooks.marshalRequestBody(requestBody)
+	if err != nil {
+		return "", err
+	}
+
+	url := client.hooks.buildUrl()
+	httpReq, err := client.hooks.buildRequest(url, jsonData)
+	if err != nil {
+		return "", err
+	}
+
+	// Idle-timeout watchdog: cancel the request if no SSE line arrives for 30 seconds.
+	// This breaks the scanner out of an indefinitely blocking Read on a hung connection.
+	const idleTimeout = 60 * time.Second
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	resetCh := make(chan struct{}, 1)
+	go func() {
+		t := time.NewTimer(idleTimeout)
+		defer t.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-t.C:
+				cancel() // idle timeout: kill the connection
+				return
+			case <-resetCh:
+				// received a line — reset the idle timer
+				if !t.Stop() {
+					select {
+					case <-t.C:
+					default:
+					}
+				}
+				t.Reset(idleTimeout)
+			}
+		}
+	}()
+
+	httpReq = httpReq.WithContext(ctx)
+	resp, err := client.httpClient.Do(httpReq)
+	if err != nil {
+		return "", fmt.Errorf("streaming request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return "", fmt.Errorf("API error (status %d): %s", resp.StatusCode, string(body))
+	}
+
+	var accumulated strings.Builder
+	scanner := bufio.NewScanner(resp.Body)
+
+	for scanner.Scan() {
+		// Ping the watchdog: we received a line, reset the idle timer.
+		select {
+		case resetCh <- struct{}{}:
+		default:
+		}
+
+		line := scanner.Text()
+		if !strings.HasPrefix(line, "data: ") {
+			continue
+		}
+		data := strings.TrimPrefix(line, "data: ")
+		if data == "[DONE]" {
+			break
+		}
+
+		// Parse the SSE JSON chunk
+		var chunk struct {
+			Choices []struct {
+				Delta struct {
+					Content string `json:"content"`
+				} `json:"delta"`
+				FinishReason *string `json:"finish_reason"`
+			} `json:"choices"`
+		}
+		if err := json.Unmarshal([]byte(data), &chunk); err != nil {
+			continue // skip malformed chunks
+		}
+		if len(chunk.Choices) == 0 {
+			continue
+		}
+
+		delta := chunk.Choices[0].Delta.Content
+		if delta == "" {
+			continue
+		}
+
+		accumulated.WriteString(delta)
+		if onChunk != nil {
+			onChunk(accumulated.String())
+		}
+	}
+
+	if err := scanner.Err(); err != nil {
+		return accumulated.String(), fmt.Errorf("stream interrupted: %w", err)
+	}
+
+	return accumulated.String(), nil
+}
--- a/mcp/interface.go
+++ b/mcp/interface.go
@@ -10,21 +10,52 @@ type AIClient interface {
 	SetAPIKey(apiKey string, customURL string, customModel string)
 	SetTimeout(timeout time.Duration)
 	CallWithMessages(systemPrompt, userPrompt string) (string, error)
-	CallWithRequest(req *Request) (string, error) // Builder pattern API (supports advanced features)
+	CallWithRequest(req *Request) (string, error)
+	// CallWithRequestStream streams the LLM response via SSE.
+	// onChunk is called with the full accumulated text so far (not raw deltas).
+	// Returns the complete final text when done.
+	CallWithRequestStream(req *Request, onChunk func(string)) (string, error)
+	// CallWithRequestFull returns both text content and tool calls.
+	// Use this when the request includes Tools — the LLM may respond with
+	// either a plain text reply (LLMResponse.Content) or tool invocations
+	// (LLMResponse.ToolCalls), but not both.
+	CallWithRequestFull(req *Request) (*LLMResponse, error)
 }

-// clientHooks internal hook interface (for subclass to override specific steps)
-// These methods are only used inside the package to implement dynamic dispatch
+// clientHooks is the internal dispatch interface used to implement per-provider
+// polymorphism without Go's lack of virtual methods.
+//
+// Each method can be overridden by an embedding struct (e.g. ClaudeClient).
+// The base *Client provides OpenAI-compatible defaults; providers with a
+// different wire format (Anthropic, Gemini native, etc.) override only what
+// differs.  All call-path methods in client.go invoke these via c.hooks so
+// that the override is always picked up at runtime.
 type clientHooks interface {
-	// Hook methods that can be overridden by subclass
-
+	// ── Simple CallWithMessages path ────────────────────────────────────────
 	call(systemPrompt, userPrompt string) (string, error)
-
 	buildMCPRequestBody(systemPrompt, userPrompt string) map[string]any
+
+	// ── Shared request plumbing ─────────────────────────────────────────────
 	buildUrl() string
 	buildRequest(url string, jsonData []byte) (*http.Request, error)
 	setAuthHeader(reqHeaders http.Header)
 	marshalRequestBody(requestBody map[string]any) ([]byte, error)
+
+	// ── Advanced (Request-object) path ──────────────────────────────────────
+	// buildRequestBodyFromRequest converts a *Request into the provider's
+	// native wire-format map.  Providers that use a different protocol (e.g.
+	// Anthropic uses "input_schema" for tools, "tool_use" content blocks, and
+	// a top-level "system" field) override this method.
+	buildRequestBodyFromRequest(req *Request) map[string]any
+
+	// parseMCPResponse extracts the plain-text reply from a non-streaming
+	// response body.
 	parseMCPResponse(body []byte) (string, error)
+
+	// parseMCPResponseFull extracts both text and tool calls.  Providers whose
+	// response envelope differs from the OpenAI choices[] structure (e.g.
+	// Anthropic content[] with tool_use blocks) override this method.
+	parseMCPResponseFull(body []byte) (*LLMResponse, error)
+
 	isRetryableError(err error) bool
 }
--- a/mcp/request.go
+++ b/mcp/request.go
@@ -1,9 +1,34 @@
 package mcp

-// Message represents a conversation message
+// Message represents a conversation message.
+// Supports plain messages (Role+Content), assistant tool-call messages (ToolCalls),
+// and tool result messages (Role="tool", ToolCallID, Content).
 type Message struct {
-	Role    string `json:"role"`    // "system", "user", "assistant"
-	Content string `json:"content"` // Message content
+	Role       string     `json:"role"`                  // "system", "user", "assistant", "tool"
+	Content    string     `json:"content,omitempty"`     // Text content (omitted when ToolCalls present)
+	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`  // Set by assistant when calling tools
+	ToolCallID string     `json:"tool_call_id,omitempty"` // Set on role="tool" result messages
+}
+
+// ToolCall is a single function call requested by the LLM.
+type ToolCall struct {
+	ID       string           `json:"id"`       // Unique call ID (e.g. "call_abc123")
+	Type     string           `json:"type"`     // Always "function"
+	Function ToolCallFunction `json:"function"` // Function name and JSON-serialised arguments
+}
+
+// ToolCallFunction holds the function name and raw JSON arguments string.
+type ToolCallFunction struct {
+	Name      string `json:"name"`      // Function name
+	Arguments string `json:"arguments"` // JSON-encoded argument object
+}
+
+// LLMResponse is returned by CallWithRequestFull and carries both the assistant
+// text reply (Content) and any structured tool calls (ToolCalls).
+// Exactly one of the two fields will be non-empty for a well-formed response.
+type LLMResponse struct {
+	Content   string     // Plain-text reply (final answer)
+	ToolCalls []ToolCall // Structured tool invocations
 }

 // Tool represents a tool/function that AI can call
--- a/mcp/x402.go
+++ b/mcp/x402.go
@@ -0,0 +1,219 @@
+package mcp
+
+import (
+	"bytes"
+	"crypto/ecdsa"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/ethereum/go-ethereum/crypto"
+)
+
+// ── Shared x402 types ────────────────────────────────────────────────────────
+
+// x402v2PaymentRequired is the structure of the Payment-Required header (x402 v2).
+type x402v2PaymentRequired struct {
+	X402Version int              `json:"x402Version"`
+	Accepts     []x402AcceptOption `json:"accepts"`
+	Resource    *x402Resource    `json:"resource"`
+}
+
+// x402AcceptOption is a payment option from the x402 v2 header.
+type x402AcceptOption struct {
+	Scheme            string            `json:"scheme"`
+	Network           string            `json:"network"`
+	Amount            string            `json:"amount"`
+	Asset             string            `json:"asset"`
+	PayTo             string            `json:"payTo"`
+	MaxTimeoutSeconds int               `json:"maxTimeoutSeconds"`
+	Extra             map[string]string `json:"extra"`
+}
+
+// x402Resource describes the resource being paid for.
+type x402Resource struct {
+	URL         string `json:"url"`
+	Description string `json:"description"`
+	MimeType    string `json:"mimeType"`
+}
+
+// x402SignFunc is a callback that signs an x402 payment header and returns the
+// base64-encoded payment signature.
+type x402SignFunc func(paymentHeaderB64 string) (string, error)
+
+// ── Shared x402 helpers ──────────────────────────────────────────────────────
+
+// x402DecodeHeader decodes a base64-encoded x402 Payment-Required header,
+// trying RawStdEncoding first then StdEncoding as fallback.
+func x402DecodeHeader(b64 string) ([]byte, error) {
+	decoded, err := base64.RawStdEncoding.DecodeString(b64)
+	if err != nil {
+		decoded, err = base64.StdEncoding.DecodeString(b64)
+		if err != nil {
+			return nil, fmt.Errorf("failed to base64-decode payment header: %w", err)
+		}
+	}
+	return decoded, nil
+}
+
+// signBasePaymentHeader decodes a base64 x402 header, parses it, and signs with
+// EIP-712 (USDC TransferWithAuthorization). Shared by BlockRunBase and Claw402.
+func signBasePaymentHeader(privateKey *ecdsa.PrivateKey, paymentHeaderB64 string, providerName string) (string, error) {
+	if privateKey == nil {
+		return "", fmt.Errorf("no private key set for %s wallet", providerName)
+	}
+
+	decoded, err := x402DecodeHeader(paymentHeaderB64)
+	if err != nil {
+		return "", err
+	}
+
+	var req x402v2PaymentRequired
+	if err := json.Unmarshal(decoded, &req); err != nil {
+		return "", fmt.Errorf("failed to parse x402 v2 payment header: %w", err)
+	}
+	if len(req.Accepts) == 0 {
+		return "", fmt.Errorf("no payment options in x402 response")
+	}
+
+	senderAddr := crypto.PubkeyToAddress(privateKey.PublicKey).Hex()
+	return signX402Payment(privateKey, senderAddr, req.Accepts[0], req.Resource)
+}
+
+// doX402Request executes an HTTP request and handles the x402 v2 payment flow.
+// On a 402 response it reads the Payment-Required (or X-Payment-Required) header,
+// signs via signFn, retries with Payment-Signature, and logs the Payment-Response
+// header (tx hash) on success.
+func doX402Request(
+	httpClient *http.Client,
+	buildReqFn func() (*http.Request, error),
+	signFn x402SignFunc,
+	providerTag string,
+	logger Logger,
+) ([]byte, error) {
+	req, err := buildReqFn()
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to send request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == http.StatusPaymentRequired {
+		paymentHeader := resp.Header.Get("Payment-Required")
+		if paymentHeader == "" {
+			paymentHeader = resp.Header.Get("X-Payment-Required")
+		}
+		if paymentHeader == "" {
+			body, _ := io.ReadAll(resp.Body)
+			return nil, fmt.Errorf("received 402 but no Payment-Required header found. Body: %s", string(body))
+		}
+
+		// Drain 402 body to allow HTTP connection reuse.
+		_, _ = io.Copy(io.Discard, resp.Body)
+
+		paymentSig, err := signFn(paymentHeader)
+		if err != nil {
+			return nil, fmt.Errorf("failed to sign x402 payment: %w", err)
+		}
+
+		req2, err := buildReqFn()
+		if err != nil {
+			return nil, fmt.Errorf("failed to build retry request: %w", err)
+		}
+		req2.Header.Set("X-Payment", paymentSig)
+		req2.Header.Set("Payment-Signature", paymentSig)
+
+		resp2, err := httpClient.Do(req2)
+		if err != nil {
+			return nil, fmt.Errorf("failed to send payment retry: %w", err)
+		}
+		defer resp2.Body.Close()
+
+		body2, err := io.ReadAll(resp2.Body)
+		if err != nil {
+			return nil, fmt.Errorf("failed to read payment retry response: %w", err)
+		}
+		if resp2.StatusCode != http.StatusOK {
+			return nil, fmt.Errorf("%s payment retry failed (status %d): %s", providerTag, resp2.StatusCode, string(body2))
+		}
+
+		if txHash := resp2.Header.Get("Payment-Response"); txHash != "" {
+			logger.Infof("💰 [%s] Payment tx: %s", providerTag, txHash)
+		}
+
+		return body2, nil
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("%s API error (status %d): %s", providerTag, resp.StatusCode, string(body))
+	}
+	return body, nil
+}
+
+// x402BuildRequest creates a POST request with Content-Type but no auth header.
+func x402BuildRequest(url string, jsonData []byte) (*http.Request, error) {
+	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
+	if err != nil {
+		return nil, fmt.Errorf("fail to build request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	return req, nil
+}
+
+// x402SetAuthHeader is a no-op — x402 providers authenticate via payment signing.
+func x402SetAuthHeader(_ http.Header) {}
+
+// x402Call handles the x402 payment flow for the simple CallWithMessages path.
+func x402Call(c *Client, signFn x402SignFunc, tag string, systemPrompt, userPrompt string) (string, error) {
+	c.logger.Infof("📡 [%s] Request AI Server: %s", tag, c.BaseURL)
+
+	requestBody := c.hooks.buildMCPRequestBody(systemPrompt, userPrompt)
+	jsonData, err := c.hooks.marshalRequestBody(requestBody)
+	if err != nil {
+		return "", err
+	}
+
+	body, err := doX402Request(c.httpClient, func() (*http.Request, error) {
+		return c.hooks.buildRequest(c.hooks.buildUrl(), jsonData)
+	}, signFn, tag, c.logger)
+	if err != nil {
+		return "", err
+	}
+	return c.hooks.parseMCPResponse(body)
+}
+
+// x402CallFull handles the x402 payment flow for the advanced Request path.
+func x402CallFull(c *Client, signFn x402SignFunc, tag string, req *Request) (*LLMResponse, error) {
+	if c.APIKey == "" {
+		return nil, fmt.Errorf("AI API key not set, please call SetAPIKey first")
+	}
+	if req.Model == "" {
+		req.Model = c.Model
+	}
+
+	c.logger.Infof("📡 [%s] Request AI (full): %s", tag, c.BaseURL)
+
+	requestBody := c.hooks.buildRequestBodyFromRequest(req)
+	jsonData, err := c.hooks.marshalRequestBody(requestBody)
+	if err != nil {
+		return nil, err
+	}
+
+	body, err := doX402Request(c.httpClient, func() (*http.Request, error) {
+		return c.hooks.buildRequest(c.hooks.buildUrl(), jsonData)
+	}, signFn, tag, c.logger)
+	if err != nil {
+		return nil, err
+	}
+	return c.hooks.parseMCPResponseFull(body)
+}