nory-x402-payer

x402 payment client for AI agents. Automatically pay for HTTP 402 resources with USDC on Solana.

The Problem

Your AI agent encounters a paid API:

HTTP 402 Payment Required
{
  "error": "Payment Required",
  "price": "0.01",
  "currency": "USDC"
}

What now? This SDK handles it automatically.

Installation

npm install nory-x402-payer

Quick Start

import { NoryPayer } from 'nory-x402-payer';

// Initialize with your Solana wallet
const payer = new NoryPayer({
  privateKey: process.env.SOLANA_PRIVATE_KEY!,
  maxPaymentUsd: 1.00,  // Safety limit
});

// Fetch any x402-enabled API - payments happen automatically
const result = await payer.fetch('https://noryx402.com/api/paid/live-crypto?symbols=BTC,ETH');

console.log(result.data);        // { prices: { BTC: {...}, ETH: {...} } }
console.log(result.payment);     // { success: true, transactionId: '5x...' }
console.log(result.retried);     // true (was 402, paid, and retried)

How It Works

1. You call payer.fetch(url)
2. If response is 402, SDK parses payment requirements
3. Creates USDC transfer on Solana
4. Retries original request with X-Payment header
5. Returns the successful response

All in one function call. Your agent doesn't need to understand x402 - it just works.

API

new NoryPayer(config)

Create a payer instance.

const payer = new NoryPayer({
  // Required: Your Solana private key
  privateKey: string | Uint8Array,

  // Optional: Network (default: mainnet)
  network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',

  // Optional: Custom RPC endpoint
  rpcEndpoint: 'https://api.mainnet-beta.solana.com',

  // Optional: Max payment per request in USD (default: 1.00)
  maxPaymentUsd: 1.00,

  // Optional: Auto-pay on 402 (default: true)
  autoPay: true,
});

payer.fetch(url, options)

Fetch with automatic x402 handling.

const result = await payer.fetch<ResponseType>('https://api.example.com/paid');

// result.response - The Response object
// result.data - Parsed JSON data
// result.payment - Payment details (if 402 was encountered)
// result.retried - Whether request was retried after payment

payer.pay(requirement)

Manually make a payment.

const result = await payer.pay({
  network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
  amount: '10000',  // 0.01 USDC (6 decimals)
  currency: 'USDC',
  address: 'MERCHANT_WALLET_ADDRESS',
});

payer.getBalance()

Get USDC balance.

const balance = await payer.getBalance();
console.log(`Balance: $${balance} USDC`);

payer.walletAddress

Get wallet public key.

console.log(`Wallet: ${payer.walletAddress}`);

fetchWithPayment(url, privateKey, options)

One-liner for simple use cases.

import { fetchWithPayment } from 'nory-x402-payer';

const result = await fetchWithPayment(
  'https://noryx402.com/api/paid/weather?city=London',
  process.env.SOLANA_PRIVATE_KEY!
);

Safety Features

• Max Payment Limit: Set maxPaymentUsd to prevent overspending
• Balance Check: Verifies USDC balance before attempting payment
• Auto-Pay Toggle: Disable with autoPay: false for manual control
• Network Validation: Only pays on configured network

Use with AI Frameworks

LangChain

import { NoryPayer } from 'nory-x402-payer';

const payer = new NoryPayer({ privateKey: process.env.KEY! });

// Use payer.createFetch() as custom fetch
const response = await payer.fetch('https://paid-api.com/data');

OpenAI Function Calling

const payer = new NoryPayer({ privateKey: process.env.KEY! });

async function callPaidApi(url: string) {
  const result = await payer.fetch(url);
  return result.data;
}

// Register as a tool for your agent

Networks

| Network | CAIP-2 ID | |---------|-----------| | Solana Mainnet | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp | | Solana Devnet | solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 |

Links

• Website: https://noryx402.com
• Docs: https://noryx402.com/docs
• Paywall Middleware: https://www.npmjs.com/package/nory-x402-middleware
• MCP Server: https://www.npmjs.com/package/nory-mcp-server
• x402 Protocol: https://github.com/coinbase/x402

License

MIT