@x402-iota/core

Core types, utilities, and services for the x402 payment gateway SDK on IOTA blockchain.

Overview

This package provides the foundation for the x402 protocol implementation, including:

• Types & Interfaces: Complete TypeScript definitions for x402 protocol
• EIP-712 Utilities: Sign gasless transfers with EIP-712
• EIP-3009 Support: Implement transferWithAuthorization
• IOTA Network Helpers: RPC URLs, chain IDs, utilities
• Payment Services: PaymentVerifier and PaymentSettler
• Route Matching: Path pattern matching for protected routes

Installation

npm install @x402-iota/core
# or
pnpm add @x402-iota/core
# or
bun add @x402-iota/core

Quick Start

1. Import Types

import {
  PaymentRequirements,
  PaymentPayload,
  Network,
  ExactPayloadEVM,
} from "@x402-iota/core";

// Define payment requirements
const requirement: PaymentRequirements = {
  scheme: "exact",
  network: "iota-evm-testnet",
  maxAmountRequired: "1000000", // 1 USDC (6 decimals)
  resource: "/api/protected",
  description: "Access protected API",
  mimeType: "application/json",
  payTo: "0x1234567890123456789012345678901234567890",
  maxTimeoutSeconds: 3600,
  asset: "0xFbDa5F676cB37624f28265A144A48B0d6e87d3b6", // USDC on IOTA
  extra: {
    name: "USD Coin",
    version: "2",
  },
};

2. Use EIP-712 Signing

import { ethers } from "ethers";
import {
  signTransferAuthorization,
  createEIP712Domain,
  generateNonce,
} from "@x402-iota/core";

const wallet = new ethers.Wallet(privateKey, provider);
const domain = createEIP712Domain(requirement, 8822); // IOTA EVM chain ID

const authorization = {
  from: await wallet.getAddress(),
  to: requirement.payTo,
  value: requirement.maxAmountRequired,
  validAfter: Math.floor(Date.now() / 1000) - 60,
  validBefore: Math.floor(Date.now() / 1000) + 3600,
  nonce: generateNonce(),
};

const signature = await signTransferAuthorization(
  wallet,
  domain,
  authorization
);

// signature: { v: number; r: string; s: string }

3. Verify Payment

import { PaymentVerifier } from "@x402-iota/core";

const verifier = new PaymentVerifier({
  facilitatorUrl: "http://localhost:3001",
  onChainVerification: false, // Use facilitator
});

const isValid = await verifier.verifyPayment(paymentHeader, requirement);
console.log("Payment valid:", isValid);

API Reference

Types

Network

type Network =
  | "iota-mainnet" // L1 Move chain
  | "iota-testnet" // L1 testnet
  | "iota-evm-mainnet" // L2 EVM (Chain ID: 8822)
  | "iota-evm-testnet"; // L2 testnet (Chain ID: 1075)

PaymentRequirements

interface PaymentRequirements {
  scheme: "exact" | "upto";
  network: Network;
  maxAmountRequired: string; // uint256 as string
  resource: string; // API endpoint
  description: string; // Human-readable
  mimeType: string; // Content type
  payTo: string; // Recipient address
  maxTimeoutSeconds: number; // Payment timeout
  asset: string; // Token contract address
  extra?: {
    name?: string; // EIP-712 token name
    version?: string; // EIP-712 version
  };
}

Functions

generateNonce(): string

Generate cryptographically secure random nonce (32 bytes).

const nonce = generateNonce();
// '0x0f3e4c9a8b2d7f1e6a3c5b9d2f4e8a1c3b7f0d2e5a8c1f4b9e2a5c8f1d4e7a'

getChainId(network: Network): number

Get IOTA chain ID for network.

const chainId = getChainId("iota-evm-testnet");
// 1075

getRpcUrl(network: Network): string

Get RPC URL for network.

const rpcUrl = getRpcUrl("iota-evm-mainnet");
// 'https://json-rpc.evm.iotaledger.net'

matchRoute(path: string, routes: Record<string, RouteConfig>): RouteConfig | null

Match request path against route patterns.

const routes = {
  "/api/protected": { amount: "1000000" },
  "/api/premium/*": { amount: "5000000" },
};

const config = matchRoute("/api/premium/data", routes);
// { amount: '5000000' }

Services

PaymentVerifier

const verifier = new PaymentVerifier({
  facilitatorUrl: "http://localhost:3001",
  onChainVerification: false,
});

const isValid = await verifier.verifyPayment(paymentHeader, requirement);

PaymentSettler

const settler = new PaymentSettler({
  facilitatorUrl: "http://localhost:3001",
});

const result = await settler.settlePayment(paymentHeader, requirement);
// { success: boolean; error?: string; txHash?: string }

Related Packages

• @x402-iota/client - Client SDK
• @x402-iota/react - React components
• @x402-iota/server-express - Express middleware
• @x402-iota/server-nextjs - Next.js middleware

License

MIT