npm package: @mnm-ag/lp-agent-sdk
Description: TypeScript SDK for LP Agent Toolkit - AI-native liquidity provision on Solana with MPC custody and Arcium privacy
Author: MnM
Latest version: 1.0.0

# solana-lp-agent-sdk

> TypeScript SDK for LP Agent Toolkit - AI-native liquidity provision on Solana with MPC custody and Arcium privacy.

[![npm version](https://badge.fury.io/js/@mnm-ag%2Flp-agent-sdk.svg)](https://www.npmjs.com/package/solana-lp-agent-sdk)

## Features

- 🏦 **MPC Custody** - Privy server wallets with threshold signing (no private keys)
- 🔒 **Arcium Privacy** - Encrypt strategies to prevent frontrunning
- 💧 **Meteora DLMM** - Concentrated liquidity in specific price bins
- 🔄 **Jupiter Swaps** - Best-route token swaps
- 🤖 **AI-Native** - Built for autonomous agents

## Installation

```bash
npm install @mnm-ag/lp-agent-sdk
# or
yarn add @mnm-ag/lp-agent-sdk
# or
pnpm add @mnm-ag/lp-agent-sdk
```

## Quick Start

```typescript
import { LPAgent } from '@mnm-ag/lp-agent-sdk';

// Initialize the client
const agent = new LPAgent();

// Create an MPC wallet (no private keys!)
const wallet = await agent.createWallet();
console.log('Wallet address:', wallet.address);
console.log('Wallet ID:', wallet.walletId); // Save this!

// Fund your wallet by sending SOL to wallet.address

// Find SOL-USDC pools
const pools = await agent.scanPools('SOL', 'USDC');
console.log('Best pool:', pools[0].name, 'APY:', pools[0].apy);

// Add liquidity with concentrated strategy
const result = await agent.addLiquidity({
  poolAddress: pools[0].address,
  amount: 10, // SOL
  strategy: 'concentrated', // ±5 bins
});
console.log('Position:', result.positionAddress);
console.log('TX:', result.signature);
```

## API Reference

### Creating a Client

```typescript
import { LPAgent, createLPAgent } from '@mnm-ag/lp-agent-sdk';

// Using class
const agent = new LPAgent();

// Using factory function
const agent = createLPAgent();

// With custom config
const agent = new LPAgent({
  baseUrl: 'https://lp-agent-api-production.up.railway.app',
  timeout: 30000,
  walletId: 'existing-wallet-id', // Auto-load wallet
});
```

### Wallet Management

```typescript
// Create new wallet
const wallet = await agent.createWallet();

// Load existing wallet
const wallet = await agent.loadWallet('your-wallet-id');

// Get current wallet info
const walletId = agent.getWalletId();
const address = agent.getWalletAddress();

// Transfer tokens
const result = await agent.transfer(
  'recipient-address',
  1.5, // amount
  'SOL' // token (default: SOL)
);
```

### Pool Discovery

```typescript
// Scan for pools
const pools = await agent.scanPools('SOL', 'USDC');

// Pool object structure
interface Pool {
  address: string;
  name: string;
  tokenA: string;
  tokenB: string;
  liquidity: string;  // "$5.14M"
  apy: string;        // "819.02%"
  binStep: number;
  currentPrice?: number;
}
```

### Liquidity Provision

```typescript
// Add liquidity - concentrated (±5 bins)
const result = await agent.addLiquidity({
  poolAddress: 'pool-address',
  amount: 10,
  strategy: 'concentrated',
});

// Add liquidity - wide (±20 bins)
const result = await agent.addLiquidity({
  poolAddress: 'pool-address',
  amount: 10,
  strategy: 'wide',
});

// Add liquidity - custom bin range
const result = await agent.addLiquidity({
  poolAddress: 'pool-address',
  amount: 10,
  strategy: 'custom',
  minBinId: -15,
  maxBinId: 10,
});

// Add liquidity with Arcium encryption
const result = await agent.addLiquidity({
  poolAddress: 'pool-address',
  amount: 10,
  strategy: 'concentrated',
  encrypt: true, // Enable privacy
});

// Withdraw position
const result = await agent.withdrawLiquidity(
  'position-address',
  'pool-address'
);

// Get all positions
const positions = await agent.getPositions();
```

### Token Swaps

```typescript
// Get quote
const quote = await agent.getSwapQuote('USDC', 'SOL', 100);
console.log('Output:', quote.outputAmount, 'SOL');
console.log('Price impact:', quote.priceImpact);

// Execute swap
const result = await agent.swap({
  inputToken: 'USDC',
  outputToken: 'SOL',
  amount: 100,
  slippageBps: 50, // 0.5% slippage
});

// Get supported tokens
const tokens = await agent.getSupportedTokens();
```

### Encryption (Arcium)

```typescript
// Encrypt strategy data
const encrypted = await agent.encrypt({
  strategy: 'concentrated',
  amount: 1000,
  binRange: { min: -5, max: 5 },
});

// Test encryption
const status = await agent.testEncryption();
console.log('Working:', status.working);
```

### Health & Status

```typescript
// Check API health
const health = await agent.health();
console.log(health.status); // "healthy"
console.log(health.components); // { api, privy, arcium, solana_rpc }

// Get skill file (for agents)
const skillMd = await agent.getSkillFile();
```

## Error Handling

```typescript
import { 
  LPAgent, 
  LPAgentError, 
  WalletNotLoadedError, 
  ApiError 
} from 'solana-lp-agent-sdk';

try {
  const result = await agent.addLiquidity({ ... });
} catch (error) {
  if (error instanceof WalletNotLoadedError) {
    console.error('Load a wallet first!');
  } else if (error instanceof ApiError) {
    console.error('API error:', error.message, error.statusCode);
  } else if (error instanceof LPAgentError) {
    console.error('SDK error:', error.message, error.code);
  }
}
```

## TypeScript Types

All types are exported:

```typescript
import type {
  LPAgentConfig,
  Wallet,
  Pool,
  Position,
  SwapQuote,
  LPResult,
  WithdrawResult,
  SwapResult,
  EncryptResult,
  LPStrategy,
  LPExecuteOptions,
  SwapOptions,
} from 'solana-lp-agent-sdk';
```

## Security

### MPC Custody (Privy)
- Wallets use threshold signing - no single party holds the full private key
- Agents never see raw private keys
- Authorization handled by Privy's secure infrastructure

### Arcium Privacy
- Strategy parameters encrypted with x25519-aes256gcm
- MEV bots can't see your intent before execution
- Protects against frontrunning and sandwich attacks

## Links

- **API**: https://lp-agent-api-production.up.railway.app
- **Frontend**: https://mnm-web-seven.vercel.app
- **GitHub**: https://github.com/JoeStrangeQ/solana-lp-mpc-toolkit
- **Skill File**: https://lp-agent-api-production.up.railway.app/skill.md

## License

MIT

---

Built by [MnM](https://mnm.ag) 🦐 for AI agents.