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

TypeScript SDK for the 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

npm install @make-software/cspr-trade-mcp-sdk

Quick Start

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

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.

const tokens = await client.getTokens('USD');
// [{ symbol: 'CSPR', name: 'Casper', decimals: 9, fiatPrice: 0.012, ... }, ...]

getPairs(opts?)

List trading pairs with reserves and pricing.

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.

const pair = await client.getPairDetails('hash-abc123...', 'USD');

getQuote(params)

Get a swap quote with routing path, price impact, and recommended slippage.

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.

const currencies = await client.getCurrencies();
// [{ code: 'USD', name: 'US Dollar', symbol: '$' }, ...]

Account Data

getLiquidityPositions(publicKey, currency?)

Get liquidity positions for an account.

const positions = await client.getLiquidityPositions('01abc...', 'USD');

getImpermanentLoss(publicKey, pairHash)

Calculate impermanent loss for a position.

const il = await client.getImpermanentLoss('01abc...', 'hash-...');

getSwapHistory(opts?)

Get swap transaction history, optionally filtered by account or pair.

const history = await client.getSwapHistory({
  accountHash: 'account-hash-...',
  page: 1,
  pageSize: 20,
});

Transaction Building

All transaction methods return a TransactionBundle:

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)

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)

const bundle = await client.buildAddLiquidity({
  tokenA: 'CSPR',
  tokenB: 'USDT',
  amountA: '1000',
  amountB: '42',
  senderPublicKey: '01abc...',
});

buildRemoveLiquidity(params)

const bundle = await client.buildRemoveLiquidity({
  pairContractPackageHash: 'hash-...',
  percentage: 50,            // remove 50% of position
  senderPublicKey: '01abc...',
});

buildApproval(params)

const bundle = await client.buildApproval({
  tokenContractPackageHash: 'hash-...',
  spenderPackageHash: 'hash-...',
  amount: '1000000000',      // raw amount
  senderPublicKey: '01abc...',
});

Transaction Submission

submitTransaction(signedDeployJson)

const result = await client.submitTransaction(signedDeployJson);
console.log(result.transactionHash);

Token Resolution

resolveToken(identifier)

Resolve a token by symbol, name, or contract hash.

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

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

npm run build        # Build to dist/
npm test             # Run unit tests
npm run test:watch   # Watch mode