truemarkets-mcp-server

Instructions

Implementation Reference

• src/tools/trade.ts:83-142 (handler)

  The handler logic for tm_get_quote, which fetches a quote from the API and caches it.

  async ({ side, token, amount, chain, qty_unit }) => {
    // Resolve symbol
    let baseAsset = token;
    let resolvedChain = chain;
  
    if (isSymbol(token)) {
      const assets = await api.getAssets();
      const match = assets.find(
        (a) => a.symbol?.toLowerCase() === token.toLowerCase()
      );
      if (!match?.address) {
        return {
          isError: true,
          content: [{ type: "text", text: `Could not resolve symbol "${token}". Use tm_list_assets to see available tokens.` }],
        };
      }
      baseAsset = match.address;
      if (match.chain) resolvedChain = match.chain.toLowerCase() as "solana" | "base";
    }
  
    const quote = await api.createQuote({
      order_side: side,
      chain: resolvedChain,
      base_asset: baseAsset,
      quote_asset: getQuoteAsset(resolvedChain),
      qty: amount,
    });
  
    // Cache the quote so tm_execute_trade can use the same one
    cacheQuote(quote);
  
    // Compute effective price
    const qty = parseFloat(quote.qty);
    const qtyOut = parseFloat(quote.qty_out);
    const effectivePrice = side === "buy"
      ? (qty / qtyOut).toFixed(6)
      : (qtyOut / qty).toFixed(6);
  
    const output = {
      quote_id: quote.quote_id,
      side,
      token: token.toUpperCase(),
      chain: resolvedChain,
      you_pay: `${quote.qty} ${side === "buy" ? "USDC" : token.toUpperCase()}`,
      you_receive: `${quote.qty_out} ${side === "buy" ? token.toUpperCase() : "USDC"}`,
      fee: `${quote.fee} ${quote.fee_asset}`,
      effective_price: `${effectivePrice} USDC/${token.toUpperCase()}`,
      issues: quote.issues.map((i) => ({
        message: i.message,
        ...(i.balance ? { have: i.balance.actual, need: i.balance.expected } : {}),
      })),
      has_issues: quote.issues.length > 0,
      expires_in_seconds: 60,
    };
  
    return {
      content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
      structuredContent: output,
    };
  }

• src/tools/trade.ts:40-82 (registration)

  Registration and schema definition for the tm_get_quote tool.

    server.registerTool(
      "tm_get_quote",
      {
        title: "Get a trade quote",
        description: `Request a quote for buying or selling a token. Returns pricing info
  and a quote_id that can be passed to tm_execute_trade within 60 seconds.
  
  IMPORTANT: Always call this BEFORE tm_execute_trade. Inspect the quote
  (price, fee, issues) and only execute if acceptable. This solves the
  price uncertainty problem — you see the exact price you'll get.
  
  Args:
    - side ("buy" | "sell"): Trade direction
    - token (string): Token symbol (SOL, ETH) or contract address
    - amount (string): Quantity as a decimal string
    - chain ("solana" | "base"): Blockchain network (default: solana)
    - qty_unit ("base" | "quote"): What the amount represents (default: "quote" for buy, "base" for sell)
  
  Returns: {
    quote_id: string,       // Pass this to tm_execute_trade
    side, token, chain,
    you_pay: string,        // Amount + asset you send
    you_receive: string,    // Amount + asset you get
    fee: string,
    effective_price: string, // USDC per token
    issues: [],             // Any problems (e.g. insufficient balance)
    expires_in_seconds: 60
  }`,
        inputSchema: {
          side: z.enum(["buy", "sell"]).describe("Buy or sell"),
          token: z.string().describe("Token symbol or contract address"),
          amount: z.string().describe("Quantity as decimal string"),
          chain: z.enum(["solana", "base"]).default("solana").describe("Chain"),
          qty_unit: z.enum(["base", "quote"]).optional()
            .describe("What amount represents. Default: 'quote' (USDC) for buy, 'base' (token) for sell"),
        },
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: false,
          openWorldHint: true,
        },
      },