npm package: @shade402/langchain
Description: LangChain.js integration for X402 payment protocol
Author: shade402
Latest version: 0.0.1

# @shade402/langchain

LangChain.js integration for X402 payment protocol. Enables AI agents built with LangChain to autonomously make payments for API access.

## Overview

The LangChain package provides a payment tool that can be integrated into LangChain agents, allowing them to automatically pay for access to X402-protected APIs. This enables autonomous AI agents to access paid APIs without manual intervention.

## Features

- LangChain tool integration for X402 payments
- Automatic payment handling in agent workflows
- Configurable payment limits for safety
- Support for all HTTP methods
- Full TypeScript support
- Seamless integration with LangChain agents

## Installation

```bash
npm install @shade402/langchain
# or
pnpm add @shade402/langchain
# or
yarn add @shade402/langchain
```

## Dependencies

- `@shade402/core`: Core X402 protocol implementation
- `@shade402/client`: X402 HTTP client
- `@solana/web3.js`: Solana wallet operations
- `@langchain/core`: LangChain core types
- `langchain`: LangChain.js framework
- `zod`: Schema validation

## Usage

### Basic Setup

```typescript
import { createX402PaymentTool } from '@shade402/langchain';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { ChatOpenAI } from '@langchain/openai';
import { Keypair } from '@solana/web3.js';

// Create wallet for agent
const wallet = Keypair.generate();

// Create payment tool
const paymentTool = createX402PaymentTool({
  walletKeypair: wallet,
  rpcUrl: 'https://api.devnet.solana.com',
  maxPayment: '1.0', // Maximum payment amount in USD
  name: 'x402_payment',
  description: 'Make a payment to access a paid API endpoint'
});

// Create agent with payment tool
const model = new ChatOpenAI({ temperature: 0 });
const tools = [paymentTool];
const agent = await createOpenAIFunctionsAgent({
  llm: model,
  tools,
  prompt: /* your prompt */
});

const executor = new AgentExecutor({
  agent,
  tools,
  verbose: true
});

// Agent can now use the payment tool
const result = await executor.invoke({
  input: 'Fetch data from https://api.example.com/premium-data'
});
```

### Advanced Configuration

```typescript
import { createX402PaymentTool } from '@shade402/langchain';
import { Keypair } from '@solana/web3.js';

const wallet = Keypair.generate();

const paymentTool = createX402PaymentTool({
  walletKeypair: wallet,
  rpcUrl: process.env.SOLANA_RPC_URL,
  maxPayment: '5.0', // Allow up to $5 per payment
  name: 'api_payment',
  description: 'Pay for API access using X402 protocol. Use this when you need to access a paid API endpoint.',
  allowLocal: false // Set to true for localhost in development
});
```

### Using the Tool Class

You can also use the class directly for more control:

```typescript
import { X402PaymentTool } from '@shade402/langchain';
import { Keypair } from '@solana/web3.js';

const wallet = Keypair.generate();

const paymentTool = new X402PaymentTool({
  walletKeypair: wallet,
  rpcUrl: 'https://api.devnet.solana.com',
  maxPayment: '1.0',
  name: 'x402_payment',
  description: 'Make X402 payment for API access'
});

// Add to agent tools
const tools = [paymentTool];
```

## API Reference

### createX402PaymentTool

Factory function to create an X402 payment tool for LangChain.

```typescript
function createX402PaymentTool(
  options: X402PaymentToolOptions
): DynamicStructuredTool
```

**Parameters:**
- `options.walletKeypair`: Solana wallet keypair for making payments
- `options.rpcUrl`: Optional Solana RPC URL (default: devnet)
- `options.maxPayment`: Maximum payment amount (default: '1.0')
- `options.name`: Tool name (default: 'x402_payment')
- `options.description`: Tool description
- `options.allowLocal`: Allow localhost URLs (default: false)

**Returns:** LangChain `DynamicStructuredTool` instance

**Tool Schema:**
- `url`: string - The API endpoint URL to access
- `method`: string (optional) - HTTP method (GET, POST, PUT, DELETE), default: 'GET'

### X402PaymentTool

Class-based implementation of the payment tool.

```typescript
class X402PaymentTool extends DynamicStructuredTool
```

**Constructor:**
```typescript
new X402PaymentTool(options: X402PaymentToolOptions)
```

**Methods:**
- `async execute(url: string, method?: string): Promise<string>` - Execute payment and fetch API

## Examples

### Simple Agent with Payment Tool

```typescript
import { createX402PaymentTool } from '@shade402/langchain';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { ChatOpenAI } from '@langchain/openai';
import { Keypair } from '@solana/web3.js';
import { ChatPromptTemplate } from '@langchain/core/prompts';

const wallet = Keypair.generate();

const paymentTool = createX402PaymentTool({
  walletKeypair: wallet,
  rpcUrl: 'https://api.devnet.solana.com',
  maxPayment: '1.0'
});

const model = new ChatOpenAI({ temperature: 0 });
const prompt = ChatPromptTemplate.fromMessages([
  ['system', 'You are a helpful assistant that can access paid APIs.'],
  ['human', '{input}']
]);

const agent = await createOpenAIFunctionsAgent({
  llm: model,
  tools: [paymentTool],
  prompt
});

const executor = new AgentExecutor({
  agent,
  tools: [paymentTool],
  verbose: true
});

const result = await executor.invoke({
  input: 'Get the latest data from https://api.example.com/data'
});
```

### Agent with Multiple Tools

```typescript
import { createX402PaymentTool } from '@shade402/langchain';
import { DynamicStructuredTool } from '@langchain/core/tools';
import { z } from 'zod';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { ChatOpenAI } from '@langchain/openai';
import { Keypair } from '@solana/web3.js';

const wallet = Keypair.generate();

// Payment tool
const paymentTool = createX402PaymentTool({
  walletKeypair: wallet,
  maxPayment: '2.0'
});

// Other tools
const searchTool = new DynamicStructuredTool({
  name: 'web_search',
  description: 'Search the web',
  schema: z.object({
    query: z.string()
  }),
  func: async ({ query }) => {
    // Your search implementation
    return 'Search results...';
  }
});

const tools = [paymentTool, searchTool];

const model = new ChatOpenAI({ temperature: 0 });
const agent = await createOpenAIFunctionsAgent({
  llm: model,
  tools,
  prompt: /* your prompt */
});

const executor = new AgentExecutor({ agent, tools });
```

### Error Handling

```typescript
import { createX402PaymentTool } from '@shade402/langchain';
import { Keypair } from '@solana/web3.js';

const wallet = Keypair.generate();

const paymentTool = createX402PaymentTool({
  walletKeypair: wallet,
  maxPayment: '1.0'
});

// Tool will return error messages as strings
// Agent should handle these in its reasoning
const result = await paymentTool.invoke({
  url: 'https://api.example.com/data',
  method: 'GET'
});

if (result.startsWith('Payment error:')) {
  console.error('Payment failed:', result);
}
```

### Production Configuration

```typescript
import { createX402PaymentTool } from '@shade402/langchain';
import { Keypair } from '@solana/web3.js';
import { readFileSync } from 'fs';

// Load wallet from secure storage
const walletKeypair = Keypair.fromSecretKey(
  Buffer.from(JSON.parse(readFileSync('wallet.json', 'utf-8')))
);

const paymentTool = createX402PaymentTool({
  walletKeypair,
  rpcUrl: process.env.SOLANA_MAINNET_RPC_URL,
  maxPayment: '10.0', // Higher limit for production
  name: 'x402_payment',
  description: 'Pay for API access. Only use when explicitly needed.',
  allowLocal: false
});
```

## Tool Behavior

The payment tool automatically:

1. Detects when a 402 Payment Required response is received
2. Parses the payment request
3. Creates and broadcasts the payment transaction
4. Retries the original request with payment authorization
5. Returns the API response data

If payment fails, the tool returns an error message that the agent can use in its reasoning.

## Integration Tips

### Prompt Engineering

Include instructions about when to use the payment tool:

```
You have access to a payment tool for accessing paid APIs. Use it only when:
1. The API explicitly requires payment
2. The payment amount is reasonable
3. You have been instructed to access the paid API
```

### Payment Limits

Set appropriate `maxPayment` limits based on your use case:
- Development: $0.10 - $1.00
- Testing: $1.00 - $5.00
- Production: Based on your budget and use case

### Wallet Management

- Store wallet keys securely (environment variables, key management service)
- Use separate wallets for different agents if needed
- Monitor wallet balances
- Set up alerts for low balances

## Security Considerations

- Never expose wallet private keys in client-side code
- Use environment variables for sensitive configuration
- Set appropriate `maxPayment` limits to prevent excessive payments
- Monitor agent behavior and payment patterns
- Use mainnet RPC endpoints for production
- Keep wallet keys secure and rotate them regularly
- Set `allowLocal: false` in production

## TypeScript Support

The package is written in TypeScript and provides full type definitions:

```typescript
import type {
  X402PaymentToolOptions
} from '@shade402/langchain';
```

## License

MIT