CSPR.trade MCP

SKILL.md

---
name: cspr-trade-mcp
description: Trade on CSPR.trade DEX (Casper Network) — swaps, liquidity, and portfolio queries via the cspr-trade MCP server. Non-custodial — transactions are built remotely and signed locally.
version: 1.1.0
metadata:
  openclaw:
    emoji: "🔁"
    homepage: https://mcp.cspr.trade
    repository: https://github.com/make-software/cspr-trade-mcp
    license: MIT
    requires:
      env:
        - name: CSPR_TRADE_KEY_PATH
          description: "Path to PEM private key file (only used by the optional local signer server)"
          optional: true
          sensitive: true
        - name: CSPR_TRADE_KEY_PEM
          description: "PEM key content inline (only used by the optional local signer server)"
          optional: true
          sensitive: true
        - name: CSPR_TRADE_MNEMONIC
          description: "BIP-39 mnemonic phrase (only used by the optional local signer server)"
          optional: true
          sensitive: true
        - name: CSPR_TRADE_NETWORK
          description: "Network to connect to: mainnet (default) or testnet"
          optional: true
    install: []
---

# CSPR.trade DEX Assistant

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.

## MCP Connection Setup

The CSPR.trade MCP server must be connected before using these tools. If not already configured, add to MCP client config:

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

For self-hosting (runs the open-source server locally from [make-software/cspr-trade-mcp](https://github.com/make-software/cspr-trade-mcp)):

```json
{
  "mcpServers": {
    "cspr-trade": {
      "command": "npx",
      "args": ["@make-software/cspr-trade-mcp"],
      "env": { "CSPR_TRADE_NETWORK": "testnet" }
    }
  }
}
```

### Local Signer Mode (optional, user-initiated only)

> **Security note:** The local signer is a separate process that runs entirely on the user's machine. The private key is loaded from a local environment variable and never transmitted over the network or exposed to the LLM. This mode is only active when the user explicitly configures a `cspr-signer` server entry. The agent must never configure, enable, or modify signer settings on behalf of the user.

If the user has chosen to set up a local signer, their config will include a second server entry:

```json
{
  "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` (remote) → user confirms → `sign_deploy` (local) → `submit_transaction` (remote).

**Key source options (configured by the user in their MCP client, not by the agent):**

| `key_source` | Env variable | Description |
|---|---|---|
| `pem_file` | `CSPR_TRADE_KEY_PATH` | Path to PEM private key file |
| `pem_env` | `CSPR_TRADE_KEY_PEM` | PEM key content inline |
| `mnemonic` | `CSPR_TRADE_MNEMONIC` | BIP-39 phrase (BIP-44 `m/44'/506'/0'/0/{index}`) |

Supports Ed25519 and Secp256k1.

### `sign_deploy` Tool Reference

**Important:** The presence of `sign_deploy` in your available tools means the user has opted into local signing by configuring the signer server themselves. You must still confirm with the user before each signing operation — do not sign automatically.

**Parameters:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `deploy_json` | string | Yes | Unsigned deploy JSON from `build_swap`, `build_add_liquidity`, or `build_remove_liquidity`. |
| `key_source` | enum | Yes | `"pem_file"`, `"pem_env"`, or `"mnemonic"` — which env var holds the key. |
| `algorithm` | enum | No | `"ed25519"` (default) or `"secp256k1"`. |
| `mnemonic_index` | number | No | HD derivation index (default 0). Only for `mnemonic` key source. |

**Returns:** Signed transaction JSON, signer public key, transaction hash, and saved file path.

**Agent behavior:**
1. After any `build_*` call, present the unsigned transaction summary to the user.
2. Ask: "Would you like me to sign this with your local signer?" — wait for explicit confirmation.
3. Only after user confirms, call `sign_deploy` with the unsigned JSON.
4. The private key is loaded from an env var on the user's machine — it is never sent over the network or seen by the LLM.
5. Pass the signed JSON to `submit_transaction` to complete the flow.

## 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 get explicit confirmation**: 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**: Only after the user confirms. 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** (user has configured local signer):
   - Present the transaction details and ask: "Shall I sign this with your local signer?"
   - Only after the user confirms, call `sign_deploy` with the unsigned JSON.
   - The signing happens locally on the user's machine — the private key never leaves their environment.
   ```
   sign_deploy({
     deploy_json: "<unsigned transaction JSON>",
     key_source: "pem_file"
   })
   ```
   - Proceed to step 8 with the signed JSON.

   **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 explicit 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 or handle private keys directly.
   - Never attempt to configure, enable, or modify signer settings on the user's behalf.
   - If `sign_deploy` is available, always confirm with the user before signing — do not auto-sign.
   - If `sign_deploy` is not available, explain the external signing flow clearly.
   - If the user seems confused about signing, explain the non-custodial model: "Your keys stay on your machine. The MCP server only builds unsigned transactions — it never has access to your private key."

## 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)
- **Source code**: [make-software/cspr-trade-mcp](https://github.com/make-software/cspr-trade-mcp) (MIT license)
- **Public endpoint**: `https://mcp.cspr.trade/mcp`