# Polexbot agent integration

Production base URL: `https://www.polexbotpro.pro`

Polexbot exposes wallet connection, account reading, strategy configuration, engine start/stop, and monitoring. It does not expose arbitrary buy, sell, or order placement. An agent directs the existing strategy engine; the engine evaluates markets and signs orders.

## Discovery

- OpenAPI 3.1: `https://www.polexbotpro.pro/openapi.json`
- MCP, autonomous mode, and sandbox guide: `https://www.polexbotpro.pro/agents/mcp`
- Human API guide: `https://www.polexbotpro.pro/agents`
- OAuth resource metadata: `https://www.polexbotpro.pro/.well-known/oauth-protected-resource`

## MCP installation

Node.js 20 or newer is required.

```bash
npm install -g https://www.polexbotpro.pro/downloads/polexbot-agent-integration-1.1.0.tgz
```

Run the no-network, no-wallet sandbox:

```bash
POLEXBOT_SANDBOX=true polexbot-mcp
```

Register the command as a stdio MCP server in an MCP-compatible client. Do not put credentials in command arguments; use the client's environment-secret support.

## Autonomous wallet login and start

Use this mode when the agent is explicitly trusted with a dedicated wallet's private key and should perform the complete flow itself:

```json
{
  "mcpServers": {
    "polexbot": {
      "command": "polexbot-mcp",
      "env": {
        "POLEXBOT_BASE_URL": "https://www.polexbotpro.pro",
        "POLEXBOT_AUTONOMOUS": "true"
      }
    }
  }
}
```

No initial bearer token or approval token is needed. The agent calls:

1. `connect_wallet` with `privateKey` and optional `developerAddress`. If the address is omitted, the tool derives the deployed Polymarket wallet automatically. The returned bearer token is cached only in memory; neither key nor token is returned in the tool result.
2. `check_readiness` and `preview_config` to validate the wallet and proposed settings.
3. `apply_config` with the patch and unchanged `previewHash`.
4. `preview_config` with an empty patch, then `start_bot` with the fresh `previewHash`. Start also requires a fresh readiness pass.
5. `get_bot_state`, `get_positions`, `get_trades`, and `get_logs` to confirm actual activity. `stop_bot` stops new activity but does not sell positions.

Autonomous `apply_config` and `start_bot` do not require a separate approval token. The private key itself is the wallet owner's authorization. The engine retains it server-side for signing. Use only a dedicated limited-funds wallet, protect MCP client logs because clients may retain tool arguments, and never enable this mode for an untrusted agent.

Autonomous reference agent:

```bash
POLEXBOT_PRIVATE_KEY=... node examples/autonomous-agent.mjs --execute
```

The live example stops after its demonstration unless `--keep-running` is supplied. Without `--execute`, it connects and previews only. `node examples/autonomous-agent.mjs --sandbox` runs the entire flow without network, credentials, or real orders.

## Live bearer-token mode

```json
{
  "mcpServers": {
    "polexbot": {
      "command": "polexbot-mcp",
      "env": {
        "POLEXBOT_BASE_URL": "https://www.polexbotpro.pro",
        "POLEXBOT_TOKEN": "existing-account-bearer-token"
      }
    }
  }
}
```

A human can establish the account through Settings or `/api/wallet/connect`. Connecting does not start the bot. Live bearer-token mode exposes only read-only tools by default.

## Read-only tools

- `get_server_info`: integration mode and documentation links; no credentials required.
- `get_public_prices`: public crypto prices; no credentials required.
- `get_account`: safe account, current configuration, recent trades, and statistics.
- `get_balance`: collateral, bankroll, positions value, deployment, warnings, and restrictions.
- `get_bot_state`: requested and fresh engine state, positions, and results.
- `get_positions`: open positions from current engine state, including freshness metadata.
- `get_trades`: persisted trades and aggregate statistics.
- `get_logs`: engine events, skips, errors, and results.
- `check_readiness`: wallet deployment, pairing, collateral, and readiness without a transaction.
- `preview_config`: validates a partial patch and returns current config, proposed config, exact diff, warnings, errors, and `previewHash`. This never saves.

## Supervised live controls

For human-approved bearer-token control instead of autonomous mode:

```json
{
  "mcpServers": {
    "polexbot": {
      "command": "polexbot-mcp",
      "env": {
        "POLEXBOT_BASE_URL": "https://www.polexbotpro.pro",
        "POLEXBOT_TOKEN": "existing-account-bearer-token",
        "POLEXBOT_ENABLE_CONTROLS": "true",
        "POLEXBOT_APPROVAL_TOKEN": "owner-created-approval-secret"
      }
    }
  }
}
```

- `apply_config` requires the patch, its unchanged `previewHash`, and `approvalToken`.
- `start_bot` requires an empty-patch configuration preview, its unchanged `previewHash`, `approvalToken`, and a fresh readiness pass.
- `stop_bot` does not require the approval token. It disables new activity but does not liquidate positions.

Show the owner the exact configuration diff before requesting the approval token. Do not store the approval token in a system prompt or source repository.

## Sandbox reference agents

```bash
mkdir polexbot-agent && cd polexbot-agent
curl -fsSLO https://www.polexbotpro.pro/downloads/polexbot-agent-integration-1.1.0.tgz
tar -xzf polexbot-agent-integration-1.1.0.tgz
cd package
npm install
node examples/supervised-agent.mjs --sandbox --approve
node examples/autonomous-agent.mjs --sandbox
```

Other examples:

```bash
node examples/read-only-monitor.mjs --sandbox
node examples/alert-agent.mjs --sandbox
```

`alert-agent.mjs` can post state changes to `ALERT_WEBHOOK_URL`. Set `ALERT_INTERVAL_MS` and `ALERT_ITERATIONS` for continuous polling.

## API behavior

Authenticated endpoints use `Authorization: Bearer <token>`. Public market endpoints need no authentication. Agents may also use `/api/wallet/derive-address` and `/api/wallet/connect` directly over HTTPS to establish a token. Always check `ok`; many validation and readiness failures use HTTP 200 with `ok:false`. Readiness can return `ok:true` with `ready:false`. A green `botActive` flag does not prove engine freshness or a trade. Inspect `running`, `stale`, `age_seconds`, wallet link, restrictions, logs, and persisted trades.

Configuration supports `constellation`, `aistrat`, `aces`, and `custom` strategies. The MCP validator allows documented fields only and enforces ranges, preset expansion, entry bands, `maxPerTrade >= initialBuy`, affordability, and reviewed configuration hashes.

## Safety

Use a dedicated limited-funds wallet. Keep credentials in a secret manager and protect MCP tool-argument logs. Use supervised approval or an explicit autonomous trust decision before configuration and start. Set hard sizing, concurrency, and bankroll limits. Run only one engine per wallet and one controlling writer per account. Keep stop available. Stopping is not selling; inspect open positions and market resolution before reporting an account as flat.
