The five-minute quickstart
From credentials to a monitored trading session. Connecting alone never starts the bot.
Connect and authenticate
The private key identifies your wallet. The developer address identifies the Polymarket account that holds and trades your funds.
| Credential | Where it goes | What to know |
|---|---|---|
privateKey | Connect request body | A 64-character hexadecimal EOA private key, with or without 0x. The engine retains it with the account to sign orders. |
proxyAddress | Connect request body | Your own 40-character Polymarket developer/profile address. This is normally different from the EOA address. |
token | Authorization: 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.
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.
Read before you act
A reliable agent establishes wallet readiness, available funds, current configuration, and engine state before issuing any control command.
| Request | Use it for |
|---|---|
| GET /api/me | Account, stored configuration, recent trades, all-time statistics, wallet status. The private key is redacted. |
| GET /api/wallet/balance | pUSD, legacy USDC.e, POL, open-position value/cost, live bankroll, deployment, link and restriction warnings. |
| GET /api/bot/state | running, botActive, live engine state, open positions, recent trades, freshness, restrictions, and notices. |
| GET /api/trades | Up to 200 persisted trades plus aggregate statistics. |
| GET /api/logs | Merged 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.
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.
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
strategy | Behavior and controls |
|---|---|
constellation | Default 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. |
aistrat | Weekly-trained signal model with calibrated edge gates and no averaging down. Tune initialBuy, maxConcurrent and bankroll; the model chooses setups and assets. |
aces | Pocket Aces fixed community preset: near-certainty entries, confirm-DCA and preset quiet hours. Tune sizing and concurrency only. |
custom | Simple/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.
| Mode | UP / DOWN threshold | Entry band | Default max concurrent |
|---|---|---|---|
selective | 0.08 / 0.14 | 0.42–0.62 | 2 |
balanced | 0.055 / 0.10 | 0.38–0.68 | 3 |
aggressive | 0.015 / 0.03 | 0.35–0.75 | 4 |
Core configuration keys
| Key | Meaning |
|---|---|
initialBuy | Dollar size of each initial entry. Keep it affordable relative to the actual pUSD balance; $5–10 is a cautious test size. |
maxPerTrade | Maximum total allocated to one position, including DCA additions. Set it equal to initialBuy for no additions. |
bankroll | Total dollar allocation available to the strategy. It does not create funds or override the real wallet balance. |
maxConcurrent | Maximum number of positions open at once. The settings interface supports 1–6. |
entryLow / entryHigh | Allowed token-price band, expressed from 0 to 1. Low must remain below high. |
upThreshold / downThreshold | Directional spot-move thresholds, expressed as decimals: 0.03 means 3%. |
avoidLow / avoidHigh | Optional token-price band to avoid. Disabled when high is not above low. |
minAgree | Constellation consensus count, 2–6. Higher values are pickier and can drastically reduce trade frequency. |
laggardGap | Constellation laggard filter. Larger gaps accept only stronger dislocations. |
assets | Asset list for the directional/custom strategy only. Constellation and AI Strat scan their own six-asset universe. |
tradeUp / tradeDown | Allow entries in each direction. If both are false, no new directional entries are taken. |
skipHours | Array of UTC hours from 0–23 during which the bot should sit out. |
dca1, dca2, dcaDrop | First and second averaging-down amounts and the adverse move that triggers them. |
stopLoss | Strategy risk-floor setting. Read the current account configuration and settings guide before changing it. |
streakReversal, streakLength | Optional reversal override after a run of same-direction outcomes. It can filter out normal entries. |
DCA presets
dcaMode | dca1 | dca2 | Preset maxPerTrade |
|---|---|---|---|
standard | $3 | $2.50 | $10.50 |
off | $0 | $0 | $5 |
capped | $2 | $0 | $7 |
confirm | $3 | $2.50 | $10.50 |
maxPerTrade below initialBuy.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:trueafter 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/orderendpoints. They are not part of this API.
botActive flag alone is not evidence of a trade.API reference and behavior
All requests and responses use JSON. Authenticated routes below require the bearer token unless marked public.
| Method and path | Access | Purpose |
|---|---|---|
| POST /api/wallet/connect | Public credential exchange | Connect matching key + developer address; create/retrieve account and return bearer token. |
| POST /api/wallet/derive-address | Public credential exchange | Derive deployed Polymarket wallet candidates from a private key; returns address, kind and deployment status. |
| POST /api/wallet/disconnect | Bearer | Mark disconnected and stop the bot; preserve account and history. |
| GET /api/me | Bearer | Safe account record, config, trades and stats; private key redacted. |
| GET /api/wallet/balance | Bearer | Collateral, bankroll, positions, deployment, warnings and restrictions. |
| POST /api/wallet/approve | Bearer | Read-only wallet/trading readiness check. |
| POST /api/bot/config | Bearer | Merge and return strategy configuration. /api/config is equivalent. |
| GET /api/bot/state | Bearer | Requested and actual engine state, positions, trades, stats and notices. |
| GET /api/trades | Bearer | Persisted trade history and aggregate statistics. |
| GET /api/logs | Bearer | Engine activity, errors, skips and durable results. |
| POST /api/bot/start | Bearer | Enable the real trading engine after server-side checks. |
| POST /api/bot/stop | Bearer | Disable the botActive flag. |
| POST /api/ask-ai | Bearer · cooldown | Read BTC across four timeframes and return a sanitized AI strategy suggestion. It does not save or start the config. |
| POST /api/onboard-ai | Bearer · cooldown | Send {"text":"plain-English style"}; returns a sanitized AI Strat proposal. It does not save or start the config. |
| GET /api/prices | Public | Current crypto price snapshot. |
| GET /api/markets/live | Public | Live five-minute market data used by the console. |
| GET /api/signals/live · /api/signals/history | Public | Live and historical engine signal-board data. |
| GET /api/traders/positions | Public | Public board of tracked traders' Polymarket positions. |
| GET /api/politics[/:slug] | Public | Politics market boards and analysis. |
| GET /api/esports[/:slug] · /api/uefa[/:slug] | Public | Esports and UEFA boards and analysis. |
| GET /api/briefs[/:date] | Public | Daily 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.
restrictedorproxyRestricted: do not repeatedly call start. Readlink,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, andrunningrather than assuming the engine is online.
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.
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.