npm package: @lnfi-network/lnex-sdk
Description: LN Exchange SDK for spot and perpetual trading
Latest version: 0.1.0

# LnexSdk

A JavaScript SDK for interacting with Lnex Exchange API, supporting both spot and perpetual trading.

## Installation

```bash
npm install @lnfi-network/lnex-sdk
```

---

## Quick Start

### Browser Environment

**Use Case:** Web applications where users trade through their browser wallets

**Features:**
- Wallet integration is optional - automatically connects to installed crypto wallets
- Supports popular wallet extensions (OKX, TokenPocket, Alby, etc.)
- Uses browser-compatible HTTP client

```javascript
import { LnexSdk } from '@lnfi-network/lnex-sdk';

// Basic initialization (all parameters optional)
const lnex = new LnexSdk();

// Get available trading pairs and market information
const spotPublicInfo = await lnex.spot.getPublicInfo();
const perpPublicInfo = await lnex.perp.getPublicInfo();

```

### Node.js Environment

**Use Case:** Server applications, trading bots, or backend services

**Features:**
- Private key authentication is required for security
- Uses LnfiNostr for Nostr protocol implementation
- Supports automated trading and server-side applications

```javascript
import { LnexSdk, LnfiNostr } from '@lnfi-network/lnex-sdk';

// Create signer (required)
const signer = new LnfiNostr({
  privateKey: 'nsec1...' // or hex string
});

// Basic initialization
const lnex = new LnexSdk({ signer });

// Get available trading pairs and market information
const spotPublicInfo = await lnex.spot.getPublicInfo();
const perpPublicInfo = await lnex.perp.getPublicInfo();

```

---

## API Reference

### LnexSdk Class

#### Constructor Options

- `env` (string, optional): Environment setting (default: 'production')
  - 'development': Development environment
  - 'production': Production environment

- `signer` (object, optional): Nostr signer instance
  - Browser: Automatically reads from wallet extensions if not provided
  - Node.js: Must provide LnfiNostr instance
  - When no signer is provided, the SDK will automatically select in this priority:
    1. 'window.lnfi.nostr'
    2. 'window.okxwallet.nostr'
    3. 'window.tokenpocket.nostr'
    4. 'window.alby.nostr'
    5. 'window.nostr'

- `spotBaseURL` (string, optional): Custom spot trading API base URL
  - Default: 'https://test-spots-api.ln.exchange'

- `perpBaseURL` (string, optional): Custom perpetual trading API base URL
  - Default: 'https://test-futures-api.ln.exchange'

- `relay` (string|string[], optional): Custom Nostr relay URL(s)
  - Accepts single relay URL string or array of relay URLs
  - Default: Uses lnfi-sdk's built-in relay configuration based on environment
  - Production: Uses production relay endpoints from lnfi-sdk
  - Development: Uses development relay endpoints from lnfi-sdk

#### Configuration Examples

**Custom Configuration:**
```javascript
// Browser environment with custom settings
const lnex = new LnexSdk({
  env: 'development',
  spotBaseURL: 'https://custom-spot-api.example.com',
  perpBaseURL: 'https://custom-perp-api.example.com',
  relay: 'wss://custom-relay.example.com'
});

// Node.js environment with custom settings
import { LnexSdk, LnfiNostr } from '@lnfi-network/lnex-sdk';

const signer = new LnfiNostr({ privateKey: 'nsec1...' });
const lnex = new LnexSdk({
  signer,
  env: 'development',
  spotBaseURL: 'https://custom-spot-api.example.com',
  perpBaseURL: 'https://custom-perp-api.example.com',
  relay: 'wss://custom-relay.example.com'
});
```

#### Signer Configuration & LnfiNostr Class

The SDK supports multiple signing methods through the `signer` parameter. You can use browser Nostr extensions directly or create custom signers using the `LnfiNostr` class.

##### Browser Environment (Auto-detection)
```javascript
// SDK automatically detects available Nostr providers in this order:
// 1. window.lnfi.nostr → 2. window.okxwallet.nostr → 3. window.tokenpocket.nostr
// 4. window.alby.nostr → 5. window.nostr
const lnex = new LnexSdk();

// Or specify a particular provider
const lnex = new LnexSdk({ signer: window.nostr });
```

##### LnfiNostr Class for Custom Signing

The `LnfiNostr` class provides flexible signing options for different wallet types:

**1. Using Private Key**
```javascript
import { LnexSdk, LnfiNostr } from '@lnfi-network/lnex-sdk';

const signer = new LnfiNostr({ 
  privateKey: 'nsec1...' // or hex format private key
});

const lnex = new LnexSdk({ signer });
```

**2. Using EVM Wallet (MetaMask, etc.)**
```javascript
// Using default window.ethereum
const signer = new LnfiNostr({ evm: true });

// Using custom provider (viem/wagmi walletClient)
const signer = new LnfiNostr({ evm: walletClient });

// Using ethers provider
const provider = new ethers.BrowserProvider(window.ethereum).provider;
const signer = new LnfiNostr({ evm: provider });

const lnex = new LnexSdk({ signer });
```

**3. Using BTC Wallet (Unisat, etc.)**
```javascript
// Using default window.unisat
const signer = new LnfiNostr({ btc: true });

// Using custom BTC provider
const signer = new LnfiNostr({ btc: customBtcProvider });

const lnex = new LnexSdk({ signer });
```

**Note:** If no signer is provided and no browser Nostr extensions are available, the SDK will throw an error: "Nostr provider not available"

For more detailed LnfiNostr usage, refer to the [lnfi-sdk documentation](https://www.npmjs.com/package/@lnfi-network/lnfi-sdk).

#### Core Methods

- **spot**: Getter property that returns SpotApi instance for spot trading
- **perp**: Getter property that returns PerpApi instance for perpetual trading

#### `getPublicKey()`
Retrieve the public key for the current account.

**Returns:** `Promise<Object>` - Object containing public key in raw hex and npub format

```javascript
const publicKey = await lnex.getPublicKey();
console.log(publicKey);
```

---

## SpotApi Methods

### User Management

#### `createUser(referrals?)`
Registers a user for trading.

**Parameters:**
- `referrals` (string, optional): Referral ID for user registration (default: "")

**Returns:** `Promise<Object>` - Response from the API containing user registration result

**Example:**
```javascript
const result = await lnex.spot.createUser("referral123");
```

#### `enableTrade(symbolName)`
Enables trading for a specific symbol.

**Parameters:**
- `symbolName` (string, required): The name of the symbol to enable trading for

**Returns:** `Promise<Object>` - Response data of the enable trade request

**Example:**
```javascript
const result = await lnex.spot.enableTrade("BTC-USDT");
```

#### `getUserInfo()`
Fetches user information.

**Returns:** `Promise<Object>` - User information data

**Example:**
```javascript
const userInfo = await lnex.spot.getUserInfo();
```

### Asset Management

#### `approve(tokenName, amount)`
Approves a token for trading.

**Parameters:**
- `tokenName` (string, required): Token name to approve
- `amount` (number, required): Amount to approve (must be positive)

**Returns:** `Promise<Object>` - Response from the approval operation

**Example:**
```javascript
const result = await lnex.spot.approve("USDT", 1000);
```

#### `deposit(tokenNameOrAssetId, amount)`
Deposits an asset.

**Parameters:**
- `tokenNameOrAssetId` (string, required): Token name (e.g., "USDT") or Asset ID
- `amount` (number, required): Amount to deposit (must be positive)

**Returns:** `Promise<Object>` - Response from the deposit operation

**Example:**
```javascript
// Using token name
const result = await lnex.spot.deposit("USDT", 100);

// Using asset ID
const result2 = await lnex.spot.deposit("asset_id_here", 100);
```

#### `withdraw(assetsId, amount)`
Withdraws an asset.

**Parameters:**
- `assetsId` (string, required): Asset ID
- `amount` (number, required): Amount to withdraw

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const result = await lnex.spot.withdraw("asset_id_here", 50);
```

### Market Data

#### `getAllMarkets()`
Fetches all available markets.

**Returns:** `Promise<Object>` - Market data

**Example:**
```javascript
const markets = await lnex.spot.getAllMarkets();
```

### Order Management

#### `createOrderApi(params)`
Creates a new order.

**Parameters:**
- `params` (Object, required): Order parameters
  - `side` (string, required): Order side ("buy" or "sell")
  - `volume` (number, required): Order volume (must be positive)
  - `symbolName` (string, required): Symbol name
  - `price` (number, optional): Order price (default: 0 for market order)
  - `type` (number, optional): Order type (default: 2)
  - `timeInForce` (number, optional): Time in force (default: 2)
  - `leverageLevel` (number, optional): Leverage level (default: 1)

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const order = await lnex.spot.createOrderApi({
  side: "buy",
  volume: 0.1,
  symbolName: "BTC-USDT",
  price: 50000
});
```

#### `cancelOrder(params)`
Cancels an order.

**Parameters:**
- `params` (Object, required): Order parameters
  - `symbolName` (string, required): Symbol name
  - `orderId` (number, required): Order ID

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const result = await lnex.spot.cancelOrder({
  symbolName: "BTC-USDT",
  orderId: 12345
});
```

#### `cancelAllOrder(params)`
Cancels all orders for a specific symbol.

**Parameters:**
- `params` (Object, required): Order parameters
  - `symbolName` (string, required): Symbol name

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const result = await lnex.spot.cancelAllOrder({
  symbolName: "BTC-USDT"
});
```

#### `currentOrderList(params)`
Retrieves current order list for a specific symbol.

**Parameters:**
- `params` (Object, required): Query parameters
  - `symbolName` (string, required): Symbol name
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)
  - `type` (string, optional): Order type filter (default: "")

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const orders = await lnex.spot.currentOrderList({
  symbolName: "BTC-USDT",
  page: 1,
  limit: 20
});
```

#### `triggerOrderList(params)`
Retrieves trigger order list for a specific symbol.

**Parameters:**
- `params` (Object, required): Query parameters
  - `symbolName` (string, required): Symbol name
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)
  - `type` (string, optional): Order type filter (default: "")

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const triggerOrders = await lnex.spot.triggerOrderList({
  symbolName: "BTC-USDT"
});
```

#### `historyOrderList(params)`
Retrieves historical order list for a specific symbol.

**Parameters:**
- `params` (Object, required): Query parameters
  - `symbolName` (string, required): Symbol name
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)
  - `wallet` (string, optional): Wallet address (default: current user's address)
  - `type` (string, optional): Order type filter (default: "")
  - `beginTime` (string, optional): Start time filter (default: "")
  - `endTime` (string, optional): End time filter (default: "")

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const historyOrders = await lnex.spot.historyOrderList({
  symbolName: "BTC-USDT",
  page: 1,
  limit: 50,
  beginTime: "2024-01-01",
  endTime: "2024-01-31"
});
```

#### `historyTriggerOrderList(params)`
Retrieves historical trigger order list for a specific symbol.

**Parameters:**
- `params` (Object, required): Query parameters
  - `symbolName` (string, required): Symbol name
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)
  - `wallet` (string, optional): Wallet address (default: current user's address)
  - `type` (string, optional): Order type filter (default: "")
  - `beginTime` (string, optional): Start time filter (default: "")
  - `endTime` (string, optional): End time filter (default: "")

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const historyTriggerOrders = await lnex.spot.historyTriggerOrderList({
  symbolName: "BTC-USDT"
});
```

#### `hisTradeList(params)`
Retrieves historical trade list for a specific symbol.

**Parameters:**
- `params` (Object, required): Query parameters
  - `symbolName` (string, required): Symbol name
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)
  - `wallet` (string, optional): Wallet address (default: current user's address)
  - `type` (string, optional): Trade type filter (default: "")
  - `beginTime` (string, optional): Start time filter (default: "")
  - `endTime` (string, optional): End time filter (default: "")

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const trades = await lnex.spot.hisTradeList({
  symbolName: "BTC-USDT",
  limit: 100
});
```

---

## PerpApi Methods

### User Management

#### `createUser(referrals?)`
Registers a user for perpetual trading.

**Parameters:**
- `referrals` (string, optional): Referral ID for user registration (default: "")

**Returns:** `Promise<Object>` - Response from the API containing user registration result

**Example:**
```javascript
const result = await lnex.perp.createUser("referral123");
```

#### `enableTrade(contractName)`
Enables trading for a specific contract.

**Parameters:**
- `contractName` (string, required): The name of the contract to enable trading for

**Returns:** `Promise<Object>` - Response data of the enable trade request

**Example:**
```javascript
const result = await lnex.perp.enableTrade("E-BTC-USDT");
```

#### `getUserInfo()`
Fetches user information.

**Returns:** `Promise<Object>` - User information data

**Example:**
```javascript
const userInfo = await lnex.perp.getUserInfo();
```

### Asset Management

#### `approve(tokenName, amount)`
Approves a token for perpetual trading.

**Parameters:**
- `tokenName` (string, required): Token name
- `amount` (number, required): Amount to approve

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const result = await lnex.perp.approve("USDT", 1000);
```

#### `deposit(tokenNameOrAssetId, amount)`
Deposits an asset for perpetual trading.

**Parameters:**
- `tokenNameOrAssetId` (string, required): Token name (e.g., "USDT") or Asset ID
- `amount` (number, required): Amount to deposit (must be positive)

**Returns:** `Promise<Object>` - Response from the deposit operation

**Example:**
```javascript
const result = await lnex.perp.deposit("USDT", 100);
```

#### `withdraw(assetsId, amount)`
Withdraws an asset from perpetual trading.

**Parameters:**
- `assetsId` (string, required): Asset ID
- `amount` (number, required): Amount to withdraw

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const result = await lnex.perp.withdraw("asset_id_here", 50);
```

### Market Data

#### `getAllMarkets()`
Fetches all available perpetual markets.

**Returns:** `Promise<Object>` - Market data

**Example:**
```javascript
const markets = await lnex.perp.getAllMarkets();
```

### Position Management

#### `getAllPosition(data?)`
Fetches all positions.

**Parameters:**
- `data` (Object, optional): Query parameters
  - `positionStatus` (string, optional): Position status filter (default: "1")

**Returns:** `Promise<Object>` - Position data

**Example:**
```javascript
const positions = await lnex.perp.getAllPosition({
  positionStatus: "1"
});
```

#### `getHistoryPosition(data)`
Fetches historical positions.

**Parameters:**
- `data` (Object, required): Query parameters
  - `contractId` (string, required): Contract ID
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)

**Returns:** `Promise<Object>` - Historical position data

**Example:**
```javascript
const historyPositions = await lnex.perp.getHistoryPosition({
  contractId: "contract123",
  page: 1,
  limit: 20
});
```

#### `editLevel(data)`
Edits leverage level for a contract.

**Parameters:**
- `data` (Object, required): Parameters
  - `contractName` (string, required): Contract name
  - `nowLevel` (number, required): New leverage level

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const result = await lnex.perp.editLevel({
  contractName: "E-BTC-USDT",
  nowLevel: 10
});
```

### Order Management

#### `createOrderApi(params)`
Creates a new perpetual order.

**Parameters:**
- `params` (Object, required): Order parameters
  - `side` (string, required): Order side ("buy" or "sell")
  - `volume` (number, required): Order volume (must be positive)
  - `contractName` (string, required): Contract name
  - `openOrClose` (string, required): "open" or "close"
  - `price` (number, optional): Order price (default: 0 for market order)
  - `type` (number, optional): Order type (default: 2)
  - `leverageLevel` (number, optional): Leverage level (default: 8)

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const order = await lnex.perp.createOrderApi({
  side: "buy",
  volume: 0.1,
  contractName: "E-BTC-USDT",
  openOrClose: "open",
  leverageLevel: 10
});
```

#### `cancelOrder(params)`
Cancels a perpetual order.

**Parameters:**
- `params` (Object, required): Order parameters
  - `contractName` (string, required): Contract name
  - `orderId` (number, required): Order ID

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const result = await lnex.perp.cancelOrder({
  contractName: "E-BTC-USDT",
  orderId: 12345
});
```

#### `cancelAllOrder(params)`
Cancels all orders for a specific contract.

**Parameters:**
- `params` (Object, required): Order parameters
  - `contractName` (string, required): Contract name

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const result = await lnex.perp.cancelAllOrder({
  contractName: "E-BTC-USDT"
});
```

#### `currentOrderList(params)`
Retrieves current order list for a specific contract.

**Parameters:**
- `params` (Object, required): Query parameters
  - `contractName` (string, required): Contract name
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)
  - `type` (string, optional): Order type filter (default: "")

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const orders = await lnex.perp.currentOrderList({
  contractName: "E-BTC-USDT"
});
```

#### `triggerOrderList(params)`
Retrieves trigger order list for a specific contract.

**Parameters:**
- `params` (Object, required): Query parameters
  - `contractName` (string, required): Contract name
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)
  - `type` (string, optional): Order type filter (default: "")

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const triggerOrders = await lnex.perp.triggerOrderList({
  contractName: "E-BTC-USDT"
});
```

#### `historyOrderList(params)`
Retrieves historical order list for a specific contract.

**Parameters:**
- `params` (Object, required): Query parameters
  - `contractName` (string, required): Contract name
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)
  - `wallet` (string, optional): Wallet address (default: current user's address)
  - `type` (string, optional): Order type filter (default: "")
  - `beginTime` (string, optional): Start time filter (default: "")
  - `endTime` (string, optional): End time filter (default: "")

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const historyOrders = await lnex.perp.historyOrderList({
  contractName: "E-BTC-USDT",
  page: 1,
  limit: 50
});
```

#### `historyTriggerOrderList(params)`
Retrieves historical trigger order list for a specific contract.

**Parameters:**
- `params` (Object, required): Query parameters
  - `contractName` (string, required): Contract name
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)
  - `wallet` (string, optional): Wallet address (default: current user's address)
  - `type` (string, optional): Order type filter (default: "")
  - `beginTime` (string, optional): Start time filter (default: "")
  - `endTime` (string, optional): End time filter (default: "")

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const historyTriggerOrders = await lnex.perp.historyTriggerOrderList({
  contractName: "E-BTC-USDT"
});
```

#### `hisTradeList(params)`
Retrieves historical trade list for a specific contract.

**Parameters:**
- `params` (Object, required): Query parameters
  - `contractName` (string, required): Contract name
  - `page` (number, optional): Page number (default: 1)
  - `limit` (number, optional): Items per page (default: 10)
  - `wallet` (string, optional): Wallet address (default: current user's address)
  - `type` (string, optional): Trade type filter (default: "")
  - `beginTime` (string, optional): Start time filter (default: "")
  - `endTime` (string, optional): End time filter (default: "")

**Returns:** `Promise<Object>` - Response from the API

**Example:**
```javascript
const trades = await lnex.perp.hisTradeList({
  contractName: "E-BTC-USDT",
  limit: 100
});
```

---



---

## Error Handling

All API methods return promises and may throw errors. Always use try-catch blocks:

```javascript
try {
  const result = await lnex.spot.createOrderApi({
    symbolName: "BTC-USDT",
    side: "buy",
    volume: 0.01,
    type: 1,
    price: 30000,
  });
  console.log('Order created:', result);
} catch (error) {
  console.error('Order failed:', error.message);
}
```

---

## License

MIT