MCP (Model Context Protocol)

The MCP protocol lets LLMs like Claude interact with Suwappu as a tool provider. Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients can discover and call Suwappu's tools automatically.

Endpoint

POST https:class=class="hl-str">"hl-comment">//api.suwappu.bot/mcp

Authentication

Include your Bearer token in the Authorization header:

Authorization: Bearer suwappu_sk_YOUR_KEY

Obtain a token by registering at POST /v1/agent/register.

Protocol

All requests and responses follow JSON-RPC 2.0, using MCP protocol version 2024-11-05.

Handshake: Initialize

Before calling any tools, initialize the MCP session:

Request:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 1,
  "hl-key">"method": "initialize",
  "hl-key">"params": {}
}

Response:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 1,
  "hl-key">"result": {
    "hl-key">"protocolVersion": "2024-11-05",
    "hl-key">"capabilities": {
      "hl-key">"tools": {}
    },
    "hl-key">"serverInfo": {
      "hl-key">"name": "suwappu",
      "hl-key">"version": "0.5.0"
    }
  }
}

Discover Tools: tools/list

List all available tools and their input schemas:

Request:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 2,
  "hl-key">"method": "tools/list",
  "hl-key">"params": {}
}

Response:

Returns an array of tool definitions. See the tool reference below for all eleven tools.

Available Tools

1. get_quote

Get a swap quote for a token pair.

Parameter	Type	Required	Description
`from_token`	string	Yes	Source token symbol (e.g., "ETH")
`to_token`	string	Yes	Destination token symbol (e.g., "USDC")
`amount`	string	Yes	Amount of source token to swap
`chain`	string	No	Chain name for same-chain swaps (e.g., "base")
`from_chain`	string	No	Source chain for cross-chain swaps
`to_chain`	string	No	Destination chain for cross-chain swaps
`wallet_address`	string	No	Wallet address for the quote
`slippage`	string	No	Slippage tolerance (e.g., "0.5" for 0.5%)

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 3,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "get_quote",
    "hl-key">"arguments": {
      "hl-key">"from_token": "ETH",
      "hl-key">"to_token": "USDC",
      "hl-key">"amount": "0.5",
      "hl-key">"chain": "base"
    }
  }
}

2. execute_swap

Execute a previously obtained quote.

Parameter	Type	Required	Description
`quote_id`	string	Yes	Quote ID from a `get_quote` response
`wallet_address`	string	Yes	Wallet address to execute the swap from

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 4,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "execute_swap",
    "hl-key">"arguments": {
      "hl-key">"quote_id": "q_abc123",
      "hl-key">"wallet_address": "0x1234567890abcdef1234567890abcdef12345678"
    }
  }
}

3. get_portfolio

Check token balances for a wallet.

Parameter	Type	Required	Description
`wallet_address`	string	Yes	Wallet address to check
`chain`	string	No	Filter by specific chain

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 5,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "get_portfolio",
    "hl-key">"arguments": {
      "hl-key">"wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
      "hl-key">"chain": "base"
    }
  }
}

4. get_prices

Get current prices for one or more tokens.

Parameter	Type	Required	Description
`symbols`	string	Yes	Comma-separated token symbols (e.g., "ETH,BTC,SOL")

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 6,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "get_prices",
    "hl-key">"arguments": {
      "hl-key">"symbols": "ETH,BTC,SOL"
    }
  }
}

5. list_chains

List all supported blockchain networks. No parameters required.

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 7,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "list_chains",
    "hl-key">"arguments": {}
  }
}

6. list_tokens

Search and list available tokens.

Parameter	Type	Required	Description
`chain`	string	No	Filter tokens by chain
`search`	string	No	Search by token name or symbol

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 8,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "list_tokens",
    "hl-key">"arguments": {
      "hl-key">"chain": "base",
      "hl-key">"search": "USDC"
    }
  }
}

7. get_tempo_tokens

Get the TIP-20 token list on Tempo mainnet (chain ID 4217). Includes USD-denominated stablecoins.

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 9,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "get_tempo_tokens",
    "hl-key">"arguments": {}
  }
}

8. browse_mpp_directory

Browse the Micropayment Protocol (MPP) service directory. Discover available services and their payment requirements.

Parameter	Type	Required	Description
`category`	string	No	Filter by service category

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 10,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "browse_mpp_directory",
    "hl-key">"arguments": {
      "hl-key">"category": "ai"
    }
  }
}

9. predict_markets

Search and browse prediction markets on Polymarket with live prices and volumes.

Parameter	Type	Required	Description
`query`	string	No	Search term
`category`	string	No	Filter by category

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 11,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "predict_markets",
    "hl-key">"arguments": {
      "hl-key">"category": "crypto"
    }
  }
}

10. predict_market_detail

Get detailed market information with live CLOB midpoint prices for each outcome.

Parameter	Type	Required	Description
`market_id`	string	Yes	Polymarket condition ID

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 12,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "predict_market_detail",
    "hl-key">"arguments": {
      "hl-key">"market_id": "0x1234abcd..."
    }
  }
}

11. perps_markets

List available perpetual futures markets on HyperLiquid with current prices and funding rates.

Example call:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 13,
  "hl-key">"method": "tools/call",
  "hl-key">"params": {
    "hl-key">"name": "perps_markets",
    "hl-key">"arguments": {}
  }
}

Response Format

All tools/call responses return content as an array of parts:

{
  "hl-key">"jsonrpc": "2.0",
  "hl-key">"id": 3,
  "hl-key">"result": {
    "hl-key">"content": [
      {
        "hl-key">"type": "text",
        "hl-key">"text": "{\"quote_id\":\"q_abc123\",\"from_token\":\"ETH\",\"to_token\":\"USDC\",\"from_amount\":\"0.5\",\"to_amount\":\"1247.50\",\"chain\":\"base\",\"expires_at\":\"2026-03-07T12:05:00Z\"}"
      }
    ]
  }
}

The text field contains a JSON string. Parse it to access the structured data.

npm Package (Local stdio Server)

For local MCP setups, install the @suwappu/mcp-server npm package:

-kw">npm install -g @suwappu/mcp-server

Run directly:

SUWAPPU_API_KEY=suwappu_sk_YOUR_KEY npx @suwappu/mcp-server

The stdio server connects to the Suwappu API and exposes the same eleven tools as the remote endpoint. Use this when your MCP client requires a local process (e.g., Claude Desktop with stdio transport).

Claude Desktop Configuration

Add Suwappu as an MCP server in your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "hl-key">"mcpServers": {
    "hl-key">"suwappu": {
      "hl-key">"url": "https://api.suwappu.bot/mcp",
      "hl-key">"headers": {
        "hl-key">"Authorization": "Bearer suwappu_sk_YOUR_KEY"
      }
    }
  }
}

Alternatively, use the local stdio server:

{
  "hl-key">"mcpServers": {
    "hl-key">"suwappu": {
      "hl-key">"command": "npx",
      "hl-key">"args": ["-y", "@suwappu/mcp-server"],
      "hl-key">"env": {
        "hl-key">"SUWAPPU_API_KEY": "suwappu_sk_YOUR_KEY"
      }
    }
  }
}

After saving the config and restarting Claude Desktop, you can ask Claude to interact with Suwappu directly:

"Get me a quote for swapping 1 ETH to USDC on Base"
"What's the price of ETH and BTC?"
"Show my portfolio on 0xabc..."
"What chains does Suwappu support?"

Claude will automatically discover the available tools and call them on your behalf.

Full Example: Quote Flow with curl

-str">"hl-comment"># Step 1: Initialize
-kw">curl -X POST https://api.suwappu.bot/mcp \
  -H -str">"Content-Type: application/json" \
  -H -str">"Authorization: Bearer suwappu_sk_YOUR_KEY" \
  -d -str">'{-str">"jsonrpc":-str">"2.0",-str">"id":1,-str">"method":-str">"initialize",-str">"params":{}}'

-str">"hl-comment"># Step 2: List available tools
-kw">curl -X POST https://api.suwappu.bot/mcp \
  -H -str">"Content-Type: application/json" \
  -H -str">"Authorization: Bearer suwappu_sk_YOUR_KEY" \
  -d -str">'{-str">"jsonrpc":-str">"2.0",-str">"id":2,-str">"method":-str">"tools/list",-str">"params":{}}'

-str">"hl-comment"># Step 3: Get a quote
-kw">curl -X POST https://api.suwappu.bot/mcp \
  -H -str">"Content-Type: application/json" \
  -H -str">"Authorization: Bearer suwappu_sk_YOUR_KEY" \
  -d -str">'{
    -str">"jsonrpc":-str">"2.0",-str">"id":3,-str">"method":-str">"tools/call",
    -str">"params":{
      -str">"name":-str">"get_quote",
      -str">"arguments":{
        -str">"from_token":-str">"ETH",
        -str">"to_token":-str">"USDC",
        -str">"amount":-str">"0.5",
        -str">"chain":-str">"base"
      }
    }
  }'