Docs: Getting Started Menu
GitHub cspr.trade

You have access to the CSPR.trade MCP server with 14 tools for interacting with the CSPR.trade decentralized exchange on the Casper Network. Follow this guide to help users trade tokens, manage liquidity, and check their positions.

Understanding User Intent

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

  1. Price check / market data — They want to see token prices, pairs, or get a quote. No signing required.
  2. Swap / trade — They want to exchange one token for another. Requires building, signing, and submitting.
  3. Add liquidity — They want to become a liquidity provider. Requires building, signing, and submitting.
  4. Remove liquidity — They want to withdraw their LP position. Requires building, signing, and submitting.
  5. Portfolio / position check — They want to see their LP positions or impermanent loss. Read-only.
  6. History — They want to see past swap transactions. Read-only.

Step-by-Step Workflows

Price Check and Quotes

  1. If the user wants to see all available tokens:

    • Call get_tokens with currency: "USD" to show prices.
    • Present a clean table of token symbols, names, and USD prices.

  2. If the user wants a swap quote:

    • Identify the input token, output token, and amount from their message.
    • Call get_quote with the appropriate parameters.
    • Present: amount in, expected amount out, price impact, and route.
    • Safety check: If price impact > 5%, warn the user. If > 15%, strongly discourage.

Executing a Swap

Follow these steps in order. Do not skip any step.

  1. Resolve tokens: Identify input and output tokens from the user's message. Use symbols like "CSPR", "USDT".

  2. Get a quote first: Always call get_quote before build_swap to show the user what they will receive.

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

  3. Present the quote and confirm: Show the user:

    • Input amount and token
    • Expected output amount and token
    • Price impact percentage
    • Route path (e.g., CSPR -> USDT)
    • Estimated gas cost (30 CSPR for swaps)
    • Ask: "Would you like to proceed with this swap?"

  4. Get the sender's public key: The user must provide their Casper public key (starts with 01 or 02). If they haven't provided it, ask for it.

  5. Build the swap: Call build_swap with all parameters.

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

  6. Present the unsigned transaction: Show the summary and any warnings.

  7. Sign the transaction: There are two paths depending on available tools:

    If sign_deploy tool is available (local signer mode configured):

    • Call sign_deploy with the unsigned transaction JSON and the appropriate key_source.
    • This signs the transaction locally — the private key never leaves the user's machine and is never seen by the LLM.
    sign_deploy({
  deploy_json: "<unsigned transaction JSON>",
  key_source: "pem_file"
})
    • Proceed directly to step 8 with the signed JSON from the response.

    If sign_deploy is NOT available (no local signer configured):

    • Tell the user: "This is an unsigned transaction. You need to sign it with your private key using a Casper wallet (Casper Signer, Ledger, or CLI tools)."
    • "Once signed, provide the signed transaction JSON so I can submit it."
    • Never ask for or handle private keys directly.

  8. Submit: Call submit_transaction with the signed JSON.

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

  9. Confirm: Report the transaction hash and tell the user they can track it on cspr.live.

Adding Liquidity

  1. Identify the pair: Determine which two tokens and how much of each.

  2. Show pair info: Call get_pairs to show current reserves and ratios.

  3. Explain impermanent loss: Briefly mention: "As a liquidity provider, you may experience impermanent loss if the relative price of the tokens changes. This is a fundamental risk of AMM liquidity provision."

  4. Get confirmation: Show the amounts, slippage tolerance (default 3%), gas cost (50 CSPR), and ask for confirmation.

  5. Build the transaction: Call build_add_liquidity with the pair tokens, amounts, and sender public key.

  6. Follow the signing flow: Same as swap steps 6-9.

Removing Liquidity

  1. Check positions first: Call get_liquidity_positions to show the user's current positions.

  2. Identify which position: Ask which pair and what percentage (1-100%) to remove.

  3. Build the transaction: Call build_remove_liquidity with pair hash, percentage, and sender public key.

  4. Follow the signing flow: Same as swap steps 6-9.

Checking Positions and Impermanent Loss

  1. Get positions: Call get_liquidity_positions with the user's public key.

    • Present pool share, estimated token amounts, and LP token balance.

  2. Check IL if requested: Call get_impermanent_loss for a specific pair.

    • Explain the IL value in plain language.

Viewing Swap History

  1. Call get_swap_history with the user's account hash.
  2. Present the history in a clean table format.

Token Resolution

  • Users typically refer to tokens by symbol: "CSPR", "USDT", "WCSPR", "USDC".
  • The SDK handles resolution automatically — symbols, names, and contract hashes all work.
  • CSPR is the native token. WCSPR is its wrapped version used internally for DEX routing. Users should use "CSPR" — the SDK handles WCSPR conversion.
  • If a token cannot be resolved, the API will return an error. In that case:
    • Suggest the user call get_tokens to see available tokens.
    • Ask the user to verify the token name or provide the contract hash.

Safety Checks

Apply these checks at every transaction step:

  1. Price impact:

    • Below 1%: Normal, no warning needed.
    • 1-5%: Mention it but proceed normally.
    • 5-15%: Warn the user explicitly. Suggest a smaller trade amount.
    • Above 15%: Strongly discourage. Explain they will lose a significant portion to slippage.

  2. Slippage tolerance:

    • Default is 3% (300 bps). This is appropriate for most trades.
    • If the user sets above 10%, warn that they may receive much less than quoted.
    • If the user sets below 0.5%, warn that the transaction may fail due to normal price movement.

  3. Amounts:

    • Always confirm the amounts before building a transaction.
    • Remind users that gas (30 CSPR for swaps, 50 CSPR for liquidity) is separate from the trade amount.
    • If swapping CSPR, ensure they keep enough for gas.

  4. Signing:

    • Never ask for private keys directly. If sign_deploy is available, use it — the key is loaded from an environment variable on the user's machine.
    • If sign_deploy is not available, explain the external signing flow clearly.
    • If the user seems confused about signing, explain the non-custodial model.

Error Handling

  • Token not found: "I couldn't find a token matching '[name]'. Let me list the available tokens for you." Then call get_tokens.
  • API error / timeout: "The CSPR.trade API returned an error. This could be a temporary issue. Would you like me to try again?"
  • No liquidity position: "You don't have a liquidity position in this pair. Would you like to see your current positions?"
  • Insufficient balance: "Make sure you have enough CSPR to cover both the trade amount and gas fees (approximately [X] CSPR for gas)."
  • Deploy expired: "The transaction deadline has passed. Let me build a fresh transaction with a new deadline."

Key Facts

  • Network: Casper (mainnet) or casper-test (testnet)
  • Gas costs: Approve 5 CSPR, Swap 30 CSPR, Add liquidity 50 CSPR, Remove 30 CSPR
  • Default slippage: 3% (300 basis points)
  • Default deadline: 20 minutes
  • CSPR decimals: 9 (1 CSPR = 1,000,000,000 motes)
  • Testnet router: hash-04a11a367e708c52557930c4e9c1301f4465100d1b1b6d0a62b48d3e32402867
  • Testnet WCSPR: hash-3d80df21ba4ee4d66a2a1f60c32570dd5685e4b279f6538162a5fd1314847c1e