x402pp-client

Client SDK for AI agents and applications to interact with x402++ providers.

Installation

npm install x402pp-client

What is This?

This package enables AI agents and applications to:

• 🤝 Negotiate pricing with API providers
• 💰 Create prepaid sessions
• 🚀 Execute requests with automatic payment
• ✅ Verify cryptographic receipts
• 💵 Get refunds for unused balance

Quick Start

import { Connection, Keypair } from '@solana/web3.js';
import { X402Client } from 'x402pp-client';

// Initialize
const connection = new Connection('https://api.devnet.solana.com');
const wallet = Keypair.generate(); // Your agent's wallet
const client = new X402Client({ connection, wallet });

// 1. Create Intent (express your needs)
const intent = client.createIntent({
  capability: 'gpt-4-inference',
  maxPricePerRequest: 0.01,
  token: 'USDC',
  sla: { maxLatencyMs: 2000 }
});

// 2. Negotiate with provider
const offer = await client.negotiate('https://api.provider.com', intent);

// 3. Create prepaid session
const session = await client.createSession(offer);

// 4. Execute requests (payment automatic!)
const result = await client.executeRequest(session.sessionId, {
  prompt: 'Explain quantum computing'
});

console.log(result.data);     // API response
console.log(result.receipt);  // Cryptographic proof

// 5. Close session and get refund
await client.closeSession(session.sessionId);

Core Features

Automatic Negotiation

// Agent expresses maximum price
const intent = client.createIntent({
  maxPricePerRequest: 0.01,
  capability: 'ai-inference'
});

// Provider responds with actual price
const offer = await client.negotiate(endpoint, intent);

// Verify it's within budget
if (offer.pricePerRequest <= intent.maxPricePerRequest) {
  // Accept!
}

Prepaid Sessions

// Deposit once, make many requests
const session = await client.createSession(offer, {
  depositAmount: 1.0  // 1 USDC
});

// Make multiple requests without per-request transactions
await client.executeRequest(session.sessionId, request1);
await client.executeRequest(session.sessionId, request2);
await client.executeRequest(session.sessionId, request3);

Receipt Verification

const result = await client.executeRequest(sessionId, data);

// Every request gets a cryptographic receipt
console.log(result.receipt);
/*
{
  receiptId: "receipt_123",
  inputHash: "sha256(...)",    // Tamper-proof
  outputHash: "sha256(...)",   // Tamper-proof
  signature: "...",            // Provider's signature
  slaVerification: {
    met: true,
    metrics: { latency: { expected: 2000, actual: 1234 } }
  }
}
*/

SLA Enforcement

// Request SLA guarantees
const intent = client.createIntent({
  sla: {
    maxLatencyMs: 2000,      // Must respond within 2s
    minUptimePercent: 99.0,  // Must have 99% uptime
  }
});

// If provider breaches SLA, automatic refund!

API Reference

X402Client

Constructor

new X402Client({
  connection: Connection,    // Solana connection
  wallet: Keypair,          // Your wallet
  httpConfig?: {            // Optional HTTP settings
    timeout?: number,
    headers?: Record<string, string>
  }
})

Methods

createIntent(options)

client.createIntent({
  capability: string,
  maxPricePerRequest: number,
  token: 'SOL' | 'USDC' | 'USDT' | 'BONK',
  sla?: { maxLatencyMs?, minUptimePercent? },
  maxSessionBudget?: number,
  sessionDurationMs?: number,
  metadata?: Record<string, any>
})

negotiate(endpoint, intent)

const offer = await client.negotiate(
  'https://api.provider.com',
  intent
);

createSession(offer, options?)

const session = await client.createSession(offer, {
  depositAmount?: number,      // Custom deposit
  anchorOnChain?: boolean      // Store on Solana (optional)
});

executeRequest(sessionId, data)

const result = await client.executeRequest(
  sessionId,
  { prompt: 'Hello' }
);
// Returns: { data, receipt }

closeSession(sessionId)

const refund = await client.closeSession(sessionId);
// Returns: { refundAmount, txSignature }

getSession(sessionId)

const session = client.getSession(sessionId);

getActiveSessions()

const sessions = client.getActiveSessions();

Examples

AI Inference

const intent = client.createIntent({
  capability: 'gpt-4-inference',
  maxPricePerRequest: 0.01,
  token: 'USDC'
});

const offer = await client.negotiate('https://ai-api.com', intent);
const session = await client.createSession(offer);

const result = await client.executeRequest(session.sessionId, {
  prompt: 'Write a poem about Solana'
});

console.log(result.data.text);

Image Generation

const intent = client.createIntent({
  capability: 'image-generation',
  maxPricePerRequest: 0.05,
  token: 'USDC'
});

const offer = await client.negotiate('https://image-api.com', intent);
const session = await client.createSession(offer);

const result = await client.executeRequest(session.sessionId, {
  prompt: 'A futuristic city on Mars',
  style: 'photorealistic'
});

console.log(result.data.imageUrl);

Data Analysis

const intent = client.createIntent({
  capability: 'data-analysis',
  maxPricePerRequest: 0.001,
  token: 'USDC'
});

const offer = await client.negotiate('https://data-api.com', intent);
const session = await client.createSession(offer);

const result = await client.executeRequest(session.sessionId, {
  dataset: myData,
  operation: 'statistical-summary'
});

console.log(result.data.analysis);

Error Handling

try {
  const offer = await client.negotiate(endpoint, intent);
  const session = await client.createSession(offer);
  const result = await client.executeRequest(session.sessionId, data);
} catch (error) {
  if (error instanceof InvalidOfferError) {
    console.error('Offer validation failed');
  } else if (error instanceof SessionExpiredError) {
    console.error('Session expired, create new one');
  } else if (error instanceof InsufficientFundsError) {
    console.error('Session balance depleted');
  }
}

Related Packages

• x402pp-core - Core protocol (auto-installed)
• x402pp-server - For API providers

License

Apache 2.0