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

---

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: ``bash cp .env.example .env ``

2. Edit .env and fill in your private key: ``env 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.

| Parameter | Required | Description | |-----------|----------|-------------| | address | Yes | Sui wallet address (0x...) |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | address | Yes | Sui wallet address (0x...) |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | address | Yes | Sui wallet address (0x...) |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | tradingToken | Yes | The base token to trade. See Supported Tokens. | | collateralToken | Yes | Token used as collateral. Supported: USDC, SUI | | size | Yes | Position size as a raw integer (amount × 10^size_decimal). Use get_markets to find size_decimal for the token. | | triggerPrice | Yes | Order trigger price as a raw integer (USD price × 10^8). e.g. $65,000 = 6500000000000 | | isLong | Yes | true = Long position, false = Short position | | collateralAmount | Yes | Collateral amount as a raw integer. USDC has 6 decimals (10 USDC = 10000000), SUI has 9 decimals (5 SUI = 5000000000). | | isStopOrder | No | true = stop order attached to an existing position. false = regular open/limit order. Default: false | | reduceOnly | No | true = can only reduce an existing position. false = can open or increase. Default: false | | linkedPositionId | No | Position ID to attach this order to. Required when isStopOrder is true. Use get_positions to find position IDs. | | dryRun | No | true = simulate without submitting. Default: false |

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.

| Parameter | Required | Description | |-----------|----------|-------------| | orderId | Yes | The order ID to cancel. Use get_orders to find order IDs. | | marketIndex | Yes | The market index the order belongs to. Use get_orders to find the marketIndex for each order. |

---

`increase_collateral`

Add more collateral to an existing position.

| Parameter | Required | Description | |-----------|----------|-------------| | positionId | Yes | The position ID to add collateral to. Use get_positions to find position IDs. | | amount | Yes | Collateral amount as a raw integer (token units × 10^decimals). | | marketIndex | Yes | The market index the position belongs to. Use get_positions to find the marketIndex for each position. |

---

`release_collateral`

Withdraw excess collateral from an existing position.

| Parameter | Required | Description | |-----------|----------|-------------| | positionId | Yes | The position ID to release collateral from. Use get_positions to find position IDs. | | amount | Yes | Amount to release as a raw integer (token units × 10^decimals). | | marketIndex | Yes | The market index the position belongs to. Use get_positions to find the marketIndex for each position. |

---

`collect_funding_fee`

Collect accumulated funding fees for a position.

| Parameter | Required | Description | |-----------|----------|-------------| | positionId | Yes | The position ID to collect funding fees from. Use get_positions to find position IDs. | | marketIndex | Yes | The market index the position belongs to. Use get_positions to find the marketIndex for each position. |

---

Liquidity Tools (requires `PRIVATE_KEY`)

---

`mint_stake_lp`

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

| Parameter | Required | Description | |-----------|----------|-------------| | collateralToken | Yes | Token to deposit. e.g. USDC, SUI | | amount | Yes | Amount to deposit as a raw integer (token units × 10^decimals). | | poolIndex | Yes | LP pool index. 0 = mTLP pool (accepts SUI, USDC), 1 = iTLP pool (accepts USDC, for TYPUS market). | | stakePoolIndex | Yes | Stake pool index. 0 = mTLP stake pool, 1 = iTLP stake pool. Must match poolIndex. | | stake | Yes | true = automatically stake the minted TLP after deposit. false = receive TLP without staking. | | isAutoCompound | Yes | true = enable auto-compounding of staking rewards. false = rewards accumulate without compounding. |

---

`stake_lp`

Stake existing TLP tokens to earn rewards.

| Parameter | Required | Description | |-----------|----------|-------------| | amount | Yes | Amount of TLP to stake as a raw integer (TLP units × 10^9). | | stakePoolIndex | Yes | Stake pool index. 0 = mTLP stake pool, 1 = iTLP stake pool. |

---

`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.

| Parameter | Required | Description | |-----------|----------|-------------| | stakePoolIndex | Yes | Stake pool index. 0 = mTLP stake pool, 1 = iTLP stake pool. | | poolIndex | Yes | LP pool index. 0 = mTLP pool, 1 = iTLP pool. Must match stakePoolIndex. | | share | No | Amount of shares to unstake as a raw integer. Omit to unstake all. |

---

`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.

| Parameter | Required | Description | |-----------|----------|-------------| | poolIndex | Yes | LP pool index. 0 = mTLP pool, 1 = iTLP pool. | | share | No | Amount of TLP shares to redeem as a raw integer. Omit to redeem all. |

---

`claim`

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

| Parameter | Required | Description | |-----------|----------|-------------| | collateralToken | Yes | The collateral token to receive. e.g. SUI, USDC | | poolIndex | Yes | LP pool index. 0 = mTLP pool, 1 = iTLP pool. | | stakePoolIndex | Yes | Stake pool index. 0 = mTLP stake pool, 1 = iTLP stake pool. Must match poolIndex. |

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

---

`harvest_reward`

Harvest pending staking reward tokens.

| Parameter | Required | Description | |-----------|----------|-------------| | stakePoolIndex | Yes | Stake pool index. 0 = mTLP stake pool, 1 = iTLP stake pool. |

---

`swap`

Swap tokens using the Typus Perp liquidity pool.

| Parameter | Required | Description | |-----------|----------|-------------| | fromToken | Yes | Token to swap from. e.g. USDC, SUI | | toToken | Yes | Token to swap to. e.g. SUI, USDC | | amount | Yes | Amount to swap as a raw integer (fromToken units × 10^decimals). | | perpIndex | Yes | Perp market index. 0 = main market (SUI, BTC, ETH, etc.), 1 = TYPUS market. |

---

Reference

Pool Index

| Index | LP Pool | Stake Pool | Accepted Collateral | Markets | |-------|---------|------------|---------------------|---------| | 0 | mTLP | mTLP stake | SUI, USDC | All markets except TYPUS | | 1 | iTLP | iTLP stake | USDC | TYPUS market only |

Supported Tokens

| Token | Symbol to use | Decimals | |-------|--------------|----------| | SUI | SUI | 9 | | Bitcoin | WBTC | 8 | | Ethereum | wETH | 8 | | Solana | wSOL | 8 | | Aptos | wAPT | 8 | | DEEP | DEEP | 6 | | WAL | WAL | 9 | | DOGE | DOGE | 8 | | HYPE | HYPE | 8 | | XRP | XRP | 8 | | Japanese Yen | JPY | 9 | | Gold | XAU | 9 | | Silver | XAG | 9 | | US Oil | USOIL | 9 | | QQQ (ETF) | QQQX | 9 | | S&P 500 (ETF) | SPYX | 9 | | TYPUS | TYPUS | 9 | | USDC (collateral) | USDC | 6 |

Raw Integer Conversion

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

| Value | Formula | Example | |-------|---------|---------| | Token amount | amount × 10^decimals | 10 USDC = 10000000 (6 decimals) | | Position size | amount × 10^size_decimal | Use get_markets to find size_decimal |

---

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

typus-perp-mcp

typus-perp-mcp

Prerequisites

Installation

Private Key Setup

Enable in Claude

Claude Code

Claude Desktop

Tools

Query Tools (read-only, no wallet required)

get_markets

get_lp_pools

get_stake_pools

get_positions

get_orders

get_user_stake

Trading Tools (requires PRIVATE_KEY)

create_order

cancel_order

increase_collateral

release_collateral

collect_funding_fee

Liquidity Tools (requires PRIVATE_KEY)

mint_stake_lp

stake_lp

unstake

unstake_redeem

redeem_tlp

claim

harvest_reward

swap

Reference

Pool Index

Supported Tokens

Raw Integer Conversion

Workflow Examples

Open a Long with TP/SL

Deposit and Withdraw Liquidity

Important Notes

Development

Security

Score

Proud of your score? Add this badge to your README.

typus-perp-mcp FAQ

How do I install typus-perp-mcp?

Is typus-perp-mcp an official MCP server?

Related MCP servers

Related guides

`get_markets`

`get_lp_pools`

`get_stake_pools`

`get_positions`

`get_orders`

`get_user_stake`

Trading Tools (requires `PRIVATE_KEY`)

`create_order`

`cancel_order`

`increase_collateral`

`release_collateral`

`collect_funding_fee`

Liquidity Tools (requires `PRIVATE_KEY`)

`mint_stake_lp`

`stake_lp`

`unstake`

`unstake_redeem`

`redeem_tlp`

`claim`

`harvest_reward`

`swap`