conviction-mcp

Instructions

Implementation Reference

• mcp/src/index.ts:941-998 (handler)

  The 'enter_position' tool handler, which validates the API key and sends a request to the server to place a bet in a pool on-chain.

  // ── Tool: place_bet ──
  
  server.tool(
    "enter_position",
    "Enter an open pool with a position on one side of a token pair. Requires an agent API key (from create_agent). Earlier entries earn a higher conviction multiplier.",
    {
      api_key: z.string().optional().describe("Agent API key from create_agent (starts with cfm_). Auto-filled from saved credentials if omitted."),
      token_a: z.string().describe("First token in the pair (e.g. BTC)"),
      token_b: z.string().describe("Second token in the pair (e.g. ETH)"),
      side: z.string().describe("Which token to pick (e.g. BTC or ETH)"),
      amount: z.number().min(1).default(1).describe("Amount in USDC to commit (minimum 1)"),
    },
    async ({ api_key, token_a, token_b, side, amount }) => {
      const resolvedKey = api_key || getDefaultApiKey();
      if (!resolvedKey) {
        return {
          content: [{ type: "text", text: "No API key found. Create an agent first with `create_agent`, or pass an `api_key`." }],
          isError: true,
        };
      }
  
      const result = (await apiPost("agent-place-bet", {
        agentApiKey: resolvedKey,
        tokenAId: token_a.toUpperCase(),
        tokenBId: token_b.toUpperCase(),
        selectedSide: side.toUpperCase(),
        amountUsdc: amount,
      })) as any;
  
      if (!result.success) {
        const rawError = result.error || "Unknown error";
        return {
          content: [{ type: "text", text: `Entry failed: ${humanizeError(rawError)}` }],
          isError: true,
        };
      }
  
      return {
        content: [
          {
            type: "text",
            text: [
              "# Entry Placed",
              "",
              `**Pool:** ${token_a.toUpperCase()}-${token_b.toUpperCase()}`,
              `**Side:** ${side.toUpperCase()}`,
              `**Amount:** $${amount}`,
              `**Conviction Multiplier:** ${result.convictionMultiplier?.toFixed(3) ?? "1.000"}`,
              `**Win Probability:** ${result.winProbability?.toFixed(1) ?? "?"}%`,
              result.explorerUrl ? `**Transaction:** ${result.explorerUrl}` : "",
            ]
              .filter(Boolean)
              .join("\n"),
          },
        ],
      };
    }
  );