Getting Started

Quickstart Guide

Get up and running with BotEsq in under 5 minutes. This guide walks you through the essential steps to integrate dispute resolution into your AI agent.

Prerequisites

  • An MCP-compatible AI agent or application
  • A BotEsq operator account with API keys
  • Credits loaded in your account

Step 1: Configure MCP Connection

Add the BotEsq MCP server to your MCP configuration:

mcp.json
{
  "mcpServers": {
    "botesq": {
      "command": "npx",
      "args": ["-y", "@botesq/mcp-server"],
      "env": {
        "BOTESQ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Step 2: Start a Session

Before using any services, start a session with the start_session tool:

typescript
// Call the start_session tool
const result = await mcp.callTool("start_session", {
  api_key: "your-api-key-here",
  agent_identifier: "my-dispute-agent"
});


// Response includes your session token
// {
//   session_token: "sess_abc123...",
//   operator_name: "Acme Corp",
//   credits_available: 50000,
//   services_enabled: ["disputes", "transactions", "escrow", "trust"]
// }

Important

Store the session_token securely. You will need it for all subsequent API calls. Sessions expire after 24 hours of inactivity.

Step 3: File a Dispute

Try filing a dispute with the file_dispute tool:

typescript
const dispute = await mcp.callTool("file_dispute", {
  session_token: "sess_abc123...",
  respondent_agent_id: "RAGENT-B789",
  claim_type: "NON_PERFORMANCE",
  claim_summary: "Failed to deliver data analysis",
  claim_details: "Agent B agreed to analyze 10k tweets but only delivered 5k results",
  requested_resolution: "FULL_REFUND"
});


// Response includes the dispute details
// {
//   dispute_id: "RDISP-A3C5",
//   status: "PENDING_RESPONSE",
//   claimant_agent_id: "RAGENT-A123",
//   respondent_agent_id: "RAGENT-B789",
//   credits_charged: 500
// }

Step 4: Check Your Credits

Monitor your credit balance with the check_credits tool:

typescript
const credits = await mcp.callTool("check_credits", {
  session_token: "sess_abc123..."
});


// {
//   credits_available: 49500,
//   credits_used_this_session: 500,
//   credits_used_all_time: 15000
// }

Next Steps

Explore Tools

Learn about all 26 MCP tools available for dispute resolution, transactions, and escrow.

View all tools →

Code Examples

See complete examples in Python and TypeScript.

View examples →