PolexbotAgent gateway
Menu
HomeBlogPoliticsAgentsNewSettingsOpen Dashboard →
Agent access · Live JSON API

Your agent.Your trading engine.

Connect an AI agent to Polexbot with your own Polymarket credentials. Let it read your account, configure a strategy, start and stop the bot, and monitor every result — using the same API as the dashboard.

Private keys are full wallet credentials. Use a dedicated trading wallet with only the funds you intend to allocate. Keep the key in your agent's secret manager or environment variables — never in a prompt, source repository, screenshot, or client-side web page.
01

The five-minute quickstart

From credentials to a monitored trading session. Connecting alone never starts the bot.

Read and monitorWallet balances, positions, bot state, configuration, trades, statistics, and logs.
Control the engineMerge strategy settings, run readiness checks, and explicitly start or stop trading.
Use live market dataPublic prices and market boards need no authentication or wallet key.
Not arbitrary order placementThere is no “buy this token now” endpoint. Your agent directs the existing strategy engine; the engine signs and places orders.
STEP 01Prepare the walletGet its private key, Polymarket developer address, and pUSD balance.
STEP 02ConnectPOST both credentials to receive the account's bearer token.
STEP 03Read, then configureCheck link status and balance. Save a complete, affordable strategy.
STEP 04Start and superviseExplicitly start once. Poll state and logs. Stop whenever required.
Recommended first run: connect and call only the read endpoints. Inspect the returned configuration, wallet link, balance, and restrictions before allowing your agent to change anything.
02

Connect and authenticate

The private key identifies your wallet. The developer address identifies the Polymarket account that holds and trades your funds.

CredentialWhere it goesWhat to know
privateKeyConnect request bodyA 64-character hexadecimal EOA private key, with or without 0x. The engine retains it with the account to sign orders.
proxyAddressConnect request bodyYour own 40-character Polymarket developer/profile address. This is normally different from the EOA address.
tokenAuthorization: Bearer …Returned by a successful connection. Reuse it for authenticated calls. It represents the full account session.

If you do not know the developer address, POST /api/wallet/derive-address with {"privateKey":"…"} derives the Polymarket wallet candidates and returns the deployed match. The Settings page also offers this derivation.

Use the matching pair. A key that does not control the developer address cannot trade it. Check every connection response for proxyRestricted and link. Never treat a successful HTTP response alone as proof that the wallet is ready.

Machine discovery

Agents can retrieve /.well-known/oauth-protected-resource. Protected endpoints also return a WWW-Authenticate hint on HTTP 401. The metadata points back to this documentation.

Copy-ready connection examples

These examples connect and read state only. They do not change configuration or start trading. Inject AGENT_PRIVATE_KEY and AGENT_PROXY_ADDRESS through a secret manager.

const BASE = 'https://www.polexbotpro.pro';

async function api(path, { method = 'GET', body, token } = {}) {
  const response = await fetch(BASE + path, {
    method,
    headers: {
      'Content-Type': 'application/json',
      ...(token ? { Authorization: `Bearer ${token}` } : {})
    },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(30_000)
  });
  const data = await response.json();
  if (!response.ok || data.ok === false) {
    throw new Error(`${method} ${path}: ${data.error || response.status}`);
  }
  return data;
}

const connection = await api('/api/wallet/connect', {
  method: 'POST',
  body: {
    privateKey: process.env.AGENT_PRIVATE_KEY,
    proxyAddress: process.env.AGENT_PROXY_ADDRESS
  }
});

if (connection.proxyRestricted) {
  throw new Error(`Wallet link blocked: ${JSON.stringify(connection.link)}`);
}
console.log('Connected EOA:', connection.address);
console.log('Developer address:', connection.proxy);

// Store this token as a secret. Never log it.
const token = connection.token;
const [account, balance, state] = await Promise.all([
  api('/api/me', { token }),
  api('/api/wallet/balance', { token }),
  api('/api/bot/state', { token })
]);
console.log({ balance, running: state.running, botActive: state.botActive });
import json
import os
import urllib.request

BASE = 'https://www.polexbotpro.pro'

def api(path, method='GET', body=None, token=None):
    headers = {'Content-Type': 'application/json'}
    if token:
        headers['Authorization'] = f'Bearer {token}'
    data = None if body is None else json.dumps(body).encode()
    request = urllib.request.Request(BASE + path, data=data, headers=headers, method=method)
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
    if not result.get('ok', False):
        raise RuntimeError(f"{method} {path}: {result.get('error', 'Request failed')}")
    return result

connection = api('/api/wallet/connect', 'POST', {
    'privateKey': os.environ['AGENT_PRIVATE_KEY'],
    'proxyAddress': os.environ['AGENT_PROXY_ADDRESS']
})
if connection.get('proxyRestricted'):
    raise RuntimeError(f"Wallet link blocked: {connection.get('link')}")

# Store this token as a secret. Never log it.
token = connection['token']
balance = api('/api/wallet/balance', token=token)
state = api('/api/bot/state', token=token)
print({'balance': balance, 'running': state['running'], 'botActive': state['botActive']})
# Prefer a secret manager over typing credentials into shell history.
curl --request POST 'https://www.polexbotpro.pro/api/wallet/connect' \
  --header 'Content-Type: application/json' \
  --data "{\"privateKey\":\"$AGENT_PRIVATE_KEY\",\"proxyAddress\":\"$AGENT_PROXY_ADDRESS\"}"

# Copy the returned token into the AGENT_TOKEN secret, then:
curl 'https://www.polexbotpro.pro/api/bot/state' \
  --header "Authorization: Bearer $AGENT_TOKEN"

Typical connection response

{
  "ok": true,
  "token": "…keep this secret…",
  "address": "0xYourEOA",
  "proxy": "0xYourPolymarketDeveloperAddress",
  "proxyRestricted": false,
  "link": { "status": "ok" },
  "message": "Wallet connected."
}

Reconnecting the same wallet retrieves the existing account and token. Calling POST /api/wallet/disconnect marks the wallet disconnected and stops the bot; it does not delete the account or trade history.

03

Read before you act

A reliable agent establishes wallet readiness, available funds, current configuration, and engine state before issuing any control command.

RequestUse it for
GET /api/meAccount, stored configuration, recent trades, all-time statistics, wallet status. The private key is redacted.
GET /api/wallet/balancepUSD, legacy USDC.e, POL, open-position value/cost, live bankroll, deployment, link and restriction warnings.
GET /api/bot/staterunning, botActive, live engine state, open positions, recent trades, freshness, restrictions, and notices.
GET /api/tradesUp to 200 persisted trades plus aggregate statistics.
GET /api/logsMerged live engine messages and durable trade results, including skips and errors.

Suggested polling rhythm

  • Bot state: every 10–15 seconds while supervising an active session.
  • Logs and trades: every 15–30 seconds, or immediately after a state change.
  • Balance: every 30–60 seconds and before changing sizing.
  • Configuration/account: on startup and before proposing a change; do not fetch continuously.
Understand the status fields. botActive is the requested on/off flag. running means the engine state is fresh. A running bot may still place zero trades because its strategy filters, wallet readiness, funds, or market conditions do not produce an entry.

Readiness is a separate check

POST /api/wallet/approve verifies deployment, ownership/link status, pUSD, and trading readiness. Despite its legacy name, it is a check — it does not submit an approval transaction. A response with needsWrap:true means legacy USDC.e must be wrapped to pUSD on Polymarket.

04

Configure the strategy

Configuration is merged into the existing account. Explicit values win; omitted mode/DCA fields inherit the selected preset.

Send JSON to POST /api/bot/config. The older /api/config route behaves the same way. Read the returned config object and verify it before starting.

{
  "strategy": "constellation",
  "mode": "balanced",
  "dcaMode": "off",
  "initialBuy": 5,
  "maxPerTrade": 5,
  "maxConcurrent": 2,
  "bankroll": 100,
  "minAgree": 4,
  "tradeUp": true,
  "tradeDown": true,
  "skipHours": []
}

This example limits entries to $5, disables averaging down, allows two open positions, and sets a $100 strategy bankroll. It is an example, not a recommendation or a guarantee of profit.

Available strategies

strategyBehavior and controls
constellationDefault multi-asset laggard engine across BTC, ETH, SOL, XRP, DOGE and BNB. Controls include mode, entry/avoid bands, consensus, laggard gap, sizing, DCA, directions, hours and streak reversal.
aistratWeekly-trained signal model with calibrated edge gates and no averaging down. Tune initialBuy, maxConcurrent and bankroll; the model chooses setups and assets.
acesPocket Aces fixed community preset: near-certainty entries, confirm-DCA and preset quiet hours. Tune sizing and concurrency only.
customSimple/Advanced directional momentum, normally on BTC with optional additional configured assets. Exposes mode, thresholds, bands, assets, sizing, DCA, hours and streak controls.

Trading mode presets

Thresholds are spot-move gates; entry bands are allowed token prices. Values sent explicitly in the same request override these presets.

ModeUP / DOWN thresholdEntry bandDefault max concurrent
selective0.08 / 0.140.42–0.622
balanced0.055 / 0.100.38–0.683
aggressive0.015 / 0.030.35–0.754

Core configuration keys

KeyMeaning
initialBuyDollar size of each initial entry. Keep it affordable relative to the actual pUSD balance; $5–10 is a cautious test size.
maxPerTradeMaximum total allocated to one position, including DCA additions. Set it equal to initialBuy for no additions.
bankrollTotal dollar allocation available to the strategy. It does not create funds or override the real wallet balance.
maxConcurrentMaximum number of positions open at once. The settings interface supports 1–6.
entryLow / entryHighAllowed token-price band, expressed from 0 to 1. Low must remain below high.
upThreshold / downThresholdDirectional spot-move thresholds, expressed as decimals: 0.03 means 3%.
avoidLow / avoidHighOptional token-price band to avoid. Disabled when high is not above low.
minAgreeConstellation consensus count, 2–6. Higher values are pickier and can drastically reduce trade frequency.
laggardGapConstellation laggard filter. Larger gaps accept only stronger dislocations.
assetsAsset list for the directional/custom strategy only. Constellation and AI Strat scan their own six-asset universe.
tradeUp / tradeDownAllow entries in each direction. If both are false, no new directional entries are taken.
skipHoursArray of UTC hours from 0–23 during which the bot should sit out.
dca1, dca2, dcaDropFirst and second averaging-down amounts and the adverse move that triggers them.
stopLossStrategy risk-floor setting. Read the current account configuration and settings guide before changing it.
streakReversal, streakLengthOptional reversal override after a run of same-direction outcomes. It can filter out normal entries.

DCA presets

dcaModedca1dca2Preset maxPerTrade
standard$3$2.50$10.50
off$0$0$5
capped$2$0$7
confirm$3$2.50$10.50
The configuration endpoint is not a complete risk sandbox. Your agent must validate types, ranges, affordability, and cross-field consistency itself. Always read back the saved config. Never set maxPerTrade below initialBuy.
05

Start, supervise, and stop

These are deliberate control operations. Your agent should show the intended configuration and obtain the owner's permission before starting.

# 1. Verify wallet readiness
curl -X POST 'https://www.polexbotpro.pro/api/wallet/approve' \
  -H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json'

# 2. Save the reviewed strategy JSON (shown in section 04)
curl -X POST 'https://www.polexbotpro.pro/api/bot/config' \
  -H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @reviewed-config.json

# 3. Start the existing strategy engine — this enables real trading
curl -X POST 'https://www.polexbotpro.pro/api/bot/start' \
  -H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json'

# 4. Monitor fresh state, positions, trades, and errors
curl 'https://www.polexbotpro.pro/api/bot/state' -H "Authorization: Bearer $AGENT_TOKEN"
curl 'https://www.polexbotpro.pro/api/logs'    -H "Authorization: Bearer $AGENT_TOKEN"

# 5. Stop new trading activity
curl -X POST 'https://www.polexbotpro.pro/api/bot/stop' \
  -H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json'

What start and stop mean

  • Start: sets botActive:true after checking wallet connection, bans/restrictions, and the wallet link. The engine then evaluates markets and places real signed orders when its strategy permits.
  • Stop: sets botActive:false. Existing positions and already-submitted activity still need normal engine handling/resolution; stopping is not an instant sell-all.
  • No direct trades: do not invent /buy, /sell, or /order endpoints. They are not part of this API.
Starting does not promise a fill. Inspect logs for skips, order rejection, insufficient balance, wrong wallet pairing, or restrictive strategy settings. A green botActive flag alone is not evidence of a trade.
06

API reference and behavior

All requests and responses use JSON. Authenticated routes below require the bearer token unless marked public.

Method and pathAccessPurpose
POST /api/wallet/connectPublic credential exchangeConnect matching key + developer address; create/retrieve account and return bearer token.
POST /api/wallet/derive-addressPublic credential exchangeDerive deployed Polymarket wallet candidates from a private key; returns address, kind and deployment status.
POST /api/wallet/disconnectBearerMark disconnected and stop the bot; preserve account and history.
GET /api/meBearerSafe account record, config, trades and stats; private key redacted.
GET /api/wallet/balanceBearerCollateral, bankroll, positions, deployment, warnings and restrictions.
POST /api/wallet/approveBearerRead-only wallet/trading readiness check.
POST /api/bot/configBearerMerge and return strategy configuration. /api/config is equivalent.
GET /api/bot/stateBearerRequested and actual engine state, positions, trades, stats and notices.
GET /api/tradesBearerPersisted trade history and aggregate statistics.
GET /api/logsBearerEngine activity, errors, skips and durable results.
POST /api/bot/startBearerEnable the real trading engine after server-side checks.
POST /api/bot/stopBearerDisable the botActive flag.
POST /api/ask-aiBearer · cooldownRead BTC across four timeframes and return a sanitized AI strategy suggestion. It does not save or start the config.
POST /api/onboard-aiBearer · cooldownSend {"text":"plain-English style"}; returns a sanitized AI Strat proposal. It does not save or start the config.
GET /api/pricesPublicCurrent crypto price snapshot.
GET /api/markets/livePublicLive five-minute market data used by the console.
GET /api/signals/live · /api/signals/historyPublicLive and historical engine signal-board data.
GET /api/traders/positionsPublicPublic board of tracked traders' Polymarket positions.
GET /api/politics[/:slug]PublicPolitics market boards and analysis.
GET /api/esports[/:slug] · /api/uefa[/:slug]PublicEsports and UEFA boards and analysis.
GET /api/briefs[/:date]PublicDaily AI market brief index or one date.

Response and error handling

  • Always check ok. Many validation and readiness failures arrive as HTTP 200 with { "ok": false, "error": "…" }.
  • HTTP 401: missing or invalid token. Reconnect the wallet and use the returned token.
  • HTTP 429: back off and honor the service's retry message. Do not retry in a tight loop.
  • restricted or proxyRestricted: do not repeatedly call start. Read link, warning, balance and notices; fix the stated cause.
  • Network/RPC failure: preserve the last known state, back off, and retry with a timeout. Never duplicate start/config requests blindly.
  • Stale state: inspect stale, age_seconds, and running rather than assuming the engine is online.
07

Instructions for your AI agent

Paste this into your agent's system or tool instructions, then provide the two credentials through its secret manager. Adjust the limits to your own policy.

You are my trading operator for Polexbot.
Base URL: https://www.polexbotpro.pro
Full API guide: https://www.polexbotpro.pro/agents

CREDENTIALS
- Read AGENT_PRIVATE_KEY and AGENT_PROXY_ADDRESS from the secret manager.
- Never print, repeat, log, or place either credential in chat.
- Connect with POST /api/wallet/connect and keep the returned bearer token secret.

OPERATING RULES
1. You may connect and use read-only endpoints without further confirmation.
2. Before changing configuration or starting the bot, show me the exact JSON diff and ask for my approval.
3. Unless I explicitly approve different limits: initialBuy <= 5, maxPerTrade <= 5, maxConcurrent <= 2, bankroll <= 100.
4. Use the existing strategy engine only. There is no arbitrary buy/sell endpoint.
5. Before every start, check wallet link, restrictions, readiness, real pUSD balance, current config, and whether another engine may already control this wallet.
6. Never run this wallet on two sites or engines simultaneously.
7. While active, poll /api/bot/state every 10–15 seconds and /api/logs every 15–30 seconds. Check balance every 30–60 seconds and before sizing changes.
8. Treat HTTP 200 with ok:false as an error. Never ignore link, warning, restricted, proxyRestricted, stale, or running fields.
9. Do not retry start repeatedly when orders are rejected. Stop, diagnose the logs, and tell me what is required.
10. You may stop the bot immediately when I ask, when credentials/link status fail, or when my stated risk limit is reached.
11. Stopping is not selling. Report open positions and their resolution state honestly.
12. Never claim a trade occurred without confirming it in state, trades, or logs.
08

Security checklist and FAQ

The convenience of agent control should not obscure what the credentials can do.

  • Use a separate, limited-funds trading wallet.
  • Store keys and tokens in a secret manager.
  • Require approval before configuration and start.
  • Set hard size, concurrency, and bankroll limits.
  • Run only one engine for a given wallet.
  • Keep a reliable, tested stop procedure.
  • Review agent actions and engine logs regularly.
  • Never expose credentials in browser JavaScript.
Does connecting my agent start trading?

No. Connection establishes the account and bearer token. Real trading begins only after an explicit successful POST /api/bot/start.

Can the agent decide to buy BTC UP in a particular round?

Not through a direct order endpoint. It can choose and configure a supported strategy and enable the engine. The engine evaluates each round, signs orders, and manages entries.

Why does Polexbot need the private key?

The trading engine signs Polymarket orders for your account. The connection API stores the key with your server-side account for that purpose. Anyone holding the key can control the wallet, so dedicate a wallet and protect the agent environment.

Where do I find the developer address?

Open your Polymarket profile and copy the 0x address from the profile URL. You can also call POST /api/wallet/derive-address with the private key, or use the developer-address derivation control in Settings.

Why is the bot active but not trading?

Check the real pUSD balance, wallet pairing, restrictions, approval/readiness response, engine freshness, and logs. Strict entry bands, high consensus, skipped hours, one-direction filters, or ordinary market conditions can all produce no entries.

Can I use the same wallet on several Polexbot family sites?

Do not run them simultaneously. Each site has its own configuration and engine. Starting the same wallet in two places can produce duplicated or conflicting orders. Choose one site and one active agent per wallet.

Can several agents manage one account?

They would share the same token, configuration, botActive flag, and engine. That creates race conditions and overwritten settings. Use one controlling agent, or implement your own coordinator with a single writer.

Does stop close every position immediately?

No. Stop disables new bot activity. Existing positions and submitted activity still need engine handling and market resolution. Read state and Polymarket positions before reporting the account as flat.

Copied