typus-perp-mcp

MCP (Model Context Protocol) server for Typus Perp — lets Claude and other AI agents query markets, manage positions, and execute trades on the Typus Perp DEX on Sui.

Prerequisites

• Node.js >= 18

• A Sui wallet (required for trading and liquidity tools)

• Claude Desktop or Claude Code

Related MCP server: MAIN MCP

Installation

git clone https://github.com/xingyen0613/typus-perp-mcp
cd typus-perp-mcp
npm install
cp .env.example .env   # then edit .env to add your PRIVATE_KEY
npm run build

Private Key Setup

Trading and liquidity tools require a private key. The private key is stored locally in a .env file and never leaves your machine.

1. Copy the example file:

cp .env.example .env

2. Edit .env and fill in your private key:

NETWORK=MAINNET
SUI_RPC_URL=https://fullnode.mainnet.sui.io:443
PRIVATE_KEY=<your-private-key>

Both Bech32 format (suiprivkey1...) and Base64 format are supported.

The .env file is listed in .gitignore and will never be committed to Git. If you only need read-only tools (query markets, positions, etc.), you can leave PRIVATE_KEY empty.

Enable in Claude

Setup order: Installation → Private Key Setup → add to Claude config below → restart Claude.

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "typus-perp": {
      "command": "node",
      "args": ["/absolute/path/to/typus-perp-mcp/dist/index.js"]
    }
  }
}

Claude Desktop

macOS — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "typus-perp": {
      "command": "node",
      "args": ["/absolute/path/to/typus-perp-mcp/dist/index.js"]
    }
  }
}

Windows — add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "typus-perp": {
      "command": "node",
      "args": ["C:\\Users\\username\\typus-perp-mcp\\dist\\index.js"]
    }
  }
}

Replace the path in args with the actual location where you cloned this repo. PRIVATE_KEY and other settings are loaded from the .env file in the project root — no need to repeat them here. After editing the config, restart Claude to load the new MCP server.

Tools

Query Tools (read-only, no wallet required)

get_markets

Get all active trading markets and their configurations.

No parameters required.

Returns: Market list including leverage limits, trading fees, funding rates, open interest per symbol.

get_lp_pools

Get TLP liquidity pool information.

No parameters required.

Returns: TVL, per-token liquidity amounts and USD values, LP token info.

get_stake_pools

Get TLP staking pool information.

No parameters required.

Returns: Current TLP price snapshot, total staked shares.

get_positions

Get all open positions for a wallet address.

Returns: Open positions including size, collateral, entry price, liquidation price, unrealized PnL, funding fee, borrow fee, close fee.

get_orders

Get all pending orders for a wallet address.

Returns: Pending orders including size, trigger price, leverage, order type, linked position.

get_user_stake

Get a user's TLP staking positions and pending rewards.

Returns: Staked shares, active/deactivating shares, claimable rewards, unlock timestamps.

Use this to check your cooldown status after unstake or unstake_redeem. The deactivating_shares[].unlocked_ts_ms field shows the Unix timestamp (ms) when the cooldown ends and claim becomes available.

Trading Tools (requires PRIVATE_KEY)

create_order

Create a trading order on Typus Perp.

The perp market and pool index are determined automatically based on tradingToken (TYPUS uses index 1, all others use index 0).

cancel_order

Cancel a pending trading order.

increase_collateral

Add more collateral to an existing position.

release_collateral

Withdraw excess collateral from an existing position.

collect_funding_fee

Collect accumulated funding fees for a position.

Liquidity Tools (requires PRIVATE_KEY)

mint_stake_lp

Deposit tokens into the TLP liquidity pool to mint TLP, with optional staking.

stake_lp

Stake existing TLP tokens to earn rewards.

unstake

Begin unstaking TLP. This starts an unlock countdown — you must wait for the cooldown period to complete before calling redeem_tlp → claim. The cooldown duration is subject to change; check the official Typus documentation for the current value.

To check when your cooldown ends, call get_user_stake and look at deactivating_shares[].unlocked_ts_ms.

unstake_redeem

Combine unstake and redeem into a single transaction. Note that the cooldown period still applies — you must wait for it to complete before calling claim. The cooldown duration is subject to change; check the official Typus documentation for the current value.

⚠️ This does not return tokens to your wallet directly — you must wait for the cooldown period, then call claim to receive the underlying collateral. To check when your cooldown ends, call get_user_stake and look at deactivating_shares[].unlocked_ts_ms.

redeem_tlp

Redeem TLP tokens for underlying assets. Use this when:

• TLP is already in your wallet (minted with stake=false), or

• You have completed the unstake cooldown period

⚠️ This does not return tokens to your wallet directly — you must call claim afterwards. Full flow: unstake → (wait cooldown) → redeem_tlp → claim.

claim

Claim redeemed TLP tokens back as underlying collateral. This is the final step after unstake_redeem or redeem_tlp.

Claim does not require an amount — it automatically transfers all redeemed collateral to your wallet.

harvest_reward

Harvest pending staking reward tokens.

swap

Swap tokens using the Typus Perp liquidity pool.

Reference

Pool Index

Supported Tokens

Raw Integer Conversion

All amount parameters use raw integers (on-chain representation):

Workflow Examples

Open a Long with TP/SL

# 1. Open Long position
create_order: tradingToken="SUI", collateralToken="SUI", size="10000000000",
              triggerPrice="10000000000", isLong=true, collateralAmount="3000000000"

# 2. Get positionId
get_positions: address="0x..."

# 3. Set Take-Profit (TP)
create_order: tradingToken="SUI", collateralToken="SUI", size="10000000000",
              triggerPrice="500000000", isLong=false, reduceOnly=true,
              collateralAmount="0", linkedPositionId="<positionId>"

# 4. Set Stop-Loss (SL) — set BELOW current market price to avoid immediate trigger
create_order: tradingToken="SUI", collateralToken="SUI", size="10000000000",
              triggerPrice="50000000", isLong=false, isStopOrder=true, reduceOnly=true,
              collateralAmount="0", linkedPositionId="<positionId>"

# 5. Close position at market price
create_order: tradingToken="SUI", collateralToken="SUI", size="10000000000",
              triggerPrice="1", isLong=false, reduceOnly=true,
              collateralAmount="0", linkedPositionId="<positionId>"

Deposit and Withdraw Liquidity

# Deposit and stake
mint_stake_lp: collateralToken="SUI", amount="10000000000",
               poolIndex="0", stakePoolIndex="0", stake=true, isAutoCompound=false

# Withdraw — Option A: single transaction (cooldown still applies)
unstake_redeem: stakePoolIndex="0", poolIndex="0"               # Step 1: unstake + redeem
# ... wait for cooldown period ...
claim: collateralToken="SUI", poolIndex="0", stakePoolIndex="0" # Step 2: receive tokens

# Withdraw — Option B: two transactions
unstake: stakePoolIndex="0", poolIndex="0"                      # Step 1: start cooldown
# ... wait for cooldown period ...
redeem_tlp: poolIndex="0"                                       # Step 2: redeem
claim: collateralToken="SUI", poolIndex="0", stakePoolIndex="0" # Step 3: receive tokens

Important Notes

• Minimum deposit: mTLP pool requires at least ~10 SUI (or equivalent USDC). Smaller amounts will fail with deposit_amount_insufficient.

• reduceOnly orders require linkedPositionId: When closing or reducing a position with reduceOnly=true, you must provide linkedPositionId. Omitting it will fail with position_id_needed_with_reduce_only_order.

• Stop-Loss price: Set SL below your entry price for longs (above for shorts). Setting SL above the current market price will trigger it immediately and close your position.

• Withdrawal flow: unstake_redeem or redeem_tlp alone does not return tokens to your wallet. Always call claim as the final step to receive the underlying collateral.

Development

npm run build      # Compile TypeScript → dist/index.js
npm run typecheck  # Type check without building
npm start          # Run the server directly

Security

• PRIVATE_KEY is stored locally and never transmitted outside your machine

• Store it in .env or the MCP config's env block — never commit it to Git

• .env is listed in .gitignore

• For read-only use, leave PRIVATE_KEY empty — all query tools work without it