@x402-iota/client

Client SDK for making HTTP requests with automatic x402 payment handling.

Overview

This package provides an HTTP client that automatically:

1. Detects HTTP 402 Payment Required responses
2. Generates EIP-712 signatures
3. Retries requests with payment header
4. Returns protected resources

Installation

npm install @x402-iota/client @x402-iota/core ethers axios

Quick Start

Basic Usage

import { X402Client } from "@x402-iota/client";
import { ethers } from "ethers";

const wallet = new ethers.Wallet(privateKey, provider);
const client = new X402Client({
  signer: wallet,
  network: "iota-evm-testnet",
});

// Make request - automatically handles 402!
const data = await client.get("http://api.example.com/protected");
console.log(data);

Request Methods

// GET request
const data = await client.get("/api/protected");

// POST request
const result = await client.post("/api/data", { key: "value" });

// PUT request
const updated = await client.put("/api/resource", { updated: true });

// DELETE request
const deleted = await client.delete("/api/resource");

How It Works

1. Client sends request
   ↓
2. Server returns 402 + PaymentRequirements
   ↓
3. Client parses payment requirements
   ↓
4. Client signs payment using EIP-712
   ↓
5. Client retries with X-PAYMENT header
   ↓
6. Server verifies payment
   ↓
7. Server returns protected resource
   ↓
8. Client returns data to caller

Error Handling

try {
  const data = await client.get("/api/protected");
} catch (error) {
  if (error.response?.status === 402) {
    // Payment required but failed
    console.log("Payment failed:", error.message);
  } else {
    // Other errors
    console.log("Request failed:", error.message);
  }
}

Configuration

interface X402ClientOptions {
  signer: ethers.Signer; // Wallet for signing
  network: Network; // IOTA network
}

Supported Networks

// Mainnet
"iota-mainnet"; // Chain ID: 1074
"iota-evm-mainnet"; // Chain ID: 8822

// Testnet
"iota-testnet"; // Chain ID: 1075
"iota-evm-testnet"; // Chain ID: 1075

Related Packages

• @x402-iota/core - Core types
• @x402-iota/react - React components

License

MIT