Details and links

• Address: 5FCKLnjXSR8Dwe6AS93tnGvnAmDsnNqivvfWcjjsFEBC4i4V
• Purpose: Classification step that gives you a quality score for a given content creator and tells you the likelihood that the user is a bot

Reference client

cURL against the REST API

Score a single user by entityId

curl --location '<https://real-trump.fun/torus/bot-detector>' \\
--header 'Content-Type: application/json' \\
--data '{
  "entityId": "1894281116796030977",
  "platform": "x",
  "model": "openai/gpt-4.1-mini",
  "options": {
    "forceRecheck": true
  }
}'

Score a single user by entityUsername

curl --location '<https://real-trump.fun/torus/bot-detector>' \\
--header 'Content-Type: application/json' \\
--data '{
  "entityUsername": "elonmusk",
  "platform": "x",
  "model": "openai/gpt-4.1-mini",
  "options": {
    "forceRecheck": true
  }
}'

Score many users by entityIds

curl --location '<https://real-trump.fun/torus/bot-detector/batch>' \\
--header 'Content-Type: application/json' \\
--header 'Authorization: Basic dG9ydXM6eGdQdTRnSFRSMlJhR1hAbTVC' \\
--data '{
  "entityIds": ["44196397","1894281116796030977","25073877","129048120948120841084012841084012849012"],
  "platform": "x",
  "model": "openai/gpt-4.1-mini",
  "options": {
    "forceRecheck": true
  }
}'

Score many users by entityUsernames

curl --location '<https://real-trump.fun/torus/bot-detector/batch>' \\
--header 'Content-Type: application/json' \\
--header 'Authorization: Basic dG9ydXM6eGdQdTRnSFRSMlJhR1hAbTVC' \\
--data '{
  "entityUsernames": ["elonmusk", "pvpvai", "oefoiehfoifoiweonv390239802nfsndpovnwpof39", "bigwheel_boom"],
  "platform": "x",
  "model": "openai/gpt-4.1-mini",
  "options": {
    "forceRecheck": true
  }
}'

Torus AgentClient

<aside> ⛔

The AgentServer variation of this is not deployed currently due to the NODE_URL hardcoding bug in the Torus SDK, so the below code will not work against real-trump.fun. This comment will be removed once the AgentServer variation is deployed

The REST API for this service, however, is deployed and available (it’s a hono server not a Torus AgentServer), see the above cURLs for how to interact with it.

</aside>

// This is a reference Torus SDK client for the bot detection service
import { AgentClient, Keypair } from "@torus-network/sdk/agent-client";
import { z } from "zod";

export const botDetectorResponseSchema = z.object({
  entityId: z.string(),
  qualityScore: z.number(),
  botLikelihood: z.number(),
  error: z.string().nullable(),
});

export type BotDetectorResponse = z.infer<typeof botDetectorResponseSchema>;

export class BotDetectorClient {
  private client: AgentClient;

  constructor(mnemonic: string, baseUrl: string) {
    const keypair = new Keypair(mnemonic);
    this.client = new AgentClient({ keypair, baseUrl });
  }

  async detectBot(input: {
    entityId?: string;
    entityUsername?: string;
    options?: { forceRecheck?: boolean };
    platform?: string;
    model?: string;
  }) {
    const response = await this.client.call({
      endpoint: "bot-detector",
      data: input,
    });

    if (response.success) {
      return {
        success: true,
        data: response.data as BotDetectorResponse,
      };
    } else {
      return {
        success: false,
        error: response.error?.message || "Failed to detect bot",
      };
    }
  }

  async detectBotBatch(input: {
    entityIds?: string[];
    entityUsernames?: string[];
    options?: { forceRecheck?: boolean };
    platform?: string;
    model?: string;
  }) {
    const response = await this.client.call({
      endpoint: "bot-detector-batch",
      data: input,
    });

    if (response.success) {
      return {
        success: true,
        results: response.data as BotDetectorResponse[],
      };
    } else {
      return {
        success: false,
        error: response.error?.message || "Failed to batch detect bots",
      };
    }
  }
}

Example usage

// This is a reference Torus SDK client for the bot detection service
import dotenv from "dotenv";
import { BotDetectorClient } from "../src/clients/bot-detector";

dotenv.config();

const BASE_URL = process.env.BASE_URL || "<http://localhost:3001>";
const TORUS_CLIENT_MNEMONIC = process.env.TORUS_CLIENT_MNEMONIC;

if (!TORUS_CLIENT_MNEMONIC) {
  throw new Error("TORUS_CLIENT_MNEMONIC is not set");
}

// Example usage
async function main() {
  if (!TORUS_CLIENT_MNEMONIC) {
    throw new Error(
      "Please set TORUS_CLIENT_MNEMONIC in your .env file to run this example."
    );
  }

  const client = new BotDetectorClient(TORUS_CLIENT_MNEMONIC, BASE_URL);

  console.log("--- Bot Detector ---");

  // Example 1: Detect a bot from a username
  const username1 = "VitalikButerin"; // a real user
  console.log(`Running: detectBot({ entityUsername: "${username1}" })`);
  const response1 = await client.detectBot({ entityUsername: username1 });
  console.log("Response:", JSON.stringify(response1, null, 2));
  console.log("---\\n");

  // Example 2: Detect a likely bot from a username
  const username2 = "pepecoin"; // a project/brand account, might have bot-like characteristics
  console.log(`Running: detectBot({ entityUsername: "${username2}" })`);
  const response2 = await client.detectBot({ entityUsername: username2 });
  console.log("Response:", JSON.stringify(response2, null, 2));
  console.log("---\\n");

  // Example 3: Batch detect bots
  const usernames = ["elonmusk", "cz_binance", "VitalikButerin"];
  console.log(
    `Running: detectBotBatch({ entityUsernames: ${JSON.stringify(usernames)} })`
  );
  const response3 = await client.detectBotBatch({
    entityUsernames: usernames,
  });
  console.log("Response:", JSON.stringify(response3, null, 2));
  console.log("---\\n");
}

main().catch((error) => {
  console.error("An error occurred:", error.message);
});