mantle-agent-kit-sdk 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,6 @@
 # Mantle Agent Kit SDK
 
-TypeScript SDK for seamless integration with DeFi protocols on Mantle Network. Provides unified interfaces for swaps, lending, liquid staking, and cross-chain operations.
+TypeScript SDK for seamless integration with DeFi protocols on Mantle Network. Provides unified interfaces for swaps, lending, liquid staking, perpetual trading, and cross-chain operations.
 
 Part of [Mantle DevKit](https://mantle-devkit.vercel.app) - the complete developer suite for Mantle.
 
@@ -32,31 +32,23 @@ const txHash = await agent.sendTransaction(
 
 ## Supported Protocols
 
-### DEX Aggregators
-- **OKX DEX Aggregator** - Multi-source liquidity aggregation with HMAC authentication
-- **1inch** - Pathfinder algorithm for optimal swap routes (optional API key)
-- **OpenOcean** - Cross-DEX aggregation for best execution prices
-
-### Native Mantle DEXs
-- **Agni Finance** - Leading DEX on Mantle with concentrated liquidity (Uniswap V3 architecture)
-- **Merchant Moe** - Liquidity Book DEX with dynamic fee tiers (TraderJoe V2.1 architecture)
-- **Uniswap V3** - Direct integration with canonical Uniswap V3 contracts
-
-### Lending Protocols
-- **Lendle** - Mantle's primary lending market with supply, borrow, and collateralization (Aave V2 architecture)
-
-### Liquid Staking
-- **mETH Protocol** - Mantle's native liquid staking derivative for Ethereum
-
-### Cross-Chain Infrastructure
-- **Squid Router** - Seamless cross-chain swaps via Axelar network
+| Protocol | Network | Description |
+|----------|---------|-------------|
+| **OKX DEX** | Mainnet | Multi-source liquidity aggregation |
+| **1inch** | Mainnet | Pathfinder algorithm for optimal routes |
+| **OpenOcean** | Mainnet | Cross-DEX aggregation |
+| **Agni Finance** | Mainnet | Concentrated liquidity DEX (Uniswap V3) |
+| **Merchant Moe** | Mainnet | Liquidity Book DEX (TraderJoe V2.1) |
+| **Uniswap V3** | Mainnet | Canonical Uniswap V3 contracts |
+| **Lendle** | Mainnet | Lending market (Aave V2 fork) |
+| **mETH Protocol** | Mainnet | Liquid staking token |
+| **PikePerps** | Testnet | Perpetual futures trading (up to 100x) |
+| **Squid Router** | Mainnet | Cross-chain swaps via Axelar |
 
 ## API Reference
 
 ### Token Transfers
 
-Send native MNT tokens to any address.
-
 ```typescript
 await agent.sendTransaction(
   recipientAddress: Address,
@@ -64,6 +56,8 @@ await agent.sendTransaction(
 ): Promise<Address>
 ```
 
+---
+
 ### DEX Operations
 
 #### OKX DEX Aggregator
@@ -160,12 +154,12 @@ const txHash = await agent.merchantMoeSwap(
 );
 ```
 
+---
+
 ### Lendle Lending Protocol
 
 #### Supply Assets
 
-Deposit tokens to earn yield and use as collateral.
-
 ```typescript
 const txHash = await agent.lendleSupply(
   tokenAddress: Address,
@@ -175,8 +169,6 @@ const txHash = await agent.lendleSupply(
 
 #### Withdraw Assets
 
-Withdraw previously supplied tokens.
-
 ```typescript
 const txHash = await agent.lendleWithdraw(
   tokenAddress: Address,
@@ -187,46 +179,158 @@ const txHash = await agent.lendleWithdraw(
 
 #### Borrow Assets
 
-Borrow against supplied collateral.
-
 ```typescript
 const txHash = await agent.lendleBorrow(
   tokenAddress: Address,
   amount: string,
   interestRateMode?: 1 | 2, // 1 = stable, 2 = variable (default)
-  onBehalfOf?: Address // optional
+  onBehalfOf?: Address
 );
 ```
 
 #### Repay Debt
 
-Repay borrowed assets.
-
 ```typescript
 const txHash = await agent.lendleRepay(
   tokenAddress: Address,
   amount: string,
   rateMode?: 1 | 2, // 1 = stable, 2 = variable (default)
-  onBehalfOf?: Address // optional
+  onBehalfOf?: Address
+);
+```
+
+#### View Account Data
+
+```typescript
+const accountData = await agent.lendleGetUserAccountData(
+  userAddress?: Address // optional, defaults to agent account
+);
+// Returns: {
+//   totalCollateralETH: bigint,
+//   totalDebtETH: bigint,
+//   availableBorrowsETH: bigint,
+//   currentLiquidationThreshold: bigint,
+//   ltv: bigint,
+//   healthFactor: bigint
+// }
+```
+
+#### View All Positions
+
+```typescript
+const positions = await agent.lendleGetPositions(
+  userAddress?: Address // optional, defaults to agent account
 );
+// Returns: {
+//   positions: LendlePosition[],
+//   totalSupplied: bigint,
+//   totalDebt: bigint
+// }
 ```
 
-### mETH Protocol
+---
 
-Access Mantle's liquid staking token address.
+### mETH Protocol (Liquid Staking)
 
 ```typescript
+// Get mETH token address
 const methAddress = agent.getMethTokenAddress();
 // Returns: 0xcDA86A272531e8640cD7F1a92c01839911B90bb0 (mainnet)
+
+// View mETH position (balances)
+const position = await agent.methGetPosition(
+  userAddress?: Address // optional, defaults to agent account
+);
+// Returns: {
+//   methBalance: bigint,
+//   wethBalance: bigint,
+//   wmntBalance: bigint,
+//   methTokenAddress: Address,
+//   wethTokenAddress: Address,
+//   wmntTokenAddress: Address
+// }
+
+// Swap WETH to mETH via DEX
+const txHash = await agent.swapToMeth(
+  amount: string, // WETH amount in wei
+  slippage?: number // default: 0.5
+);
+
+// Swap mETH to WETH via DEX
+const txHash = await agent.swapFromMeth(
+  amount: string, // mETH amount in wei
+  slippage?: number // default: 0.5
+);
 ```
 
-Note: To stake ETH for mETH, use the [official mETH interface](https://www.mantle-meth.xyz/).
+> **Note**: Actual ETH staking happens on Ethereum L1. On Mantle L2, you can swap to/from mETH via DEX or use it in DeFi protocols. To stake ETH for mETH on L1, use the [official mETH interface](https://www.mantle-meth.xyz/).
+
+---
+
+### PikePerps - Perpetual Trading
 
-### Cross-Chain Operations
+Trade perpetual futures with up to 100x leverage on meme tokens.
 
-#### Squid Router
+> **Network**: Mantle Sepolia Testnet only
 
-Execute cross-chain swaps via Axelar network.
+#### Open Long Position
+
+```typescript
+const result = await agent.pikeperpsOpenLong(
+  tokenAddress: Address, // Meme token to trade
+  margin: string,        // Margin in wei
+  leverage?: number      // 1-100, default: 10
+);
+// Returns: { positionId: bigint, txHash: Hex }
+```
+
+#### Open Short Position
+
+```typescript
+const result = await agent.pikeperpsOpenShort(
+  tokenAddress: Address,
+  margin: string,
+  leverage?: number // 1-100, default: 10
+);
+// Returns: { positionId: bigint, txHash: Hex }
+```
+
+#### Close Position
+
+```typescript
+const txHash = await agent.pikeperpsClosePosition(
+  positionId: bigint
+);
+```
+
+#### View Positions
+
+```typescript
+const positions = await agent.pikeperpsGetPositions(
+  userAddress?: Address // optional, defaults to agent account
+);
+// Returns: PikePerpsPosition[] with:
+//   positionId, token, isLong, size, margin, leverage,
+//   entryPrice, currentPrice, pnl, isProfit,
+//   liquidationPrice, isOpen
+```
+
+#### Get Market Data
+
+```typescript
+const marketData = await agent.pikeperpsGetMarketData(
+  tokenAddress: Address,
+  limit?: number // default: 20
+);
+// Returns: {
+//   token, currentPrice, hasPrice, isListed, curveProgress,
+//   recentTrades: PikePerpsTrade[]
+// }
+```
+
+---
+
+### Cross-Chain Operations (Squid Router)
 
 ```typescript
 // Get cross-chain route
@@ -250,14 +354,14 @@ const txHash = await agent.crossChainSwapViaSquid(
 );
 ```
 
+---
+
 ## Configuration
 
 ### Environment Variables
 
 #### Platform Configuration (Required)
 
-The Mantle Agent Kit requires an APP_ID for platform validation and authentication.
-
 ```env
 APP_ID=your_app_id_here
 
@@ -265,10 +369,6 @@ APP_ID=your_app_id_here
 PLATFORM_URL=https://mantle-devkit.vercel.app
 ```
 
-**What is APP_ID?**
-
-APP_ID is a unique identifier that authenticates your application and validates access to the Mantle Agent Kit. When you call `agent.initialize()`, it validates your APP_ID with the platform API and returns your project configuration (name, payout address, network, status).
-
 #### OKX DEX (Required for OKX methods)
 
 ```env
@@ -286,49 +386,60 @@ ONEINCH_API_KEY=your_api_key
 
 ### Network Configuration
 
-The SDK supports both Mantle mainnet and testnet:
-
-- **Mainnet**: Chain ID 5000
-- **Testnet**: Chain ID 5003 (Sepolia)
+| Network | Chain ID | Usage |
+|---------|----------|-------|
+| Mainnet | 5000 | Production (DEX, Lendle, mETH) |
+| Testnet (Sepolia) | 5003 | Development, PikePerps |
 
 ```typescript
 const mainnetAgent = new MNTAgentKit(privateKey, "mainnet");
 const testnetAgent = new MNTAgentKit(privateKey, "testnet");
 ```
 
-## Contract Addresses
+### Demo/Simulation Mode
+
+```typescript
+// Initialize agent in demo mode
+const demoAgent = new MNTAgentKit(privateKey, "testnet-demo");
+
+// All operations return mock responses
+const result = await demoAgent.swapOnUniswap(tokenA, tokenB, amount);
+// Returns: { txHash: "0xdemo...", demo: true, message: "..." }
+```
 
-All protocol contract addresses are pre-configured for Mantle Mainnet:
+---
+
+## Contract Addresses
 
-**Lendle Protocol**
-- LendingPool: `0xCFa5aE7c2CE8Fadc6426C1ff872cA45378Fb7cF3`
-- DataProvider: `0xD0E0b5e99c8a36f4c5234cd1E90CFc5C2Bb58A69`
+### Mainnet (Chain ID: 5000)
 
-**Agni Finance**
-- Factory: `0x25780dc8Fc3cfBD75F33bFDAB65e969b603b2035`
-- SwapRouter: `0x319B69888b0d11cEC22caA5034e25FfFBDc88421`
-- NonfungiblePositionManager: `0x9C9e335A3BC0EF6F66F44390c383D0bB7a0A34f0`
+| Protocol | Contract | Address |
+|----------|----------|---------|
+| **mETH** | Token | `0xcDA86A272531e8640cD7F1a92c01839911B90bb0` |
+| **WETH** | Token | `0xdEAddEaDdeadDEadDEADDEAddEADDEAddead1111` |
+| **WMNT** | Token | `0x78c1b0C915c4FAA5FffA6CAbf0219DA63d7f4cb8` |
+| **Lendle** | LendingPool | `0xCFa5aE7c2CE8Fadc6426C1ff872cA45378Fb7cF3` |
+| **Lendle** | DataProvider | `0x552b9e4bae485C4B7F540777d7D25614CdB84773` |
+| **Agni** | Factory | `0x25780dc8Fc3cfBD75F33bFDAB65e969b603b2035` |
+| **Agni** | SwapRouter | `0x319B69888b0d11cEC22caA5034e25FfFBDc88421` |
+| **Merchant Moe** | LBRouter | `0x013e138EF6008ae5FDFDE29700e3f2Bc61d21E3a` |
+| **Uniswap V3** | SwapRouter | `0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45` |
 
-**Merchant Moe**
-- LBRouter: `0x013e138EF6008ae5FDFDE29700e3f2Bc61d21E3a`
-- LBFactory: `0xa6630671775c4EA2743840F9A5016dCf2A104054`
-- LBQuoter: `0xFa1ec885c522Ee2c06aFCfBC66E88a88ca09EEED`
+### Testnet (Chain ID: 5003)
 
-**mETH Protocol**
-- mETH Token: `0xcDA86A272531e8640cD7F1a92c01839911B90bb0`
+| Protocol | Contract | Address |
+|----------|----------|---------|
+| **PikePerps** | PerpetualTrading | `0x8081b646f349c049f2d5e8a400057d411dd657bd` |
+| **PikePerps** | BondingCurveMarket | `0x93b268325A9862645c82b32229f3B52264750Ca2` |
 
-**Uniswap V3**
-- SwapRouter: `0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45`
-- QuoterV2: `0x61fFE014bA17989E743c5F6cB21bF9697530B21e`
+Verify addresses on [Mantlescan](https://mantlescan.xyz).
 
-Verify current addresses on [Mantlescan](https://mantlescan.xyz).
+---
 
 ## Advanced Usage
 
 ### Accessing Protocol Constants
 
-Import protocol-specific constants for advanced integrations:
-
 ```typescript
 import {
   AgniConstants,
@@ -336,26 +447,37 @@ import {
   MerchantMoeConstants,
   MethConstants,
   UniswapConstants,
+  PikePerpsConstants,
 } from "mantle-agent-kit-sdk";
 
 // Example: Get Lendle pool address
 const poolAddress = LendleConstants.LENDING_POOL.mainnet;
+
+// Example: Get PikePerps contract
+const perpsAddress = PikePerpsConstants.PERPETUAL_TRADING.testnet;
+
+// Example: Get mETH/WETH/WMNT addresses
+const methToken = MethConstants.METH_TOKEN.mainnet;
+const wethToken = MethConstants.WETH_TOKEN.mainnet;
+const wmntToken = MethConstants.WMNT_TOKEN.mainnet;
 ```
 
 ### Type Definitions
 
-Import utility types for type-safe development:
-
 ```typescript
-import type { UserAccountData, ProjectConfig } from "mantle-agent-kit-sdk";
-
-// UserAccountData returned from Lendle user queries
-// ProjectConfig returned from platform validation
+import type {
+  UserAccountData,
+  ProjectConfig,
+  LendlePosition,
+  LendlePositionsResult,
+  MethPosition,
+  PikePerpsPosition,
+  PikePerpsMarketData,
+  PikePerpsTrade,
+} from "mantle-agent-kit-sdk";
 ```
 
-### Accessing Project Configuration
-
-After initializing the agent, you can access the validated project configuration:
+### Project Configuration
 
 ```typescript
 const agent = new MNTAgentKit(privateKey, "mainnet");
@@ -368,6 +490,8 @@ console.log("Network:", agent.projectConfig?.network);
 console.log("Status:", agent.projectConfig?.status);
 ```
 
+---
+
 ## Development
 
 ### Build from Source
@@ -393,6 +517,8 @@ dist/
 └── *.map             # Source maps
 ```
 
+---
+
 ## License
 
 MIT