aptos-x402 2.2.3 → 2.3.0

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [2.3.0] - 2026-01-17
+
+### 🔴 Breaking Change (V2 Protocol Compliance)
+- **402 Response Format**: Payment requirements now sent via `PAYMENT-REQUIRED` header (base64 JSON) instead of response body
+- **Header Constants**: Added `PAYMENT_REQUIRED_HEADER` export
+
+### ✨ Improvements
+- **Backward Compatibility**: Client (`x402axios`) still reads from body if header is missing (V1 fallback)
+- **Protocol Compliance**: Now fully compliant with official x402 V2 specification
+
+## [2.2.4] - 2026-01-17
+
+### 🐛 Bug Fixes
+- Fixed npm package missing README and CHANGELOG
+
+## [2.2.3] - 2026-01-17
+
+### 🐛 Bug Fixes
+- Fixed minor typo in CHANGELOG
+
+## [2.2.2] - 2026-01-17
+
+### 📚 Documentation
+- Removed v1 deprecation warning from README
+
+## [2.2.1] - 2026-01-17
+
+### 📚 Documentation
+- Fixed README examples: Removed non-existent `x402axios.create()` references
+- Clarified v2 protocol changes: Header-based architecture, standard headers (no "X-" prefix), fungible assets
+- Updated "What's new" section with accurate v2.2.0 features
+
+## [2.2.0] - 2026-01-17
+
+### 🌟 New Features (v2 Protocol)
+- **Protocol Standards**: Removed "X-" prefix from headers (now `PAYMENT-SIGNATURE`).
+- **Header-Based Architecture**: Moved payment specifications and proofs to headers.
+- **Fungible Assets**: Native support for USDC transfers on Aptos (via `primary_fungible_store`).
+- **Geomi Gas Sponsorship**: Facilitator-sponsored gas fees for better UX.
+- **ARC-8004**: Added Agent Trust Layer (Identity, Reputation, Validation).
+
+### ⚡ Improvements
+- **Performance**: Faster settlement times and bug fixes.
+- **Bug Fixes**: Resolved performance bottlenecks and improved type safety.
+
+## [1.0.2] - 2025-01-10
+
+### ⚡ Performance Optimizations
+- **Hex Encoding**: Replaced base64 encoding with hex for transaction/signature (faster, more compact)
+  - Direct JSON payment header (no outer base64 encoding)
+  - ~1-2ms improvement per request
+- **Removed Verification Caching**: Eliminated middleware verification cache overhead (~5ms saved)
+- **Skipped Middleware Validation**: Removed redundant validation checks in middleware (~2-5ms saved)
+  - Single source of truth: facilitator handles all validation
+- **HTTP/2 Keep-Alive**: Added persistent connections for facilitator calls
+  - ~50-100ms improvement on subsequent requests
+  - Connection pooling and multiplexing support
+
+### 📊 Performance Impact
+- **First call**: ~8-12ms faster
+- **Subsequent calls**: ~58-112ms faster (with HTTP/2 keep-alive)
+- **Total improvement**: Combined with previous optimizations (async confirmation, simulation-only verification)
+
+### 🔧 Technical Changes
+- Updated all components to use consistent hex + JSON format
+  - Client (`x402axios`): Hex encoding for transaction/signature
+  - Middleware: Direct JSON parsing (no base64 decode)
+  - Facilitator endpoints: Hex decoding for transaction/signature
+- Improved code consistency across client, middleware, and facilitator
+- Better debugging with hex encoding (more human-readable)
+
+### 🐛 Bug Fixes
+- Fixed TypeScript build error in middleware (type assertion for SettleResponse)
+- Ensured all components use the same encoding format
+
+### ⚠️ Breaking Changes
+- **Not backward compatible**: Old clients sending base64 will fail
+- All components must be updated together (client, middleware, facilitator)
+
+## [0.2.0] - 2024-12-19
+
+### 🚀 Major Features
+- **Axios-Compatible Interface**: Complete rewrite of x402axios to work exactly like axios
+  - Support for all axios methods: `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()`, `.options()`
+  - Full axios configuration support: `timeout`, `headers`, `baseURL`, `params`, etc.
+  - `x402axios.create()` for creating instances with default configs
+  - Backward compatible with existing API
+
+### 🔧 Improvements
+- **Zero Fallbacks Policy**: Removed all silent fallbacks to testnet
+  - Throws clear errors when environment variables are missing
+  - No more silent defaults that could cause confusion
+- **Dynamic Explorer Links**: Explorer URLs now correctly reflect the network used
+  - Mainnet transactions show `?network=mainnet`
+  - Testnet transactions show `?network=testnet`
+  - No more hardcoded testnet links
+- **Enhanced Error Handling**: Better error messages and validation
+  - Clear indication when network configuration is missing
+  - Proper error propagation throughout the payment flow
+
+### 🛠️ Technical Changes
+- **Type Safety**: Full TypeScript support with proper interfaces
+  - `AxiosRequestConfig` interface for request configuration
+  - `AxiosResponse` interface for response handling
+  - Backward compatible `X402Response` alias
+- **Network Detection**: Automatic network detection from 402 responses
+  - No hardcoded network assumptions
+  - Proper network mapping and validation
+- **Documentation**: Comprehensive updates to all documentation
+  - Updated examples to use new axios interface
+  - Enhanced API reference with new types
+  - Improved quickstart guides
+
+### 🐛 Bug Fixes
+- Fixed recipient/sender address mismatch issue
+- Corrected network configuration handling
+- Fixed explorer URL generation for different networks
+- Resolved environment variable loading issues
+
+### 📚 Documentation
+- Updated all code examples to use new axios interface
+- Enhanced README with axios compatibility section
+- Updated API reference with new types and methods
+- Improved quickstart guides and troubleshooting
+
+## [0.1.3] - 2024-12-18
+
+### Features
+- Initial release with basic x402 payment functionality
+- Next.js middleware for payment protection
+- Basic x402axios wrapper for payment handling
+- Facilitator service for payment verification and settlement

package/COMPOSER_IMPLEMENTATION.md

@@ -0,0 +1,203 @@
+# Agent Composer Platform - Implementation Summary
+
+## Overview
+Successfully implemented a complete Agent Composer platform that allows users to create AI agents, assign them APIs/tools, fund them with APT (testnet), and interact with them through a chat interface. Agents autonomously make payments through the x402 protocol when calling APIs.
+
+## Implementation Details
+
+### 1. Storage Layer (`lib/storage/`)
+- **agents.ts**: File-based JSON storage for agent configurations
+  - CRUD operations for agents
+  - Private key storage (server-side only, never exposed to client)
+  - Client-safe agent retrieval (excludes private keys)
+  
+- **chats.ts**: File-based JSON storage for chat conversations
+  - Thread management per agent
+  - Message history with metadata (API calls, payment hashes, errors)
+  
+- **apis.ts**: Hardcoded API registry
+  - Weather API (existing `/api/protected/weather`)
+  - Example APIs for testing (stocks, search)
+  - Category-based filtering and search functionality
+
+### 2. Agent Utilities (`lib/agent/`)
+- **wallet.ts**: Wallet management utilities
+  - Agent wallet generation using `Account.generate()`
+  - Balance checking via Aptos SDK
+  - Faucet funding helper (for development)
+  
+- **executor.ts**: Agent execution logic
+  - Simple query parsing (keyword-based API selection)
+  - API calling via x402axios with agent's private key
+  - Error handling for insufficient funds and API failures
+
+### 3. API Endpoints (`app/api/`)
+- **GET /api/apis**: List available APIs (with category/search filtering)
+- **GET /api/agents**: List all agents (client-safe, no private keys)
+- **POST /api/agents**: Create new agent (generates wallet automatically)
+- **GET /api/agents/[agentId]**: Get agent details
+- **PATCH /api/agents/[agentId]**: Update agent settings
+- **DELETE /api/agents/[agentId]**: Delete agent
+- **GET /api/agents/[agentId]/balance**: Get agent wallet balance
+- **GET /api/agents/[agentId]/chat**: Get chat history
+- **POST /api/agents/[agentId]/chat**: Send message and execute agent query
+
+### 4. UI Components (`components/composer/`)
+- **AgentCard.tsx**: Agent display card with wallet info, balance, and actions
+- **AgentCreationWizard.tsx**: 3-step wizard for creating agents
+  - Step 1: Display settings (name, description, image, visibility)
+  - Step 2: API/tool selection
+  - Step 3: Review and create
+- **ApiSelector.tsx**: Searchable, filterable API browser with category tags
+- **FundingModal.tsx**: Modal for viewing wallet address and funding agent
+- **ChatInterface.tsx**: Full chat UI with message history, balance display, and funding integration
+
+### 5. Pages (`app/composer/`)
+- **page.tsx**: Main composer dashboard showing all user agents
+- **create/page.tsx**: Agent creation page
+- **[agentId]/page.tsx**: Agent chat interface
+- **[agentId]/settings/page.tsx**: Agent settings and wallet management
+
+### 6. Navigation
+- Updated Navbar to include "Composer" link
+
+### 7. Storage Configuration
+- Added `.composer-data/` to `.gitignore` for local storage files
+
+## Key Features Implemented
+
+1. **Agent Creation**
+   - Multi-step wizard with progress indicator
+   - Wallet generation (automatic Aptos wallet per agent)
+   - API selection from registry
+   - Public/private visibility settings
+
+2. **Agent Management**
+   - List view with balance display
+   - Edit agent settings
+   - Delete agents
+   - Wallet information display
+
+3. **Funding System**
+   - Display agent wallet address (copyable)
+   - Real-time balance checking
+   - Direct link to Aptos testnet faucet
+   - Balance refresh functionality
+
+4. **Chat Interface**
+   - Real-time messaging with agent
+   - Message history persistence
+   - Payment hash display for API calls
+   - Error handling with user-friendly messages
+   - Insufficient funds detection and funding prompts
+
+5. **Agent Execution**
+   - Simple keyword-based query parsing
+   - Automatic API selection based on query
+   - x402 payment handling (automatic via x402axios)
+   - Error handling and user feedback
+
+## Technical Stack
+
+- **Storage**: File-based JSON (`.composer-data/` directory)
+- **Wallet**: Aptos SDK (`@aptos-labs/ts-sdk`)
+- **Payments**: x402 protocol via `x402axios`
+- **UI**: Next.js 15, React 19, Tailwind CSS, shadcn/ui components
+- **Network**: Aptos testnet (for development)
+
+## Security Considerations
+
+- Private keys stored server-side only (never exposed to client)
+- Client-safe agent retrieval (excludes private keys)
+- Server-side validation for API calls
+- Balance checks before executing transactions
+
+## Usage Flow
+
+1. User navigates to `/composer`
+2. Clicks "Create Agent"
+3. Fills in agent details (name, description, visibility)
+4. Selects APIs/tools for the agent
+5. Reviews and creates agent (wallet auto-generated)
+6. Funds agent wallet with APT (testnet)
+7. Starts chatting with agent
+8. Agent automatically calls APIs and makes payments via x402 protocol
+
+## File Structure
+
+```
+lib/
+  storage/
+    agents.ts          # Agent CRUD operations
+    chats.ts           # Chat history storage
+    apis.ts            # API registry
+  agent/
+    wallet.ts          # Wallet utilities
+    executor.ts        # Agent execution logic
+
+app/
+  api/
+    apis/
+      route.ts         # API listing endpoint
+    agents/
+      route.ts         # Agent CRUD endpoints
+      [agentId]/
+        route.ts       # Individual agent endpoints
+        balance/
+          route.ts     # Balance checking
+        chat/
+          route.ts     # Chat message handling
+  composer/
+    page.tsx           # Main dashboard
+    create/
+      page.tsx         # Agent creation
+    [agentId]/
+      page.tsx         # Chat interface
+      settings/
+        page.tsx       # Agent settings
+
+components/
+  composer/
+    AgentCard.tsx
+    AgentCreationWizard.tsx
+    ApiSelector.tsx
+    FundingModal.tsx
+    ChatInterface.tsx
+  ui/
+    input.tsx          # Input component (new)
+```
+
+## Environment Variables
+
+- `NEXT_PUBLIC_BASE_URL`: Base URL for API endpoints (optional, defaults to localhost:3000)
+- `FACILITATOR_URL`: x402 facilitator service URL (existing)
+- `PAYMENT_RECIPIENT_ADDRESS`: Payment recipient address (existing)
+- `APTOS_NETWORK`: Aptos network (testnet/mainnet) (existing)
+
+## Testing Recommendations
+
+1. Create an agent and verify wallet generation
+2. Fund agent wallet via testnet faucet
+3. Test chat interface with weather queries
+4. Verify x402 payments are processed correctly
+5. Test error handling (insufficient funds scenario)
+6. Test agent deletion and cleanup
+
+## Future Enhancements (Out of Scope for MVP)
+
+- LLM integration for smarter query understanding
+- Public agent marketplace
+- Usage analytics dashboard
+- API cost estimation before calls
+- Multi-agent workflows
+- Agent templates/presets
+- On-chain storage for agent metadata (mentioned by user)
+
+## Notes
+
+- All agent data stored locally in `.composer-data/` directory
+- Private keys are stored in plain text (consider encryption for production)
+- Base URL detection works in browser and server contexts
+- Simple keyword-based API selection (can be enhanced with LLM later)
+
+

package/README.md

@@ -30,7 +30,7 @@ Built for **machine-to-machine micropayments**, this SDK provides zero-friction
 - 🚚 **Header-Based Spec**: Payment specs and proofs handling moved entirely to headers.
 - ⚡ **Performance**: Significant speed improvements with bug fixes and optimizations.
 
-> ⚡ **Performance:** Latest optimizations deliver **faster settlement** with verification caching, async confirmation, and smart deduplication. See [PERFORMANCE_OPTIMIZATIONS.md](./PERFORMANCE_OPTIMIZATIONS.md) for details.
+> ⚡ **Performance:** Latest optimizations deliver **faster settlement** with verification caching, async confirmation, and smart deduplication.
 
 <!-- ## Key Features
 
@@ -68,25 +68,7 @@ npm install aptos-x402
 - **TypeScript:** 5.x (recommended)
 - **Aptos SDK:** 1.26.0 or higher (included as peer dependency)
 
----
-
-## 🤖 AI-Powered Setup (Cursor IDE)
-
-Get started in seconds with AI-assisted integration:
-
-```bash
-mkdir -p .cursor/rules
-curl -o .cursor/rules/aptos-x402.mdc https://raw.githubusercontent.com/adipundir/aptos-x402/main/integration/aptos-x402.mdc
-```
-
-**Restart Cursor IDE**, then ask:
-> "Set up Aptos x402 in my Next.js app with payment middleware and a test client component"
-
-The MDC context file provides Cursor with complete API documentation, types, and examples for accurate code generation.
 
-**Learn more:** [Cursor Integration Guide](./docs/guides/cursor-integration.md)
-
----
 
 ## 🛒 Client Integration (Consuming Paid APIs)
 

package/components/auth/LoginModal.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+import { signIn } from 'next-auth/react';
+import { useState } from 'react';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Loader2 } from 'lucide-react';
+import { SiGoogle, SiGithub } from '@icons-pack/react-simple-icons';
+
+interface LoginModalProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+export function LoginModal({ open, onOpenChange }: LoginModalProps) {
+  const [loading, setLoading] = useState<'google' | 'github' | null>(null);
+
+  const handleSignIn = async (provider: 'google' | 'github') => {
+    setLoading(provider);
+    try {
+      await signIn(provider, { callbackUrl: '/' });
+    } catch (error) {
+      console.error('Sign in error:', error);
+      setLoading(null);
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-[380px] p-6 bg-white border border-zinc-200 shadow-xl rounded-xl">
+        <DialogHeader className="space-y-1 pb-2">
+          <DialogTitle className="text-lg font-semibold text-zinc-900">
+            Sign in
+          </DialogTitle>
+          <DialogDescription className="text-sm text-zinc-500">
+            Continue to Agent Composer (Beta)
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-3 pt-2">
+          <Button
+            onClick={() => handleSignIn('google')}
+            disabled={loading !== null}
+            variant="outline"
+            className="w-full h-11 bg-white hover:bg-zinc-50 text-zinc-900 border border-zinc-200 font-medium"
+          >
+            {loading === 'google' ? (
+              <Loader2 className="w-4 h-4 mr-2 animate-spin" />
+            ) : (
+              <SiGoogle className="w-4 h-4 mr-2" />
+            )}
+            Continue with Google
+          </Button>
+
+          <div className="relative">
+            <Button
+              disabled={true}
+              variant="outline"
+              className="w-full h-11 bg-zinc-50 text-zinc-400 border border-zinc-100 cursor-not-allowed font-medium"
+            >
+              <SiGithub className="w-4 h-4 mr-2 opacity-50" />
+              Continue with GitHub
+            </Button>
+            <span className="absolute right-3 top-1/2 -translate-y-1/2 text-[10px] px-1.5 py-0.5 bg-zinc-200 text-zinc-500 rounded font-medium">
+              Soon
+            </span>
+          </div>
+        </div>
+
+        <p className="text-[11px] text-zinc-400 text-center pt-3">
+          By continuing, you agree to our Terms & Privacy Policy
+        </p>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/components/auth/SessionProvider.tsx

@@ -0,0 +1,11 @@
+'use client';
+
+import { SessionProvider as NextAuthSessionProvider } from 'next-auth/react';
+
+export function SessionProvider({ children }: { children: React.ReactNode }) {
+  return <NextAuthSessionProvider>{children}</NextAuthSessionProvider>;
+}
+
+
+
+

package/components/auth/UserMenu.tsx

@@ -0,0 +1,8 @@
+import { auth } from '@/lib/auth';
+import { UserMenuClient } from './UserMenuClient';
+
+export async function UserMenu() {
+  const session = await auth();
+  
+  return <UserMenuClient session={session} />;
+}

package/components/auth/UserMenuClient.tsx

@@ -0,0 +1,117 @@
+'use client';
+
+import { signOut } from 'next-auth/react';
+import Link from 'next/link';
+import { Button } from '@/components/ui/button';
+import { LogOut, User, ChevronDown } from 'lucide-react';
+import { useState, useRef, useEffect } from 'react';
+import { LoginModal } from './LoginModal';
+import type { Session } from 'next-auth';
+
+interface UserMenuClientProps {
+  session: Session | null;
+}
+
+export function UserMenuClient({ session }: UserMenuClientProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [loginModalOpen, setLoginModalOpen] = useState(false);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (menuRef.current && !menuRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    }
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  if (!session) {
+    return (
+      <>
+        <Button 
+          variant="outline" 
+          size="sm" 
+          className="border-zinc-200"
+          onClick={() => setLoginModalOpen(true)}
+        >
+          Sign In
+        </Button>
+        <LoginModal open={loginModalOpen} onOpenChange={setLoginModalOpen} />
+      </>
+    );
+  }
+
+  return (
+    <div className="relative" ref={menuRef}>
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+        className="flex items-center gap-2 px-3 py-1.5 rounded-full bg-zinc-100 hover:bg-zinc-200 transition-colors"
+      >
+        {session.user?.image ? (
+          <img
+            src={session.user.image}
+            alt={session.user.name || 'User'}
+            className="w-7 h-7 rounded-full"
+          />
+        ) : (
+          <div className="w-7 h-7 rounded-full bg-zinc-900 flex items-center justify-center text-white text-sm font-medium">
+            {session.user?.name?.charAt(0) || 'U'}
+          </div>
+        )}
+        <span className="text-sm font-medium text-zinc-900 hidden sm:inline">
+          {session.user?.name?.split(' ')[0] || 'User'}
+        </span>
+        <ChevronDown className="w-4 h-4 text-zinc-500" />
+      </button>
+
+      {isOpen && (
+        <div className="absolute right-0 mt-2 w-72 rounded-xl bg-white shadow-lg border border-zinc-200 py-2 z-50">
+          <div className="px-4 py-3 border-b border-zinc-100">
+            <div className="flex items-center gap-3">
+              {session.user?.image ? (
+                <img
+                  src={session.user.image}
+                  alt={session.user.name || 'User'}
+                  className="w-10 h-10 rounded-full"
+                />
+              ) : (
+                <div className="w-10 h-10 rounded-full bg-zinc-900 flex items-center justify-center text-white font-medium">
+                  {session.user?.name?.charAt(0) || 'U'}
+                </div>
+              )}
+              <div className="flex-1 min-w-0">
+                <p className="text-sm font-medium text-zinc-900 truncate">
+                  {session.user?.name || 'User'}
+                </p>
+                <p className="text-xs text-zinc-500 truncate">
+                  {session.user?.email}
+                </p>
+              </div>
+            </div>
+          </div>
+
+          <div className="px-2 py-2">
+            <Link
+              href="/composer"
+              onClick={() => setIsOpen(false)}
+              className="flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-zinc-50 transition-colors"
+            >
+              <User className="w-4 h-4 text-zinc-500" />
+              <span className="text-sm text-zinc-700">My Agents</span>
+            </Link>
+            <button
+              onClick={() => signOut({ callbackUrl: '/' })}
+              className="w-full flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-red-50 transition-colors text-red-600"
+            >
+              <LogOut className="w-4 h-4" />
+              <span className="text-sm">Sign Out</span>
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+