Install the official MCP package
One versioned package contains the server, sandbox, and four reference agents.
connect_wallet derives the deployed Polymarket developer address when it is omitted.npm install -g https://www.polmexbot.com/downloads/polmexbot-agent-integration-1.2.0.tgz
Register polmexbot-mcp as a stdio MCP server in your MCP-compatible client. Use the client's environment-secret support rather than putting tokens in command arguments.
Test the complete loop without a wallet
The in-memory sandbox makes no network requests and cannot place real orders.
POLMEXBOT_SANDBOX=true polmexbot-mcp
The sandbox starts with 100 simulated pUSD, no positions, and no trade history. It supports balance, readiness, configuration preview and validation, simulated wallet login, configuration and start, state/logs, and stop.
sandbox:true.Connect live read-only access
A human establishes the account first; the agent receives only its bearer token.
Connect through Settings or the documented /api/wallet/connect exchange, then store the returned account token in your MCP client's secret environment. Connecting alone never starts trading.
{
"mcpServers": {
"polmexbot": {
"command": "polmexbot-mcp",
"env": {
"POLMEXBOT_BASE_URL": "https://www.polmexbot.com",
"POLMEXBOT_TOKEN": "existing-account-bearer-token"
}
}
}
}| Tool | Purpose |
|---|---|
get_account | Safe account, current configuration, recent trades, and statistics. |
get_balance | pUSD, USDC.e, positions value, bankroll, warnings, and restrictions. |
get_bot_state · get_positions | Requested and actual engine state, freshness, and open positions. |
get_trades · get_logs | Persisted results, engine events, skips, and errors. |
check_readiness | Wallet deployment, pairing, collateral, and readiness without a transaction. |
preview_config | Validated proposed configuration, exact diff, warnings, and previewHash; never saves. |
get_public_prices | Public crypto prices without account credentials. |
Choose supervised or fully autonomous trading
Both modes validate configuration and wallet readiness before starting the existing engine.
Autonomous: agent connects the wallet and starts by itself
Enable POLMEXBOT_AUTONOMOUS=true. No initial bearer token or approval token is needed.
{
"mcpServers": {
"polmexbot": {
"command": "polmexbot-mcp",
"env": {
"POLMEXBOT_BASE_URL": "https://www.polmexbot.com",
"POLMEXBOT_AUTONOMOUS": "true"
}
}
}
}- Call
connect_walletwithprivateKey. The optionaldeveloperAddressis derived automatically when omitted. - The tool caches only the returned bearer token in memory; neither the private key nor token appears in its result.
- Call
preview_config, thenapply_configwith the unchanged hash. No separate approval token is required. - Make an empty-patch preview and call
start_botwith its fresh hash. Start still requires a successful readiness check. - Monitor state, positions, trades, and logs. Use
stop_botat any time.
Direct EOA: trade without the Polymarket website
If the private key's EOA already holds pUSD on Polygon, select walletMode:"eoa". The EOA becomes maker, signer, and funder with signature type 0. No developer address or Polymarket account-wallet setup is needed, although orders still use Polymarket's CLOB and exchange contracts. Never use test or example keys in live mode.
1. Transfer pUSD to the EOA; keep POL for approval gas.
2. connect_wallet({ privateKey, walletMode: "eoa" })
Do not send developerAddress.
3. prepare_eoa_wallet({ approve: false })
Inspect pUSD, POL, allowance, cap, gas, and nextAction.
4. Only if needed: prepare_eoa_wallet({ approve: true })
Broadcast the exact capped pUSD approval and wait for confirmation.
5. check_readiness → preview_config → apply_config
→ empty preview_config → start_bot.approve:false never broadcasts. approve:true only approves the exact pUSD cap (configured bankroll unless amountUsd is supplied); it does not wrap, swap, or start the bot. Supervised live mode also requires approvalToken for that transaction. Start fails closed without pUSD or allowance. Selling outcome tokens may require separate ERC-1155 approvals.
Supervised: bearer token plus owner approval
{
"mcpServers": {
"polmexbot": {
"command": "polmexbot-mcp",
"env": {
"POLMEXBOT_BASE_URL": "https://www.polmexbot.com",
"POLMEXBOT_TOKEN": "existing-account-bearer-token",
"POLMEXBOT_ENABLE_CONTROLS": "true",
"POLMEXBOT_APPROVAL_TOKEN": "owner-created-approval-secret"
}
}
}
}- Call
preview_configand show the owner the exact diff. - Pass its
previewHashand the owner-provided approval token toapply_config. - For
start_bot, make an empty-patch preview, then pass its hash and approval token after a fresh readiness check. - Use
stop_botto disable new activity. No approval token is required for stop.
maxPerTrade < initialBuy.Run the reference agents
Unpack the same versioned package to inspect and run working examples.
mkdir polmexbot-agent && cd polmexbot-agent curl -fsSLO https://www.polmexbot.com/downloads/polmexbot-agent-integration-1.2.0.tgz tar -xzf polmexbot-agent-integration-1.2.0.tgz cd package npm install # Read-only account monitor node examples/read-only-monitor.mjs --sandbox # Read-only configuration preview node examples/supervised-agent.mjs --sandbox # Full simulated preview → approval → start → logs → stop node examples/supervised-agent.mjs --sandbox --approve # Autonomous key login → configure → start → logs → stop node examples/autonomous-agent.mjs --sandbox # Direct-EOA preparation → simulated approval → configure → start → stop node examples/autonomous-agent.mjs --sandbox --eoa # State-change alerts; optionally set ALERT_WEBHOOK_URL node examples/alert-agent.mjs --sandbox
The supervised and autonomous examples stop immediately after their demonstrations unless --keep-running is supplied. For a live autonomous run, set POLMEXBOT_PRIVATE_KEY in the environment and add --execute. The alert agent supports ALERT_WEBHOOK_URL, ALERT_INTERVAL_MS, and ALERT_ITERATIONS.
Machine discovery and documentation
Give agents structured contracts instead of asking them to scrape HTML.
| Resource | Address |
|---|---|
| OpenAPI 3.1 | polmexbot.com/openapi.json |
| LLM discovery | polmexbot.com/llms.txt |
| Markdown integration guide | polmexbot.com/agents.md |
| REST and authentication guide | polmexbot.com/agents |
| OAuth resource metadata | /.well-known/oauth-protected-resource |
| Versioned integration package | Download tarball |
ok; many failures use HTTP 200 with ok:false. Readiness can be ok:true with ready:false. botActive is only the requested flag — confirm freshness and fills through state, trades, and logs.