enter_position

Instructions

Implementation Reference

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

  The main handler function for the 'enter_position' tool. It resolves the API key (auto-filled from saved credentials or passed explicitly), validates inputs, calls the 'agent-place-bet' API, and returns a formatted response with conviction multiplier and win probability.

  // ── 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"),
          },
        ],
      };
    }
  );

• mcp/src/index.ts:943-952 (schema)

  Input schema for the 'enter_position' tool using Zod. Defines params: api_key (optional string), token_a (required string), token_b (required string), side (required string), amount (number, min 1, default 1).

  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)"),
    },

• mcp/src/index.ts:943-945 (registration)

  Registration of the 'enter_position' tool via server.tool() with its name, description, schema, and handler. The tool is described as entering an open pool with a position on one side of a token pair.

  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.",

• mcp/src/index.ts:954-960 (helper)

  API key resolution helper within the handler. Falls back to getDefaultApiKey() which checks CONVICTION_API_KEY env var and then the most recent saved agent credentials.

  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,
    };
  }