@glide-pool/sdk 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# @glide-pool/sdk
+
+JavaScript SDK for the [GlidePool](https://github.com/glide-pool/glidepool) autonomous DLMM agent API on Base Mainnet.
+
+## Installation
+
+```bash
+npm install @glide-pool/sdk
+```
+
+## Quick Start
+
+```js
+import { GlidePoolClient } from '@glide-pool/sdk';
+
+const client = new GlidePoolClient({
+  apiUrl: 'https://your-glidepool-instance.replit.app',
+});
+
+// List live Maverick V2 pools
+const pools = await client.listPools();
+console.log(pools);
+// [{ poolAddress, tokenASymbol, tokenBSymbol, tvlUsd, currentPrice, feeRate, ... }]
+
+// Create an autonomous agent
+const agent = await client.createAgent({
+  userAddress: '0xYourWallet',
+  poolAddress: '0x3d70b2f31f75dc84acdd5e1588695221959b2d37',
+  strategy: 'balanced',
+  budgetUsdc: 100,
+  analysisIntervalSec: 60,
+});
+console.log(agent.id); // UUID — agent loop starts immediately on the server
+
+// Check LLM decisions
+const actions = await client.getAgentActions(agent.id);
+console.log(actions[0].actionType);    // 'hold' | 'rebalance' | 'withdraw' ...
+console.log(actions[0].llmReasoning);  // Claude Opus 4 reasoning text
+```
+
+## API Reference
+
+### Constructor
+
+```js
+const client = new GlidePoolClient({ apiUrl: 'https://...' });
+```
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `apiUrl` | `string` | ✅ | Base URL of your GlidePool API server |
+
+---
+
+### Pools
+
+#### `client.listPools()`
+Returns all supported Maverick V2 pools with live TVL, price, and fee rate from Base Mainnet.
+
+```js
+const pools = await client.listPools();
+// Pool[] — see types
+```
+
+#### `client.getPool(poolAddress)`
+Get details for a specific pool by contract address.
+
+---
+
+### Agents
+
+#### `client.createAgent(params)`
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `userAddress` | `string` | ✅ | — | Wallet address that owns the agent |
+| `poolAddress` | `string` | ✅ | — | Maverick V2 pool to monitor |
+| `strategy` | `string` | ✅ | — | `'conservative'` \| `'balanced'` \| `'aggressive'` |
+| `budgetUsdc` | `number` | ✅ | — | Max USDC budget for liquidity operations |
+| `analysisIntervalSec` | `number` | ❌ | `60` | LLM analysis frequency in seconds (min: 30) |
+
+#### `client.listAgents(userAddress)`
+List all agents for a wallet.
+
+#### `client.getAgent(agentId)`
+Get a single agent by UUID.
+
+#### `client.pauseAgent(agentId)` / `resumeAgent(agentId)` / `stopAgent(agentId)`
+Control agent lifecycle. `stop` is permanent.
+
+#### `client.getAgentActions(agentId, limit?)`
+Get LLM decisions stored in the database. Each entry has:
+- `actionType` — `hold` | `rebalance` | `withdraw` | `add_liquidity` | `switch_mode`
+- `status` — `completed` | `pending_signature` | `signed` | `failed`
+- `llmReasoning` — Full Claude Opus 4 reasoning text
+- `llmRecommendation` — Structured recommendation with `riskLevel`, `suggestedBinRange`, etc.
+- `txHash` — Set after user signs and confirms
+
+#### `client.confirmAgentAction(agentId, actionId, txHash)`
+After signing a `pending_signature` action in your wallet, submit the tx hash.
+
+---
+
+### Positions
+
+#### `client.getUserPositions(walletAddress)`
+List all Maverick V2 NFT-based LP positions for a wallet on Base Mainnet.
+
+Returns `valueUsd`, `amountA`, `amountB`, `binCount`, `nftId`, and token symbols.
+
+---
+
+### Advisor (x402 gated)
+
+#### `client.getAdvice(params)`
+
+```js
+const advice = await client.getAdvice({
+  poolAddress: '0x3d70...',
+  userGoal: 'maximize fee income with minimal impermanent loss',
+  // nftId: '123',        // optional: analyze existing position
+  // paymentProof: '...',  // required if server has X402_ENABLED=true
+});
+
+console.log(advice.recommendation.action);   // 'hold' | 'rebalance' | ...
+console.log(advice.riskLevel);               // 'low' | 'medium' | 'high'
+console.log(advice.summary);                 // Human-readable summary
+```
+
+**x402 micropayments:** If `X402_ENABLED=true` on the server, the call will throw with `status: 402` and include `recipient`, `amount`, `token`, and `network` in `err.data`. Send 0.05 USDC to `recipient` on Base, then encode the proof:
+
+```js
+const proof = Buffer.from(JSON.stringify({
+  txHash: '0x...',
+  from: '0xYourWallet',
+  amount: '0.05',
+})).toString('base64');
+
+const advice = await client.getAdvice({ poolAddress, userGoal, paymentProof: proof });
+```
+
+---
+
+### Liquidity
+
+#### `client.getRemoveParams(params)`
+Compute remove-liquidity calldata for a position. Returns `binIds`, estimated token amounts. **You sign the transaction — the server never holds your keys.**
+
+#### `client.getAddParams(params)`
+Compute add-liquidity calldata for a pool. Returns encoded calldata for the `addLiquidity` transaction.
+
+---
+
+## Strategies
+
+| Strategy | Mode | Description |
+|---|---|---|
+| `conservative` | Static | Tight fixed bin range, low risk, suited for stable pairs |
+| `balanced` | Both | Follows price in both directions, medium risk |
+| `aggressive` | Right/Left | Follows price trend, higher exposure |
+
+Claude Opus 4 analyzes pool state each cycle and may override the strategy when conditions warrant caution.
+
+## TypeScript
+
+Full TypeScript types are included:
+
+```ts
+import { GlidePoolClient, Agent, Pool, AgentAction, Advice } from '@glide-pool/sdk';
+```
+
+## Requirements
+
+- Node.js >= 18 (uses native `fetch`)
+- A running GlidePool API server
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@glide-pool/sdk",
+  "version": "0.1.0",
+  "description": "JavaScript SDK for the GlidePool autonomous DLMM agent API on Base Mainnet",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "types": "./src/index.d.ts",
+  "files": ["src", "README.md"],
+  "keywords": ["glidepool", "dlmm", "maverick", "base", "defi", "liquidity", "agent", "x402"],
+  "author": "glide-pool",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/glide-pool/glidepool"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,145 @@
+export interface Pool {
+  poolAddress: string;
+  tokenASymbol: string;
+  tokenBSymbol: string;
+  tokenAAddress: string;
+  tokenBAddress: string;
+  tvlUsd: number;
+  currentPrice: number;
+  activeTick: number;
+  feeRate: number;
+  tickSpacing: number;
+}
+
+export interface CreateAgentParams {
+  userAddress: string;
+  poolAddress: string;
+  strategy: 'conservative' | 'balanced' | 'aggressive';
+  budgetUsdc: number;
+  analysisIntervalSec?: number;
+}
+
+export interface Agent {
+  id: string;
+  userAddress: string;
+  poolAddress: string;
+  strategy: string;
+  budgetUsdc: string;
+  status: 'active' | 'paused' | 'stopped';
+  lastAnalysisAt: string | null;
+  createdAt: string;
+}
+
+export interface AgentAction {
+  id: string;
+  agentId: string;
+  actionType: 'hold' | 'rebalance' | 'withdraw' | 'add_liquidity' | 'switch_mode';
+  status: 'pending_signature' | 'completed' | 'signed' | 'failed';
+  llmReasoning: string | null;
+  llmRecommendation: Record<string, unknown> | null;
+  txHash: string | null;
+  createdAt: string;
+}
+
+export interface Position {
+  nftId: string;
+  poolAddress: string;
+  tokenASymbol: string;
+  tokenBSymbol: string;
+  valueUsd: number;
+  amountA: string;
+  amountB: string;
+  binCount: number;
+}
+
+export interface BinRange {
+  lowerTick: number;
+  upperTick: number;
+}
+
+export interface Recommendation {
+  action: 'hold' | 'rebalance' | 'withdraw' | 'add_liquidity' | 'switch_mode';
+  reasoning: string;
+  suggestedMode?: string;
+  suggestedBinRange?: BinRange;
+  suggestedWithdrawPercent?: number;
+}
+
+export interface Advice {
+  summary: string;
+  riskLevel: 'low' | 'medium' | 'high';
+  recommendation: Recommendation;
+}
+
+export interface AdvisorParams {
+  poolAddress: string;
+  userGoal: string;
+  nftId?: string;
+  paymentProof?: string;
+}
+
+export interface RemoveLiquidityParams {
+  nftId: string;
+  userAddress: string;
+  poolAddress: string;
+  withdrawPercent: number;
+}
+
+export interface RemoveLiquidityResult {
+  poolAddress: string;
+  nftId: string;
+  binIds: number[];
+  amounts: string[];
+  estimatedTokenA: string;
+  estimatedTokenB: string;
+}
+
+export interface AddLiquidityParams {
+  poolAddress: string;
+  userAddress: string;
+  amountADesired: number;
+  amountBDesired: number;
+  mode: 'static' | 'both' | 'right' | 'left';
+  lowerTick?: number;
+  upperTick?: number;
+}
+
+export interface AddLiquidityResult {
+  poolAddress: string;
+  calldata: string;
+  estimatedTokenA: string;
+  estimatedTokenB: string;
+}
+
+export interface GlidePoolClientOptions {
+  apiUrl: string;
+}
+
+export class GlidePoolClient {
+  constructor(options: GlidePoolClientOptions);
+
+  // Pools
+  listPools(): Promise<Pool[]>;
+  getPool(poolAddress: string): Promise<Pool>;
+
+  // Agents
+  createAgent(params: CreateAgentParams): Promise<Agent>;
+  listAgents(userAddress: string): Promise<Agent[]>;
+  getAgent(agentId: string): Promise<Agent>;
+  updateAgentStatus(agentId: string, status: 'active' | 'paused' | 'stopped'): Promise<Agent>;
+  pauseAgent(agentId: string): Promise<Agent>;
+  resumeAgent(agentId: string): Promise<Agent>;
+  stopAgent(agentId: string): Promise<Agent>;
+  getAgentActions(agentId: string, limit?: number): Promise<AgentAction[]>;
+  confirmAgentAction(agentId: string, actionId: string, txHash: string): Promise<void>;
+
+  // Positions
+  getUserPositions(walletAddress: string): Promise<Position[]>;
+
+  // Advisor
+  getAdvice(params: AdvisorParams): Promise<Advice>;
+
+  // Liquidity
+  getRemoveParams(params: RemoveLiquidityParams): Promise<RemoveLiquidityResult>;
+  getAddParams(params: AddLiquidityParams): Promise<AddLiquidityResult>;
+}

package/src/index.js

@@ -0,0 +1,329 @@
+/**
+ * @glide-pool/sdk
+ * JavaScript SDK for the GlidePool autonomous DLMM agent API on Base Mainnet.
+ *
+ * @example
+ * import { GlidePoolClient } from '@glide-pool/sdk';
+ * const client = new GlidePoolClient({ apiUrl: 'https://your-glidepool-instance.com' });
+ * const pools = await client.listPools();
+ */
+
+export class GlidePoolClient {
+  /**
+   * @param {object} options
+   * @param {string} options.apiUrl - Base URL of your GlidePool API server (no trailing slash)
+   */
+  constructor({ apiUrl } = {}) {
+    if (!apiUrl) throw new Error('GlidePoolClient requires { apiUrl } — e.g. https://your-glidepool.replit.app');
+    this.apiUrl = apiUrl.replace(/\/$/, '');
+  }
+
+  /**
+   * Internal fetch helper. Throws on non-2xx responses.
+   * @private
+   */
+  async _fetch(path, options = {}) {
+    const url = `${this.apiUrl}${path}`;
+    const res = await fetch(url, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      const err = new Error(data.message || data.error || `HTTP ${res.status}`);
+      err.status = res.status;
+      err.data = data;
+      throw err;
+    }
+    return data;
+  }
+
+  // ─────────────────────────────────────────
+  // POOLS
+  // ─────────────────────────────────────────
+
+  /**
+   * List all supported Maverick V2 pools with live TVL, price, and fee rate.
+   * @returns {Promise<Pool[]>}
+   */
+  listPools() {
+    return this._fetch('/api/pools');
+  }
+
+  /**
+   * Get details for a specific pool by address.
+   * @param {string} poolAddress - Maverick V2 pool contract address (0x...)
+   * @returns {Promise<Pool>}
+   */
+  getPool(poolAddress) {
+    return this._fetch(`/api/pools/${poolAddress}`);
+  }
+
+  // ─────────────────────────────────────────
+  // AGENTS
+  // ─────────────────────────────────────────
+
+  /**
+   * Create a new autonomous agent for a given wallet + pool.
+   * The agent loop starts immediately on the server — no additional setup needed.
+   *
+   * @param {CreateAgentParams} params
+   * @returns {Promise<Agent>}
+   *
+   * @example
+   * const agent = await client.createAgent({
+   *   userAddress: '0xYourWallet',
+   *   poolAddress: '0x3d70b2f31f75dc84acdd5e1588695221959b2d37',
+   *   strategy: 'balanced',
+   *   budgetUsdc: 100,
+   *   analysisIntervalSec: 60,
+   * });
+   */
+  createAgent(params) {
+    return this._fetch('/api/agents', {
+      method: 'POST',
+      body: JSON.stringify(params),
+    });
+  }
+
+  /**
+   * List all agents for a wallet address.
+   * @param {string} userAddress - Wallet address (0x...)
+   * @returns {Promise<Agent[]>}
+   */
+  listAgents(userAddress) {
+    return this._fetch(`/api/agents?userAddress=${encodeURIComponent(userAddress)}`);
+  }
+
+  /**
+   * Get a single agent by ID, including recent actions.
+   * @param {string} agentId - UUID of the agent
+   * @returns {Promise<Agent>}
+   */
+  getAgent(agentId) {
+    return this._fetch(`/api/agents/${agentId}`);
+  }
+
+  /**
+   * Update agent status.
+   * @param {string} agentId
+   * @param {'active'|'paused'|'stopped'} status
+   * @returns {Promise<Agent>}
+   */
+  updateAgentStatus(agentId, status) {
+    return this._fetch(`/api/agents/${agentId}/status`, {
+      method: 'PUT',
+      body: JSON.stringify({ status }),
+    });
+  }
+
+  /**
+   * Pause a running agent. Analysis loop stops until resumed.
+   * @param {string} agentId
+   */
+  pauseAgent(agentId) { return this.updateAgentStatus(agentId, 'paused'); }
+
+  /**
+   * Resume a paused agent.
+   * @param {string} agentId
+   */
+  resumeAgent(agentId) { return this.updateAgentStatus(agentId, 'active'); }
+
+  /**
+   * Stop an agent permanently.
+   * @param {string} agentId
+   */
+  stopAgent(agentId) { return this.updateAgentStatus(agentId, 'stopped'); }
+
+  /**
+   * Get LLM decisions (actions) for an agent.
+   * @param {string} agentId
+   * @param {number} [limit=20]
+   * @returns {Promise<AgentAction[]>}
+   */
+  getAgentActions(agentId, limit = 20) {
+    return this._fetch(`/api/agents/${agentId}/actions?limit=${limit}`);
+  }
+
+  /**
+   * Confirm an on-chain action was signed and executed.
+   * @param {string} agentId
+   * @param {string} actionId
+   * @param {string} txHash - Transaction hash (0x...)
+   */
+  confirmAgentAction(agentId, actionId, txHash) {
+    return this._fetch(`/api/agents/${agentId}/actions/${actionId}/confirm`, {
+      method: 'POST',
+      body: JSON.stringify({ txHash }),
+    });
+  }
+
+  // ─────────────────────────────────────────
+  // POSITIONS
+  // ─────────────────────────────────────────
+
+  /**
+   * Get all Maverick V2 LP positions for a wallet on Base Mainnet.
+   * @param {string} walletAddress
+   * @returns {Promise<Position[]>}
+   */
+  getUserPositions(walletAddress) {
+    return this._fetch(`/api/positions/${walletAddress}`);
+  }
+
+  // ─────────────────────────────────────────
+  // ADVISOR (x402 gated)
+  // ─────────────────────────────────────────
+
+  /**
+   * Get a Claude Opus 4 recommendation for a pool + optional existing position.
+   * If x402 is enabled on the server, you must provide a valid paymentProof header.
+   * Otherwise, queries run freely.
+   *
+   * @param {AdvisorParams} params
+   * @returns {Promise<Advice>}
+   *
+   * @example
+   * const advice = await client.getAdvice({
+   *   poolAddress: '0x3d70...',
+   *   userGoal: 'maximize fee income with low IL risk',
+   * });
+   */
+  getAdvice({ poolAddress, nftId, userGoal, paymentProof } = {}) {
+    const qs = new URLSearchParams({ poolAddress, userGoal });
+    if (nftId) qs.set('nftId', nftId);
+    const headers = {};
+    if (paymentProof) headers['x-payment-proof'] = paymentProof;
+    return this._fetch(`/api/advisor?${qs}`, { headers });
+  }
+
+  // ─────────────────────────────────────────
+  // LIQUIDITY
+  // ─────────────────────────────────────────
+
+  /**
+   * Compute remove-liquidity calldata for a position.
+   * Returns estimated token amounts and bin IDs. You sign the transaction in your wallet.
+   * @param {RemoveLiquidityParams} params
+   * @returns {Promise<RemoveLiquidityResult>}
+   */
+  getRemoveParams(params) {
+    return this._fetch('/api/liquidity/remove-params', {
+      method: 'POST',
+      body: JSON.stringify(params),
+    });
+  }
+
+  /**
+   * Compute add-liquidity calldata for a pool.
+   * Returns encoded calldata for the addLiquidity transaction. You sign in your wallet.
+   * @param {AddLiquidityParams} params
+   * @returns {Promise<AddLiquidityResult>}
+   */
+  getAddParams(params) {
+    return this._fetch('/api/liquidity/add-params', {
+      method: 'POST',
+      body: JSON.stringify(params),
+    });
+  }
+}
+
+/**
+ * @typedef {object} Pool
+ * @property {string} poolAddress
+ * @property {string} tokenASymbol
+ * @property {string} tokenBSymbol
+ * @property {string} tokenAAddress
+ * @property {string} tokenBAddress
+ * @property {number} tvlUsd
+ * @property {number} currentPrice
+ * @property {number} activeTick
+ * @property {number} feeRate
+ * @property {number} tickSpacing
+ */
+
+/**
+ * @typedef {object} CreateAgentParams
+ * @property {string} userAddress - Wallet address that owns this agent
+ * @property {string} poolAddress - Maverick V2 pool address to monitor
+ * @property {'conservative'|'balanced'|'aggressive'} strategy
+ * @property {number} budgetUsdc - Max USDC budget for liquidity operations
+ * @property {number} [analysisIntervalSec=60] - How often to run LLM analysis (min: 30s)
+ */
+
+/**
+ * @typedef {object} Agent
+ * @property {string} id
+ * @property {string} userAddress
+ * @property {string} poolAddress
+ * @property {string} strategy
+ * @property {string} budgetUsdc
+ * @property {'active'|'paused'|'stopped'} status
+ * @property {string|null} lastAnalysisAt
+ * @property {string} createdAt
+ */
+
+/**
+ * @typedef {object} AgentAction
+ * @property {string} id
+ * @property {string} agentId
+ * @property {'hold'|'rebalance'|'withdraw'|'add_liquidity'|'switch_mode'} actionType
+ * @property {'pending_signature'|'completed'|'signed'|'failed'} status
+ * @property {string|null} llmReasoning
+ * @property {object|null} llmRecommendation
+ * @property {string|null} txHash
+ * @property {string} createdAt
+ */
+
+/**
+ * @typedef {object} Position
+ * @property {string} nftId
+ * @property {string} poolAddress
+ * @property {string} tokenASymbol
+ * @property {string} tokenBSymbol
+ * @property {number} valueUsd
+ * @property {string} amountA
+ * @property {string} amountB
+ * @property {number} binCount
+ */
+
+/**
+ * @typedef {object} AdvisorParams
+ * @property {string} poolAddress
+ * @property {string} userGoal
+ * @property {string} [nftId]
+ * @property {string} [paymentProof] - base64(JSON{txHash,from,amount}) for x402
+ */
+
+/**
+ * @typedef {object} Advice
+ * @property {string} summary
+ * @property {'low'|'medium'|'high'} riskLevel
+ * @property {object} recommendation
+ * @property {'hold'|'rebalance'|'withdraw'|'add_liquidity'|'switch_mode'} recommendation.action
+ * @property {string} recommendation.reasoning
+ * @property {object} [recommendation.suggestedBinRange]
+ * @property {number} [recommendation.suggestedWithdrawPercent]
+ */
+
+/**
+ * @typedef {object} RemoveLiquidityParams
+ * @property {string} nftId
+ * @property {string} userAddress
+ * @property {string} poolAddress
+ * @property {number} withdrawPercent - 0–100
+ */
+
+/**
+ * @typedef {object} AddLiquidityParams
+ * @property {string} poolAddress
+ * @property {string} userAddress
+ * @property {number} amountADesired
+ * @property {number} amountBDesired
+ * @property {'static'|'both'|'right'|'left'} mode
+ * @property {number} [lowerTick]
+ * @property {number} [upperTick]
+ */