potd-trader

Buy the 0xinsider Pick of the Day on your own Polymarket account, with a small stake and explicit spending limits. Dry-run is the default. Your wallet key signs locally through the official Polymarket SDK.

Setup guide · API contract · Release notes

Install a version with locked dependencies

v0.3.6 verifies your authenticated Pro or Max allowance before considering a buy. Pro includes five daily picks; Max includes every eligible published pick, up to fifteen. Earlier releases do not enforce this additional daily pick limit. Historical wire ranks through twenty remain readable.

Python 3.12.4+ and uv are required. Supported systems: Windows with x64 Python, macOS and Linux, including WSL. Keep the configuration and ledger on a local filesystem, outside OneDrive, other synced folders and network drives.

git clone --branch v0.3.6 --depth 1 https://github.com/0xinsider/potd-trader potd-trader-src
cd potd-trader-src
uv sync --locked
uv run --locked potd-trader init

On Windows, install Git and uv from PowerShell, then reopen your terminal:

winget install --id Git.Git --exact
winget install --id astral-sh.uv --exact

In the new PowerShell window, use a local folder under your Windows profile:

Set-Location $env:USERPROFILE
git clone --branch v0.3.6 --depth 1 https://github.com/0xinsider/potd-trader potd-trader-src
Set-Location potd-trader-src
uv sync --locked --python ">=3.12.4,<3.13"
uv run --locked potd-trader init

uv installs Python if needed. WSL is optional; native Windows uses the same commands and ledger format. Use x64 Python on Windows; native ARM64 Python is not covered by this release.

Use the v0.3.6 release page to verify the source commit and package checksums. For an immutable source pin, check out that full commit instead of a moving branch. uv sync --locked installs the versions and artifact hashes in the checked-in uv.lock and refuses a stale lockfile. Installing an unversioned Git URL or a package without its lockfile does not reproduce that environment.

init creates a new potd-trader/ folder inside the checkout. It asks five questions, hides both keys as you type, creates a private folder, and runs account checks and a forced dry run. On macOS/Linux the folder is mode 700 and .env is mode 600. On Windows, the new folder limits access to your user and administrators; files inherit its permissions. An inherited LIVE=yes cannot make this setup run buy. Only the final confirmation can enable subsequent live commands. An existing folder is never overwritten. The last two questions set your unit size per pick and daily cap; the cap prompt shows the cost of up to 15 picks. Pro opens 5 daily picks in total, including the free pick; Max opens every available published pick up to 15. The existing init suggestion remains 10 stakes, and your chosen cap remains authoritative.

From that new folder, uv finds the project in its parent directory:

cd potd-trader
uv run --locked potd-trader run --dry-run
uv run --locked potd-trader live on     # type "spend real money" yourself
uv run --locked potd-trader watch

What leaves your machine

These are runtime destinations, not package-installation hosts. The reviewed SDK is pinned to polymarket-client==0.10.0. The private key remains inside the signing process; there is no 0xinsider endpoint accepting it. OXINSIDER_API_BASE only accepts https://api.0xinsider.com; redirects are refused. The optional builder code stays optional. No withdrawal command exists.

Keeping the key local does not make a recommendation feed infallible. A compromised feed could recommend unwanted purchases within your limits. Use a dedicated wallet and a small budget.

Set up by hand or with an agent

Inside the versioned checkout:

cp .env.example .env
chmod 600 .env

On Windows, prefer init so it creates the private folder. If setting up by hand, use Copy-Item .env.example .env in a folder whose Windows Security permissions allow only your account and administrators. chmod does not set Windows access permissions.

Fill in these values locally; never paste keys into a chat:

• OXINSIDER_API_KEY: a live Pro or Max key from 0xinsider.com/developers.
• POLYMARKET_PRIVATE_KEY: the signer key. Email/Google login: Polymarket Settings, Export private key (official help). Wallet login: export from that wallet app.
• POLYMARKET_WALLET_ADDRESS: the account address in your Polymarket profile menu, which holds the pUSD. This can differ from the signer address.

uv run --locked potd-trader status
uv run --locked potd-trader run --dry-run

For an existing setup, stop its watcher, run potd-trader live off, then run uv run --locked potd-trader size inside the configuration folder. Type your unit size and daily cap; the command preserves keys and other settings and removes obsolete rank settings. Run status and a dry run, then restart the watcher. Only you can turn live trading back on. A one-shot run sees picks already released; watch wakes for later releases.

An agent must read AGENTS.md, keep secrets out of output, run only these read/dry-run checks, and leave enabling live orders to you. status reports region, account, approvals, balance, reserved UTC budget, and unresolved orders. Missing approvals require setup with a Relayer API key configured in .env; that command submits approval transactions, not orders.

Stop and resume

uv run --locked potd-trader live off
uv run --locked potd-trader live status

live off writes a persistent HALT file beside the active .env, then waits for any submission already in progress before acknowledging the stop. Running watchers using that folder cannot start another submission after that acknowledgment. An order already sent may fill; this is not an order-cancellation command. If a network call is stuck, the acknowledgment can wait for it. Creating HALT yourself signals the stop before the next post too.

live on requires your confirmation, writes LIVE=yes, and clears HALT. A watcher that started with live control enabled can resume on its next cycle. One started in dry-run stays dry until restarted. run --dry-run and watch --dry-run always prohibit orders. Live mode requires both process settings and the active file to say exactly yes, with no HALT; an inherited variable cannot override a file saying no, and a missing control file fails closed. Restart after changing other settings. A local .env is used alone; the home file is a fallback, not merged into it.

What happens before an order

1. Verify the same response's authenticated account allowance, then validate current New York product dates and unique pick slots/tokens. Refuse a duplicate or inconsistent slate. Skip settled, unreleased, started, out-of-rank, or incomplete picks.
2. Require a positive published price and a current entry authorization for the selected token.
3. Check the independent Polymarket market identity and backed outcome, an explicitly open market, known kickoff, tick size, and minimum order size. Keep the kickoff buffer.
4. Quote the book for your stake. Enforce MAX_PRICE, MAX_SLIPPAGE_PCT, and the authorization's max_entry_price together. The authorization is a drift limit, not a promise of profit.
5. Recheck the market and book before signing. After signing, recheck live control and the quote deadline (30 seconds at most, shorter near kickoff/authorization expiry).
6. Under an exclusive file lock, reload the ledger, reject a repeated pick/slot/token, enforce the account's New York daily pick limit, and reserve the stake against the local UTC submission day. Persist and sync the reservation before posting.
7. Post one Fill-and-Kill BUY through the SDK's separate post_order. Record its result without automatic approval transactions or an application retry of an ambiguous submission.

Live preflight also checks geoblocking, wallet approvals, and the available balance. FAK orders can fill partially; their full requested principal remains reserved for that UTC day. Exchange fees are additional: STAKE_USD and DAILY_CAP_USD bound order principal, not fee-inclusive debits.

Identity-free locked_picks are access information, not trades. The CLI shows how many additional picks require Max and an upgrade link. A successful state: "none" response has no released trade candidates, and replaces the previous slate; its missing game identity or schedule is never guessed.

watch honors Retry-After, release times, and proof_pending_picks[].retry_at. Read transport failures receive bounded backoff with a visible warning; an ambiguous order does not get retried.

Every released, otherwise eligible pick uses the same unit size. There is no rank-based selection, stake, or priority in this trader. If the remaining cap funds only some picks, the trader considers the earliest released eligible picks first, breaking simultaneous-release ties by token ID. It prints each cap skip.

The default 25 pUSD cap funds five 5 pUSD picks, up to the 5 daily picks Pro includes. Funding 15 Max picks at that size would require 75 pUSD of principal, but a day may publish fewer picks. Existing default and configured caps are not raised automatically.

MIN_RANKS and MAX_RANKS from older setups are ignored; status, run, and watch warn about them. The feed read reports your Pro or Max allowance and warns only when your chosen spending cap cannot cover that plan's possible daily picks. The current API still supplies a slot number for durable duplicate protection. Removing that contract across the product and historical proofs is tracked in 0xinsider/0xinsider#19968.

Pro and Max access

Your API key determines access; there is no local tier setting. The trader recognizes the verified feed response's X-Monthly-Quota-Limit header: the current included allowance of 500,000 requests identifies Pro, and 2,000,000 identifies Max. This is not the optional pay-as-you-go ceiling. Missing or unrecognized allowances stop trading instead of guessing a plan. A future quota or pick-limit change requires a compatible trader release.

Pro can reserve at most five distinct picks per New York product day, including the designated free pick. It is not a rank filter: the free selection may have a later presentation slot. Max can reserve up to fifteen. The server's filtered feed still decides which selections your account may see; locked selections are never enriched or bought. Existing accepted, submitting and unknown reservations count toward the daily allowance, including entries from an earlier release. Confirmed rejections release their pick reservation.

A watcher checks the account allowance on every successful response, including 304. If it changes, the old slate is discarded and a fresh authenticated read is required. A lapsed key cannot keep trading from a cached slate. Stop older watchers before upgrading; separate local folders or machines do not share these limits.

Ledger and recovery

ledger.json beside .env records local submission timestamps, pick identities, reserved stakes, and exchange answers. The adjacent .lock file coordinates concurrent processes. All instances for one wallet must share this ledger and configuration folder on the same local filesystem; separate copies or machines do not coordinate. Never delete the ledger or lock files while running.

A submitting, accepted, or unknown entry blocks the pick, the same date/rank slot even if its token changes, and the token even if the feed relabels its date. Known rejections release their reservation. submitting and unknown entries continue consuming budget across midnight until reconciled. Corrupt state fails closed. Existing v1 ledgers remain readable without a migration.

uv run --locked potd-trader ledger

For an unresolved order: stop all instances, inspect Polymarket Activity and the order/fill state, and preserve a backup. Only after proving no order can still execute should you remove its local entry. If the order exists, preserve its identity and record the confirmed result instead. Never clear an entry just to make the bot try again. There is no automatic unknown-order reconciliation.

Upgrade from 0.2.0

Stop every old watch process first: the old live off command cannot stop an already-running old binary. Back up your private configuration folder and ledger, install the new release in a separate checkout, and use the same ledger path. Run --dry-run before restarting live.

Behavior changes: DAILY_CAP_USD=0 is rejected; set a positive cap. Dates are checked against New York, but spending is capped by locally recorded UTC submissions. Missing safety data now skips trading. Alternate API origins are refused. Environment-only live deployments must mount an active .env control file containing LIVE=yes; keys may still come from the environment.

Settings

Docker

Build from the release checkout. Mount the configuration folder so live off on the host and container see the same control file and ledger. Never bake secrets into the image.

docker build -t potd-trader:0.3.6 .
docker run --rm -v "$PWD/potd-trader:/app/data" potd-trader:0.3.6

Verification and limits

The Check workflow installs locked dependencies, runs lint, formatting and strict source typing, compiles the source, builds packages, and exercises CLI help, version, local setup, live off, live status, an empty ledger and New York timezone loading on Windows, macOS and Linux. These checks use no wallet credentials and submit no orders. Historical fake-exchange cases remain in the repository; they are not run by this workflow or claimed as Windows evidence.

Atomic writes flush file content before replacement. macOS/Linux also flush the parent directory; Windows does not, so sudden power loss can lose a recent replacement. After a power failure, stop trading and compare the ledger with Polymarket Activity before resuming. Never run the same wallet from Windows and WSL, separate machines, containers or separate ledger copies at once.

Stop every old watcher before upgrading, including any WSL or container process. Preserve the configuration folder and ledger, then check live status and run --dry-run with the new version. Only you enable live orders. Platform checks do not prove future feed integrity or profit.

Orders spend real money and cannot be undone. Polymarket regional restrictions apply. This tool is MIT licensed, with no warranty; 0xinsider does not operate or custody your wallet.