@make-software/cspr-trade-mcp-sdk 0.1.0

package/README.md

@@ -0,0 +1,257 @@
+# @make-software/cspr-trade-mcp-sdk
+
+TypeScript SDK for the [CSPR.trade](https://cspr.trade) DEX on the Casper Network. Provides market data queries, swap/liquidity transaction building, and token resolution — all through the CSPR.trade API.
+
+Non-custodial: all transaction methods return unsigned transaction JSON for external signing.
+
+## Installation
+
+```bash
+npm install @make-software/cspr-trade-mcp-sdk
+```
+
+## Quick Start
+
+```typescript
+import { CsprTradeClient } from '@make-software/cspr-trade-mcp-sdk';
+
+const client = new CsprTradeClient({ network: 'testnet' });
+
+// Get a swap quote
+const quote = await client.getQuote({
+  tokenIn: 'CSPR',
+  tokenOut: 'USDT',
+  amount: '1000',
+  type: 'exact_in',
+});
+console.log(`${quote.amountInFormatted} CSPR -> ${quote.amountOutFormatted} USDT`);
+console.log(`Price impact: ${quote.priceImpact}%`);
+
+// Build an unsigned swap transaction
+const bundle = await client.buildSwap({
+  tokenIn: 'CSPR',
+  tokenOut: 'USDT',
+  amount: '1000',
+  type: 'exact_in',
+  senderPublicKey: '01abc...',
+});
+console.log(bundle.summary);
+// => "Swap 1000 CSPR for ~42.5 USDT\nRoute: CSPR → WCSPR → USDT\n..."
+
+// bundle.transactionJson is the unsigned transaction — sign externally, then submit:
+const result = await client.submitTransaction(signedTransactionJson);
+console.log(`Submitted: ${result.transactionHash}`);
+```
+
+## Configuration
+
+```typescript
+const client = new CsprTradeClient({
+  network: 'testnet',               // 'mainnet' | 'testnet'
+  apiUrl: 'https://custom-api.com', // optional override
+  routerPackageHash: 'hash-...',    // optional override
+  wcsprPackageHash: 'hash-...',     // optional override
+});
+```
+
+## API Reference
+
+### Market Data
+
+#### `getTokens(currency?)`
+
+List all tradable tokens with optional fiat pricing.
+
+```typescript
+const tokens = await client.getTokens('USD');
+// [{ symbol: 'CSPR', name: 'Casper', decimals: 9, fiatPrice: 0.012, ... }, ...]
+```
+
+#### `getPairs(opts?)`
+
+List trading pairs with reserves and pricing.
+
+```typescript
+const pairs = await client.getPairs({
+  page: 1,
+  page_size: 10,
+  order_by: 'reserve0',
+  order_direction: 'desc',
+  currency: 'USD',
+});
+```
+
+#### `getPairDetails(pairHash, currency?)`
+
+Get detailed info about a specific pair.
+
+```typescript
+const pair = await client.getPairDetails('hash-abc123...', 'USD');
+```
+
+#### `getQuote(params)`
+
+Get a swap quote with routing path, price impact, and recommended slippage.
+
+```typescript
+const quote = await client.getQuote({
+  tokenIn: 'CSPR',      // symbol, name, or contract hash
+  tokenOut: 'USDT',
+  amount: '100',         // human-readable
+  type: 'exact_in',      // or 'exact_out'
+});
+```
+
+#### `getCurrencies()`
+
+List supported fiat currencies.
+
+```typescript
+const currencies = await client.getCurrencies();
+// [{ code: 'USD', name: 'US Dollar', symbol: '$' }, ...]
+```
+
+### Account Data
+
+#### `getLiquidityPositions(publicKey, currency?)`
+
+Get liquidity positions for an account.
+
+```typescript
+const positions = await client.getLiquidityPositions('01abc...', 'USD');
+```
+
+#### `getImpermanentLoss(publicKey, pairHash)`
+
+Calculate impermanent loss for a position.
+
+```typescript
+const il = await client.getImpermanentLoss('01abc...', 'hash-...');
+```
+
+#### `getSwapHistory(opts?)`
+
+Get swap transaction history, optionally filtered by account or pair.
+
+```typescript
+const history = await client.getSwapHistory({
+  accountHash: 'account-hash-...',
+  page: 1,
+  pageSize: 20,
+});
+```
+
+### Transaction Building
+
+All transaction methods return a `TransactionBundle`:
+
+```typescript
+interface TransactionBundle {
+  transactionJson: string;             // Unsigned transaction JSON — sign externally
+  summary: string;                     // Human-readable description
+  estimatedGasCost: string;            // e.g. "30 CSPR"
+  approvalRequired?: TransactionBundle; // Token approval if needed
+  warnings: string[];                  // Price impact, slippage warnings
+}
+```
+
+#### `buildSwap(params)`
+
+```typescript
+const bundle = await client.buildSwap({
+  tokenIn: 'CSPR',
+  tokenOut: 'USDT',
+  amount: '100',
+  type: 'exact_in',
+  slippageBps: 300,          // 3% (default)
+  deadlineMinutes: 20,       // default
+  senderPublicKey: '01abc...',
+});
+```
+
+#### `buildAddLiquidity(params)`
+
+```typescript
+const bundle = await client.buildAddLiquidity({
+  tokenA: 'CSPR',
+  tokenB: 'USDT',
+  amountA: '1000',
+  amountB: '42',
+  senderPublicKey: '01abc...',
+});
+```
+
+#### `buildRemoveLiquidity(params)`
+
+```typescript
+const bundle = await client.buildRemoveLiquidity({
+  pairContractPackageHash: 'hash-...',
+  percentage: 50,            // remove 50% of position
+  senderPublicKey: '01abc...',
+});
+```
+
+#### `buildApproval(params)`
+
+```typescript
+const bundle = await client.buildApproval({
+  tokenContractPackageHash: 'hash-...',
+  spenderPackageHash: 'hash-...',
+  amount: '1000000000',      // raw amount
+  senderPublicKey: '01abc...',
+});
+```
+
+### Transaction Submission
+
+#### `submitTransaction(signedDeployJson)`
+
+```typescript
+const result = await client.submitTransaction(signedDeployJson);
+console.log(result.transactionHash);
+```
+
+### Token Resolution
+
+#### `resolveToken(identifier)`
+
+Resolve a token by symbol, name, or contract hash.
+
+```typescript
+const token = await client.resolveToken('CSPR');
+// { symbol: 'CSPR', decimals: 9, packageHash: '0000...0000', ... }
+```
+
+Resolution order: exact symbol match -> exact name match -> contract hash match.
+
+## Utility Functions
+
+```typescript
+import { toRawAmount, toFormattedAmount } from '@make-software/cspr-trade-mcp-sdk';
+
+toRawAmount('100.5', 9);       // '100500000000'
+toFormattedAmount('100500000000', 9); // '100.5'
+```
+
+## Gas Costs
+
+| Operation | Cost |
+|-----------|------|
+| Token approval | 5 CSPR |
+| Swap | 30 CSPR |
+| Add liquidity | 50 CSPR (500 for new pools) |
+| Remove liquidity | 30 CSPR |
+
+## Safety Warnings
+
+The SDK automatically generates warnings for:
+- Price impact > 5% (warning) or > 15% (strong warning)
+- Slippage tolerance > 10%
+
+## Development
+
+```bash
+npm run build        # Build to dist/
+npm test             # Run unit tests
+npm run test:watch   # Watch mode
+```

package/dist/index.d.ts

@@ -0,0 +1,362 @@
+/** Generic API success response */
+interface ApiResponse<T> {
+    data: T;
+    message?: string;
+    status?: string;
+}
+/** Paginated API response */
+interface PaginatedApiResponse<T> {
+    data: T[];
+    item_count: number;
+    page_count: number;
+}
+/** API error */
+interface ApiError {
+    code: number;
+    message: string;
+    status?: number;
+}
+/** Pagination options */
+interface PaginationOptions {
+    page?: number;
+    page_size?: number;
+}
+/** Sort options */
+interface SortOptions {
+    order_by?: string;
+    order_direction?: 'asc' | 'desc';
+}
+
+/** Contract package metadata from CSPR.cloud */
+interface ContractPackage {
+    contract_package_hash: string;
+    owner_public_key: string;
+    name: string;
+    description: string | null;
+    metadata: TokenMetadata;
+    icon_url: string | null;
+    website_url: string | null;
+    latest_version_contract_hash: string | null;
+    csprtrade_data: {
+        price: number;
+    } | null;
+}
+interface TokenMetadata {
+    balances_uref: string;
+    decimals: number;
+    name: string;
+    symbol: string;
+    total_supply_uref: string;
+}
+/** Token as returned by GET /tokens */
+interface TokenApiResponse {
+    contract_package_hash: string;
+    contract_package: ContractPackage;
+    listed_at: string;
+    sorting_order: number;
+    total_value_locked?: string;
+}
+/** Resolved token for SDK consumption */
+interface Token {
+    id: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+    packageHash: string;
+    iconUrl: string | null;
+    fiatPrice: number | null;
+}
+/** Currency for fiat display */
+interface Currency {
+    id: number;
+    code: string;
+    name: string;
+    symbol: string;
+}
+
+/** Pair as returned by API */
+interface PairApiResponse {
+    contract_package_hash: string;
+    token0_contract_package_hash: string;
+    token1_contract_package_hash: string;
+    decimals0: number;
+    decimals1: number;
+    reserve0: string;
+    reserve1: string;
+    timestamp: string;
+    latest_event_id: string;
+    contract_package: ContractPackage;
+    token0_contract_package: ContractPackage;
+    token1_contract_package: ContractPackage;
+}
+/** Pair for SDK consumption */
+interface Pair {
+    contractPackageHash: string;
+    token0: {
+        packageHash: string;
+        symbol: string;
+        name: string;
+        decimals: number;
+        iconUrl: string | null;
+    };
+    token1: {
+        packageHash: string;
+        symbol: string;
+        name: string;
+        decimals: number;
+        iconUrl: string | null;
+    };
+    reserve0: string;
+    reserve1: string;
+    timestamp: string;
+    fiatPrice0: number | null;
+    fiatPrice1: number | null;
+}
+
+/** Quote API response */
+interface QuoteApiResponse {
+    amount_in: string;
+    amount_out: string;
+    execution_price: string;
+    mid_price: string;
+    path: string[];
+    price_impact: string;
+    recommended_slippage_bps: string;
+    type_id: 1 | 2;
+}
+/** Quote type enum */
+type QuoteType = 'exact_in' | 'exact_out';
+/** Quote parameters */
+interface QuoteParams {
+    tokenIn: string;
+    tokenOut: string;
+    amount: string;
+    type: QuoteType;
+}
+/** Resolved quote for SDK consumption */
+interface Quote {
+    amountIn: string;
+    amountOut: string;
+    amountInFormatted: string;
+    amountOutFormatted: string;
+    executionPrice: string;
+    midPrice: string;
+    path: string[];
+    pathSymbols: string[];
+    priceImpact: string;
+    recommendedSlippageBps: string;
+    type: QuoteType;
+    tokenInSymbol: string;
+    tokenOutSymbol: string;
+    tokenInDecimals: number;
+    tokenOutDecimals: number;
+}
+
+/** Liquidity position API response */
+interface LiquidityPositionApiResponse {
+    account_hash: string;
+    pair_contract_package_hash: string;
+    lp_token_balance: string;
+    pair: PairApiResponse;
+    pair_lp_tokens_total_supply: string;
+}
+/** Liquidity position for SDK consumption */
+interface LiquidityPosition {
+    accountHash: string;
+    pairContractPackageHash: string;
+    lpTokenBalance: string;
+    lpTokenTotalSupply: string;
+    pair: {
+        token0Symbol: string;
+        token1Symbol: string;
+        token0PackageHash: string;
+        token1PackageHash: string;
+        reserve0: string;
+        reserve1: string;
+        decimals0: number;
+        decimals1: number;
+    };
+    /** User's share of the pool as percentage */
+    poolShare: string;
+    /** Estimated token0 amount based on pool share */
+    estimatedToken0Amount: string;
+    /** Estimated token1 amount based on pool share */
+    estimatedToken1Amount: string;
+}
+/** Impermanent loss response */
+interface ImpermanentLossApiResponse {
+    pair_contract_package_hash: string;
+    account_hash: string;
+    value: string;
+    timestamp: string;
+}
+interface ImpermanentLoss {
+    pairContractPackageHash: string;
+    value: string;
+    timestamp: string;
+}
+/** Add liquidity parameters */
+interface AddLiquidityParams {
+    tokenA: string;
+    tokenB: string;
+    amountA: string;
+    amountB: string;
+    slippageBps?: number;
+    deadlineMinutes?: number;
+    senderPublicKey: string;
+    /** Raw token A balance for approval amount. Falls back to amountA in motes. */
+    tokenABalance?: string;
+    /** Raw token B balance for approval amount. Falls back to amountB in motes. */
+    tokenBBalance?: string;
+}
+/** Remove liquidity parameters */
+interface RemoveLiquidityParams {
+    pairContractPackageHash: string;
+    percentage: number;
+    slippageBps?: number;
+    deadlineMinutes?: number;
+    senderPublicKey: string;
+}
+
+/** Swap parameters */
+interface SwapParams {
+    tokenIn: string;
+    tokenOut: string;
+    amount: string;
+    type: 'exact_in' | 'exact_out';
+    slippageBps?: number;
+    deadlineMinutes?: number;
+    senderPublicKey: string;
+    /** Raw token balance for approval amount (matching CSPR.trade pattern). Falls back to swap amount. */
+    tokenInBalance?: string;
+}
+/** Token approval parameters */
+interface ApprovalParams {
+    tokenContractPackageHash: string;
+    spenderPackageHash: string;
+    amount: string;
+    senderPublicKey: string;
+}
+/** The result of building a transaction */
+interface TransactionBundle {
+    /** The unsigned transaction as JSON */
+    transactionJson: string;
+    /** Human-readable description of what this transaction does */
+    summary: string;
+    /** Gas cost in CSPR */
+    estimatedGasCost: string;
+    /** If token approvals are needed first, these contain those transactions (sign & submit each before the main tx) */
+    approvalsRequired?: TransactionBundle[];
+    /** Safety warnings (high price impact, high slippage, etc.) */
+    warnings: string[];
+}
+/** Result of submitting a transaction */
+interface SubmitResult {
+    transactionHash: string;
+}
+/** Transaction status */
+interface TransactionStatus {
+    hash: string;
+    status: 'pending' | 'success' | 'failed' | 'expired';
+    errorMessage?: string;
+}
+/** Signer interface for pluggable signing */
+interface Signer {
+    sign(deployJson: string): Promise<string>;
+}
+/** Swap history entry */
+interface SwapHistoryEntry {
+    transactionHash: string;
+    timestamp: string;
+    token0ContractPackageHash: string;
+    token1ContractPackageHash: string;
+    amount0In: string;
+    amount1In: string;
+    amount0Out: string;
+    amount1Out: string;
+    senderAccountHash: string;
+}
+/** Swap history query params */
+interface SwapHistoryQuery {
+    publicKey?: string;
+    pairContractPackageHash?: string;
+    page?: number;
+    pageSize?: number;
+}
+
+interface PairQuery {
+    page?: number;
+    pageSize?: number;
+    orderBy?: 'timestamp' | 'reserve0' | 'reserve1';
+    orderDirection?: 'asc' | 'desc';
+    token0Hash?: string;
+    token1Hash?: string;
+    currencyId?: number;
+}
+interface PaginatedResult<T> {
+    data: T[];
+    itemCount: number;
+    pageCount: number;
+}
+
+interface CsprTradeClientConfig {
+    network: 'mainnet' | 'testnet';
+    apiUrl?: string;
+    routerPackageHash?: string;
+    wcsprPackageHash?: string;
+    signer?: Signer;
+}
+declare class CsprTradeClient {
+    private readonly http;
+    private readonly tokensApi;
+    private readonly pairsApi;
+    private readonly quotesApi;
+    private readonly liquidityApi;
+    private readonly ratesApi;
+    private readonly currenciesApi;
+    private readonly swapsApi;
+    private readonly tokenResolver;
+    private readonly currencyResolver;
+    private readonly networkConfig;
+    private readonly signer?;
+    constructor(config: CsprTradeClientConfig);
+    getTokens(currency?: string): Promise<Token[]>;
+    getPairs(opts?: PairQuery & {
+        currency?: string;
+    }): Promise<PaginatedResult<Pair>>;
+    getPairDetails(pairIdentifier: string, currency?: string): Promise<Pair>;
+    getQuote(params: QuoteParams): Promise<Quote>;
+    getCurrencies(): Promise<Currency[]>;
+    getLiquidityPositions(publicKey: string, currency?: string): Promise<LiquidityPosition[]>;
+    getImpermanentLoss(publicKey: string, pairHash: string): Promise<ImpermanentLoss>;
+    getSwapHistory(opts?: SwapHistoryQuery): Promise<PaginatedApiResponse<unknown>>;
+    buildSwap(params: SwapParams): Promise<TransactionBundle>;
+    buildApproval(params: ApprovalParams): Promise<TransactionBundle>;
+    buildAddLiquidity(params: AddLiquidityParams): Promise<TransactionBundle>;
+    buildRemoveLiquidity(params: RemoveLiquidityParams): Promise<TransactionBundle>;
+    /** Submit a signed transaction to the Casper node RPC */
+    submitTransaction(signedTransactionJson: string): Promise<SubmitResult>;
+    /** @deprecated Use submitTransaction instead — all transactions now submit via node RPC */
+    submitTransactionDirect(signedTransactionJson: string): Promise<SubmitResult>;
+    resolveToken(identifier: string): Promise<Token>;
+}
+
+interface NetworkConfig {
+    chainName: string;
+    apiUrl: string;
+    nodeRpcUrl: string;
+    routerPackageHash: string;
+    wcsprPackageHash: string;
+    gasPrice: number;
+    ttl: number;
+}
+declare const TESTNET_CONFIG: NetworkConfig;
+declare const MAINNET_CONFIG: NetworkConfig;
+declare function getNetworkConfig(network: 'mainnet' | 'testnet'): NetworkConfig;
+
+declare function toRawAmount(humanAmount: string, decimals: number): string;
+declare function toFormattedAmount(rawAmount: string, decimals: number): string;
+declare function calculateMinWithSlippage(rawAmount: string, slippageBps: number): string;
+declare function calculateMaxWithSlippage(rawAmount: string, slippageBps: number): string;
+
+export { type AddLiquidityParams, type ApiError, type ApiResponse, type ApprovalParams, type ContractPackage, CsprTradeClient, type CsprTradeClientConfig, type Currency, type ImpermanentLoss, type ImpermanentLossApiResponse, type LiquidityPosition, type LiquidityPositionApiResponse, MAINNET_CONFIG, type NetworkConfig, type PaginatedApiResponse, type PaginationOptions, type Pair, type PairApiResponse, type Quote, type QuoteApiResponse, type QuoteParams, type QuoteType, type RemoveLiquidityParams, type Signer, type SortOptions, type SubmitResult, type SwapHistoryEntry, type SwapHistoryQuery, type SwapParams, TESTNET_CONFIG, type Token, type TokenApiResponse, type TokenMetadata, type TransactionBundle, type TransactionStatus, calculateMaxWithSlippage, calculateMinWithSlippage, getNetworkConfig, toFormattedAmount, toRawAmount };