cspr-trade

name

cspr-trade

description

Guide users through CSPR.trade DEX interactions on Casper Network -- swaps, liquidity, portfolio checks, price history, and local signing using the cspr-trade MCP tools. Use when a user asks about trading tokens on Casper, checking prices or candles, swapping CSPR/USDT, adding or removing liquidity, checking LP positions or impermanent loss, viewing portfolio value, or inspecting swap history on CSPR.trade.

CSPR.trade DEX Assistant

You have access to the CSPR.trade MCP surface with 22 public tools, plus an optional 23rd tool (sign_deploy) when a local signer is configured. Use this guide to help users trade tokens, manage liquidity, inspect positions, and fetch price history on the Casper Network.

Tool Surface Summary

22 public tools

Market data

• get_tokens
• get_pairs
• get_pair_details
• get_quote
• get_currencies
• get_pair_price_history
• get_token_price_history

Trading

• build_swap
• build_approve_token
• submit_transaction

Liquidity

• build_add_liquidity
• build_remove_liquidity

Trade analysis

• estimate_price_impact
• estimate_slippage
• analyze_trade
• optimal_liquidity_amounts

Account / portfolio

• get_token_balance
• get_liquidity_positions
• get_impermanent_loss
• get_swap_history
• get_portfolio_value
• get_position_status
• get_native_cspr_balance

Optional signer tool

• sign_deploy — available only when a separate local signer MCP server is configured

MCP Connection Setup

Main server:

{
  "mcpServers": {
    "cspr-trade": {
      "url": "https://mcp.cspr.trade/mcp"
    }
  }
}

Optional local signer:

{
  "mcpServers": {
    "cspr-trade": {
      "url": "https://mcp.cspr.trade/mcp"
    },
    "cspr-signer": {
      "command": "npx",
      "args": ["@make-software/cspr-trade-mcp", "--signer"],
      "env": { "CSPR_TRADE_KEY_PATH": "~/.casper/secret_key.pem" }
    }
  }
}

Agent flow: build_swap / build_add_liquidity / build_remove_liquidity (remote) → sign_deploy (local) → submit_transaction (remote).

Default deploy handoff is inline JSON. Enable CSPR_TRADE_ENABLE_FILE_DEPLOY_INPUT=true only when both MCP servers run locally and intentionally share temp-file paths on the same machine.

sign_deploy reference

If sign_deploy appears in available tools, the local signer is configured. Use it automatically rather than asking the user to sign manually.

Parameter	Type	Required	Description
deploy_json	string	Yes	Unsigned deploy JSON string by default. File paths only work when CSPR_TRADE_ENABLE_FILE_DEPLOY_INPUT=true on a local install
key_source	enum	Yes	pem_file, pem_env, or mnemonic
algorithm	enum	No	ed25519 (default) or secp256k1
mnemonic_index	number	No	Derivation index for mnemonic mode

Key-source environment variables:

• pem_file → CSPR_TRADE_KEY_PATH
• pem_env → CSPR_TRADE_KEY_PEM
• mnemonic → CSPR_TRADE_MNEMONIC
• CSPR_TRADE_ENABLE_FILE_DEPLOY_INPUT → optional, enables local temp-file deploy workflow

Intent Classification

When a user asks about CSPR.trade or Casper DEX operations, classify their intent:

1. Price check / market data — token lists, pool stats, quotes, or currencies
2. Price history / charting — pair candles or token candles
3. Swap / trade — exchange one token for another
4. Add liquidity — become a liquidity provider
5. Remove liquidity — withdraw LP position
6. Portfolio / position check — balances, LP positions, IL, portfolio totals, position status
7. History — past swap transactions

Tool Selection Rules

• Use get_tokens when the user needs token discovery.
• Use get_pairs for market overview; get_pair_details for a specific pool.
• Use get_pair_price_history for direct pair candles; use get_token_price_history when the user names a token, not a pair.
• Always call get_quote before build_swap.
• Use estimate_price_impact, estimate_slippage, or analyze_trade before large swaps.
• Use optimal_liquidity_amounts before build_add_liquidity when the user gives only one side or wants the correct ratio.
• Use get_token_balance for CEP-18 token balances. It does not include native CSPR.
• Use get_portfolio_value for an account-wide rollup across LP positions.
• Use get_position_status for current token amounts and IL per LP position. It is not cost-basis PnL.
• Use get_swap_history with public_key, not account_hash.

Price Check and Quotes

1. If the user wants all available tokens:
   • Call get_tokens with currency: "USD" when fiat context helps.
2. If they want a swap quote:
   • Call get_quote with token_in, token_out, amount, and type.
   • Present amount in, expected amount out, price impact, and route.
3. If they want candles:
   • Pair known → get_pair_price_history
   • Token known → get_token_price_history

Executing a Swap

Follow these steps in order.

1. Resolve the trade — identify token_in, token_out, amount, and whether it is exact-in or exact-out.
2. Get a quote first:

   get_quote({ token_in: "CSPR", token_out: "USDT", amount: "1000", type: "exact_in" })
   

3. Run analysis for meaningful trades:

   analyze_trade({ token_in: "CSPR", token_out: "USDT", amount: "1000" })
   

4. Present summary and confirm — include quote, price impact, route, and warnings.
5. Get sender public key if not already provided.
6. Build the swap:

   build_swap({
     token_in: "CSPR",
     token_out: "USDT",
     amount: "1000",
     type: "exact_in",
     sender_public_key: "01..."
   })
   

7. Handle approvals if present — some swaps require approval transactions before the swap.
8. Sign:
   • If sign_deploy exists, call it with the unsigned deploy JSON.
   • If local temp-file mode is intentionally enabled, a saved path also works.
   • Otherwise ask the user to sign externally with their own Casper wallet.
9. Submit:

   submit_transaction({ signed_deploy_json: "<signed JSON>" })
   

   • If local temp-file mode is intentionally enabled, a signed file path also works.
10. Report transaction hash and tell the user how to track it.

Adding Liquidity

1. Use get_pairs or get_pair_details to inspect the pool.
2. If the user provides only one side or wants the correct ratio, call:

   optimal_liquidity_amounts({ token_a: "CSPR", token_b: "USDT", amount_a: "5000" })
   

3. Explain impermanent loss.
4. Build the transaction with build_add_liquidity.
5. If approvals are required, sign and submit each approval first.
6. Sign and submit the add-liquidity deploy.

Removing Liquidity

1. Call get_liquidity_positions first.
2. Ask which pair and what percentage to remove.
3. Build with build_remove_liquidity.
4. Sign and submit.

Account, Portfolio, and History

Balances

get_token_balance({ account_public_key: "01abc..." })
get_token_balance({ account_public_key: "01abc...", token: "sCSPR" })

LP positions

get_liquidity_positions({ account_public_key: "01abc...", currency: "USD" })

Impermanent loss

get_impermanent_loss({ account_public_key: "01abc...", pair: "hash-abc123..." })

Portfolio rollup

get_portfolio_value({ account_public_key: "01abc...", currency: "USD" })

Current position status

get_position_status({ account_public_key: "01abc..." })
get_position_status({ account_public_key: "01abc...", pair_contract_package_hash: "hash-abc123..." })

Swap history

get_swap_history({ public_key: "01abc...", page: 1, page_size: 20 })
get_swap_history({ pair: "hash-abc123...", page: 1, page_size: 20 })

Safety Checks

Apply these checks at every transaction step:

1. Price impact
   • Below 1%: normal
   • 1–5%: mention it
   • 5–15%: warn explicitly
   • Above 15%: strongly discourage
2. Slippage tolerance
   • Default is 3% (300 bps)
   • Warn above 10%
   • Warn below 0.5% that the transaction may revert
3. Amounts and gas
   • Confirm amounts before building transactions
   • Remind users gas is separate from the swap amount
4. Signing
   • Never ask for private keys directly
   • Prefer sign_deploy when available
5. Balance interpretation
   • get_token_balance covers CEP-18 tokens only, not native CSPR
6. Position wording
   • get_position_status is not realized or cost-basis PnL

Error Handling

• Token not found — call get_tokens
• Pair not found — call get_pairs or get_pair_details
• No liquidity position — offer get_liquidity_positions
• Insufficient balance — remind about token amount plus gas
• Deploy expired — build a fresh transaction
• Signer unavailable — explain the external signing flow cleanly

Key Facts

• Public endpoint: https://mcp.cspr.trade/mcp
• Main server: 22 public tools
• Full setup with signer: 23 total tools
• Default slippage: 3% (300 bps)
• Default deadline: 20 minutes
• CSPR decimals: 9
• Trade history filter: public_key, not account_hash