SolWaveSign In

x402 AI Starter Kit — Documentation

Welcome to the x402 AI Starter Kit (Solana Edition) documentation. This document provides a detailed, end-to-end guide to the starter kit: architecture, installation, configuration, developer workflows, payment flows using x402 on Solana, API references, examples, troubleshooting, and deployment instructions.

Search Documentation

Search for a command to run...

Quick Start

Get started with the NPM SDK in minutes

View Quick Start Guide

Table of Contents

Overview

Introduction to x402 AI Starter Kit (Solana Edition)

Architecture & Components

System architecture and component overview

Prerequisites

Required tools and dependencies

Getting Started

Setup and deployment guide

Configuration & Environment Variables

Environment configuration guide

Solana Integration & Wallet Flow

Solana blockchain integration

x402 Payment Protocol Explained

Understanding the x402 payment protocol

MCP Server & Agent Integration

MCP server setup and agent integration

API Reference

Complete API documentation

Example Flows / Walkthroughs

Step-by-step examples and tutorials

Testing & Debugging

Testing and debugging guide

Security Considerations

Security best practices

Deployment

Deployment instructions

1. Overview

The x402 AI Starter Kit (Solana Edition) is a reference application demonstrating how AI agents (built with an Agent Development Kit) can request and process payments using the x402 protocol and the Solana blockchain. The starter kit includes:

  • A Next.js web UI providing a friendly front-end for testing and interacting with agents.
  • AI tools panel and pre-built agent flows (client/merchant patterns).
  • An MCP (merchant control plane) server component for account provisioning and payment orchestration.
  • Example integrations showing how to create, sign, and confirm Solana transactions (SOL / USDC) in response to x402 payment requests.

This kit is ideal for developers building pay-to-use AI services, agent-to-agent commerce, or experimenting with decentralized payment coordination using x402 + Solana.

2. Architecture & Components

High-level components:

  • Next.js Frontend ( / ): UI for interacting with agents, quick actions (Check Solana account, Test x402 payment), model selector, and chat interface.
  • MCP Server ( /mcp ): Backend service that manages accounts, issues x402 requests, and orchestrates payment transactions for merchants.
  • ADK Agents: Client agent and merchant agent examples that run A2A (agent-to-agent) flows using the ADK library.
  • Solana Blockchain: The blockchain environment for production transactions on Solana mainnet.

Flow overview:

  1. User interacts with the Frontend (eg. "I want to buy banana").
  2. Client Agent constructs an x402 payment request targeted at the Merchant Agent.
  3. Merchant Agent responds with payment instructions (amount, token, address, or a prepared transaction).
  4. Client signs and submits the transaction to Solana (via wallet / MCP helper / simulated signer).
  5. Merchant confirms payment and completes the service.

3. Prerequisites

Before you begin, install the following on your machine:

  • Node.js (v18+ recommended) and npm/yarn
  • Git
  • Docker (optional, useful for MCP server deployment)
  • Solana CLI (for advanced blockchain interactions)
  • A wallet integration (eg. Phantom or Solflare) for signing transactions

Recommended dev tools:

  • VS Code
  • Postman / Insomnia (for API testing)

4. Getting Started

1. Clone the repo

git clone <REPO_URL>
cd x402-ai-starter-kit

2. Install dependencies

# in the root directory (Next.js frontend)
npm install

# if MCP server has a separate package
cd mcp-server && npm install

3. Configure environment variables

See the Configuration section below for full details on the env variables. Configure your environment variables in your hosting platform or deployment environment.

4. Deploy the application

Deploy the application to your hosting platform:

  • Deploy Next.js frontend to Vercel or your preferred platform
  • Deploy MCP server to your backend infrastructure
  • Configure production environment variables

5. Configure agents

Set up your ADK agents with production credentials and configuration. Agents will register in the ADK environment and can be invoked from the UI.

5. Configuration & Environment Variables

Frontend Environment Variables

NEXT_PUBLIC_API_BASE_URL=https://api.yourdomain.com # MCP server address
NEXT_PUBLIC_ADK_ENDPOINT=https://adk.yourdomain.com # ADK or agent endpoint
NEXT_PUBLIC_SOLANA_NETWORK=mainnet-beta
NEXT_PUBLIC_DEFAULT_TOKEN_USDC=USDC_MAINNET_MINT_ADDRESS

MCP Server Environment Variables

PORT=4000
SOLANA_CLUSTER=mainnet-beta
SOLANA_RPC=https://api.mainnet-beta.solana.com
USDC_MINT_ADDRESS=<USDC_MAINNET_MINT>

Agent configuration

  • AGENT_ID / AGENT_TOKEN (ADK authentication)
  • MERCHANT_PUBLIC_KEY — the Solana address merchants use to receive payments

Keep secrets (private keys, service tokens) out of git and use environment variables or secret managers.

6. Solana Integration & Wallet Flow

Supported Wallets

The SDK supports 6 major Solana wallets with priority ranking:

  1. Phantom - Most popular Solana wallet
  2. Solflare - Strong DeFi presence
  3. Backpack - Essential for xNFT ecosystem
  4. Glow - Light, fast, mobile-friendly
  5. Slope - Popular in Asia markets
  6. Ledger - Enterprise-grade hardware wallet

Wallet Integration Architecture

The wallet integration uses a WalletSigner interface abstraction that decouples SDK logic from UI wallet adapter implementation. This ensures:

  • SDK works with any wallet implementing the interface
  • No direct wallet object dependencies
  • Clean separation of concerns
  • Easy testing and mocking

Wallet Connection Flow

  1. Frontend detects installed wallets automatically
  2. Wallet adapter ranks wallets by priority (Phantom → Solflare → Backpack → Glow → Slope → Ledger)
  3. User selects wallet or auto-connects to highest priority
  4. Wallet adapter provides WalletSigner interface to SDK
  5. SDK uses signer for transaction signing

Payment Flow with Wallets

  1. AI agent generates x402 payment request
  2. Frontend receives and displays payment confirmation dialog
  3. SDK builds transaction from x402 payload (validates, computes ATA, adds memo)
  4. Wallet signs transaction (user approves in wallet popup)
  5. SDK submits transaction to Solana RPC
  6. SDK waits for on-chain confirmation
  7. Payment proof sent back to AI agent
  8. Merchant agent verifies payment and completes order

USDC / Token flow

  1. Merchant requests payment: 5 USDC to merchant_address.
  2. Client prepares a token transfer or uses Solana Pay / associated token accounts.
  3. Client signs the transfer and submits to Solana RPC.
  4. Merchant watches the transaction signature; once confirmed, service is delivered.

7. x402 Payment Protocol Explained

x402 is a lightweight extension of HTTP payment semantics for agent-to-agent commerce. The important concepts in starter kit context:

  • Payment Request: An agent (merchant) responds to a service invocation with an x402 payment requirement (amount, token, target address, optional prepared transaction, expiration).
  • Payment Response: The payer (client) either approves and signs a transaction, or returns a proof-of-payment after submission.
  • Receipt/Confirmation: Merchant validates the transaction on-chain and completes the requested action.

Typical fields in an x402 payload:

{
  "amount": "5000",
  "currency": "USDC",
  "token_mint": "<USDC_MINT_ADDRESS>",
  "recipient": "<merchant_sol_address>",
  "memo": "x402-payment-for:banana-order-123",
  "expires_at": "2025-01-01T00:00:00Z",
  "prepared_tx": "<optional_base64_serialized_tx>"
}

Prepared transaction mode: the merchant may provide a prepared transaction (unsigned or partially signed) for the payer to sign and submit.

Security note: Never rely solely on off-chain signals for payment completion; always validate on-chain confirmations and expected token amounts.

8. MCP Server & Agent Integration

The MCP server exposes endpoints that agents and the frontend use for payment orchestration. Core endpoints include:

  • POST /prepare-payment — merchant requests the server prepare a transaction payload
  • POST /validate-payment — merchant asks server to validate payment using transaction signature
  • GET /health — service health check

MCP responsibilities

  • Orchestrate payment transactions
  • Offer prepared transaction generation
  • Provide payment validation services

Agent interactions

  • Agents call MCP for payment orchestration and transaction preparation
  • Frontend triggers agent invocations via ADK endpoints; agents in turn orchestrate with MCP

9. API Reference

GET /health

Returns service health and Solana cluster connectivity.

POST /prepare-payment

Create a prepared transaction for token transfer

Request:

{
  "from": "payerPubkey",
  "to": "merchantPubkey",
  "amount": "5",
  "mint": "USDC_MINT"
}

Response:

{ "preparedTxBase64": "...", "recentBlockhash": "..." }

POST /validate-payment

Validate a tx signature and token transfer

Request:

{ "signature": "...", "expectedAmount": 5, "mint": "USDC_MINT" }

Response:

{ "status": "confirmed", "confirmedSlot": 12345 }

This is a compact reference — adapt to your actual code routes.

10. Example Flows / Walkthroughs

Example 1 — Basic buyer flow (UI + Phantom wallet)

  1. User types in the UI: "I want to buy banana".
  2. Client agent constructs a purchase intent and asks merchant agent for price.
  3. Merchant replies with x402 payment request: 5 USDC to merchantAddress.
  4. Frontend opens Phantom signature modal with a token transfer transaction (or uses prepare-payment to get a prepared transaction).
  5. User confirms and signs in Phantom; the tx is submitted to Solana.
  6. Merchant observes the tx signature, validates token amount, and replies: "Your order is being prepared".

11. Testing & Debugging

For monitoring and debugging, use the following approaches:

  • Monitor transactions via Solana Explorer
  • Check MCP server logs for payment orchestration
  • Use browser DevTools to inspect agent interactions
  • Set up proper logging and monitoring infrastructure
  • Use error tracking services for production issues

12. Security Considerations

  • Never use server signing in production — always require user wallet signatures
  • Validate all on-chain transactions before completing services
  • Use proper key management — never commit private keys to git
  • Implement rate limiting on API endpoints
  • Use HTTPS in production
  • Validate payment amounts and recipients on-chain
  • Implement proper error handling and logging

13. Deployment (Vercel & Production Tips)

For deployment to Vercel or other platforms:

  • Set all environment variables in your hosting platform
  • Use production Solana cluster (mainnet-beta) for live services
  • Configure proper CORS settings
  • Set up monitoring and alerting
  • Use environment-specific configuration
  • Enable proper logging and error tracking
  • Configure SSL/TLS certificates
  • Set up CDN for static assets
  • Implement rate limiting and DDoS protection

14. Contributing

Contributions are welcome! Please follow the project's contribution guidelines and submit pull requests for any improvements.

15. License

Please refer to the project's LICENSE file for license information.