> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xinsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-buy the Pick of the Day

> Set up potd-trader, check a dry run, and choose when it can buy picks on your Polymarket account.

[potd-trader](https://github.com/0xinsider/potd-trader) runs on your computer and buys released [Pick of the Day](/api-reference/endpoint/get-pick-of-the-day) picks with your Polymarket account. You choose an amount per pick and a daily spending cap. It starts in dry-run mode, which checks possible purchases without placing orders.

Your private key signs orders locally. 0xinsider provides the picks; it does not hold your wallet or run the trader for you.

<span id="what-you-need" />

## Before you start

You need Windows x64, macOS, or Linux, plus Git and [uv](https://docs.astral.sh/uv/getting-started/installation/). The commands below install a compatible Python version through uv.

| You need | Where to get it |
| - | - |
| A Pro or Max API key | Generate one at [0xinsider Developers](https://0xinsider.com/developers). |
| Your Polymarket signer key | For an email or Google account, follow [Polymarket's key export instructions](https://help.polymarket.com/en/articles/13364258-how-do-i-export-my-key). For a wallet account, use your wallet app. |
| Your Polymarket account address | Copy it from your Polymarket profile menu. This address holds your pUSD and can differ from the address that signs orders. |
| An amount per pick and a daily cap | Choose amounts you are willing to spend. Fees are charged in addition to the cap. |

Keep the checkout, configuration, and order ledger on one local filesystem, outside OneDrive or other synchronized folders. Use one active setup per wallet; separate computers or ledger copies cannot prevent each other from buying the same pick.

<Warning>
  Live mode spends real money. Use a dedicated wallet with a small balance, and keep your keys private. Local signing and spending limits do not protect you from every unwanted recommendation or loss.
</Warning>

<span id="install" />

## 1. Install the trader

Use [v0.3.6](https://github.com/0xinsider/potd-trader/releases/tag/v0.3.6) to verify your account's Pro or Max allowance before buying. Pro includes up to 5 daily picks; Max includes up to 15. Stop older watchers before upgrading, because they do not enforce this additional pick limit.

On Windows, install uv and Git in PowerShell:

```powershell theme={null}
winget install --id astral-sh.uv --exact
winget install --id Git.Git --exact
```

Reopen PowerShell, then run `Set-Location $env:USERPROFILE` to work in your local user folder. Windows runs the CLI directly; WSL is optional.

Run these commands in PowerShell or your macOS/Linux terminal:

```sh theme={null}
git clone --branch v0.3.6 --depth 1 https://github.com/0xinsider/potd-trader potd-trader-src
cd potd-trader-src
uv sync --locked --python ">=3.12.4,<3.13"
uv run --locked potd-trader init
```

These commands install `v0.3.6` with its locked dependencies. Use its [release page](https://github.com/0xinsider/potd-trader/releases/tag/v0.3.6) to verify the source commit and package checksums.

## 2. Enter your keys and spending limits

`init` creates a `potd-trader/` configuration folder inside the checkout. It asks for 5 values:

1. Your 0xinsider API key.
2. Your Polymarket signer key.
3. Your Polymarket account address.
4. The amount to buy per pick.
5. Your daily spending cap.

Both keys stay hidden as you type. Set your daily spending cap for up to 15 available picks; the existing suggestion stays at 10 stakes.

Pro opens 5 daily picks in total, including the free selection, and Max opens every available published pick up to 15. Your chosen cap still limits spending.

The setup checks your account and runs a dry run. It never overwrites an existing configuration folder. Leave live trading off when it asks whether to enable it; you can enable it after the checks below.

On macOS and Linux, the folder is private to your user, with mode `700`, and `.env` has mode `600`. On Windows, the new folder allows access to your user account and administrators. Check the permissions yourself if you use an existing or manually created folder.

## 3. Check your account and a dry run

Enter the configuration folder and run:

```sh theme={null}
cd potd-trader
uv run --locked potd-trader status
uv run --locked potd-trader run --dry-run
```

`status` reports regional eligibility, wallet balance, trading approvals, reserved spending, and unresolved orders. The dry run reports your Pro or Max allowance, reserved picks, and which released picks it would buy or skip. A skipped pick includes a reason; no order is sent.

If `status` reports missing approvals, create a Relayer API key in Polymarket **Settings > API Keys**. Add `POLYMARKET_RELAYER_API_KEY` and its `POLYMARKET_RELAYER_API_KEY_ADDRESS` to your local `.env`, then run:

```sh theme={null}
uv run --locked potd-trader setup
```

`setup` sends approval transactions for your wallet. It does not buy picks. Run `status` and the dry run again afterward.

## 4. Start buying when you are ready

From the same configuration folder, run:

```sh theme={null}
uv run --locked potd-trader live on
uv run --locked potd-trader watch
```

`live on` asks you to type `spend real money`. `watch` then checks for released picks and later releases, and reports each purchase or skip. Keep this process running if you want it to check future releases.

For a single check of the picks already released, use `uv run --locked potd-trader run`. Add `--dry-run` to either `run` or `watch` whenever you want to prohibit orders.

<span id="stop-a-running-watcher" />

## Stop buying

Run these commands from the configuration folder, using another terminal if the watcher is running:

```sh theme={null}
uv run --locked potd-trader live off
uv run --locked potd-trader live status
```

`live off` writes a persistent `HALT` file, then waits for any submission already in progress. After it acknowledges the stop, watchers using that folder cannot submit a new order. An order already sent can still fill; this command does not cancel it.

A stuck network request can delay acknowledgment. `live on` clears `HALT` after confirmation; a watcher that started in live mode can resume, while a watcher that started dry must be restarted.

## Set an amount per pick and a daily cap

Every eligible released pick uses the same amount. With the defaults, the trader buys up to 5 pUSD per pick and reserves at most 25 pUSD of order principal per UTC day. That cap covers 5 full-sized picks, matching Pro's daily allowance. Max needs a cap of 75 pUSD to fund 15 picks at that amount; a day can publish fewer picks.

Fees are additional. A partial fill still counts the full requested amount against the cap. If the cap cannot cover every pick, earlier releases are considered first, with token ID breaking ties, and the trader reports the skips.

To change these limits in an existing setup:

1. Run `live off` and stop every watcher.
2. Run `uv run --locked potd-trader size` from the configuration folder.
3. Enter the new amount and daily cap.
4. Check `status` and a dry run, then enable live mode and restart the watcher yourself.

The `size` command preserves your keys. Old `MIN_RANKS` and `MAX_RANKS` settings are ignored; the trader has no rank filter or rank-based stake.

## Your Pro or Max allowance

Your API key determines access; there is no local tier setting. Pro includes the designated free selection plus the first 4 nonfree selections, for up to 5 daily picks. Max includes every eligible published selection, up to 15.

The trader reads the authenticated feed response's `X-Monthly-Quota-Limit` header. The current included request allowance of 500,000 identifies Pro, and 2,000,000 identifies Max; the optional pay-as-you-go ceiling does not change your pick allowance. Missing or unrecognized values stop trading, and a future allowance change requires a compatible trader release.

The daily pick limit follows the `America/New_York` calendar used by the picks. Accepted, submitting, and unknown entries for that date count toward the limit, including entries created by older releases. Known rejections release their reservation; the independent spending cap still follows UTC.

A watcher checks this allowance on every successful feed response, including `304`. When it changes, the watcher discards its cached picks and requests a fresh slate. Locked selections never become purchases or requests for hidden game details.

<span id="guards-before-every-submission" />

## Why a pick may be skipped

The trader requires a released, unsettled pick with a positive published price and a valid `entry_authorization` for its token. Polymarket must also confirm the market, outcome, trading status, kickoff time, price increment, and minimum order size.

A purchase must fit all 3 price limits: your `MAX_PRICE`, your `MAX_SLIPPAGE_PCT`, and the pick's `entry_authorization.max_entry_price`. The trader checks the current order book price needed for your full stake against each limit. The authorization limits price movement; it is not a forecast of profit.

Before submitting, the trader checks the current order book and market again, then checks the stop flag and quote deadline. The quote is valid for at most 30 seconds, and less near kickoff or authorization expiry.

The trader records its spending reservation before submitting one Fill-and-Kill BUY order. This order can fill partly or completely; any unfilled portion is cancelled. If the submission result is uncertain, the trader blocks another attempt instead of risking a duplicate purchase.

`watch` follows `Retry-After`, release times, and `proof_pending_picks[].retry_at`. Temporary read failures produce a warning and a bounded wait before another check.

## How slippage and fill prices work

Slippage protection limits the share price before an order is sent. It compares a current book quote for your stake with 3 independent ceilings:

| Ceiling | How it is set |
| - | - |
| API authorization | New `policy_version: 8` grants allow up to 5 cents above `reference_best_ask`, capped at 85 cents and rounded down to the market's price increment. Existing `policy_version: 7` grants retain their recorded 2-cent allowance. |
| Your percentage limit | `MAX_SLIPPAGE_PCT=3` permits at most 3% above the published `backed_price`. This is a percentage, not a 3-cent allowance. |
| Your absolute limit | `MAX_PRICE=0.925` permits at most 92.5 cents, but the other ceilings can be lower. |

The lowest ceiling wins. The reference ask is recorded when authorization is first issued, which can be earlier than publication; `backed_price` is the midpoint recorded at publication. A 5-cent API allowance does not increase your local percentage limit.

For example, a 64-cent reference ask gives a new API ceiling of 69 cents. If the published pick price is 66.5 cents, the default 3% limit is 68.495 cents before rounding to the market's price increment. The trader still skips a quote above 68.495 cents.

```text theme={null}
Read the book for your stake
  Check the API ceiling, percentage limit, and absolute limit
  Set the BUY order limit to the acceptable quote, rounded down to the price increment
  Submit one Fill-and-Kill order
```

The submitted order limit is the highest share price that order may pay. It is set from the accepted quote, not automatically raised to the largest price your settings permit. The order can fill at several prices at or below its limit; the average actual fill price is known only after execution and is not the value used for the pre-order check.

If the book moves before submission, the order may fill partly or not at all. Fill-and-Kill cancels any unfilled portion instead of leaving an order resting. Fees are additional and are not covered by these share-price ceilings or the principal spending cap.

See [Polymarket's order guide](https://docs.polymarket.com/trading/place-orders#market-orders) for the provider's quote and Fill-and-Kill behavior.

<span id="the-ledger-and-daily-cap" />

## Resolve an uncertain order

Inspect the local order ledger:

```sh theme={null}
uv run --locked potd-trader ledger
```

Entries marked `submitting` or `unknown` keep their spending reservation, including across midnight. A confirmed order counts toward the UTC day when it was submitted. A known rejection releases the reservation.

If an order's result is uncertain:

1. Stop every trader instance for the wallet.
2. Inspect Polymarket Activity and the order's fill state.
3. Back up the configuration folder and `ledger.json`.
4. Reconcile the entry only after proving whether an order was accepted or can still execute.

Keep confirmed orders and their identities. Removing an entry without checking Polymarket can allow a second purchase. Never delete the ledger or lock files while a process is running.

The ledger also blocks reuse of a pick, its date/slot with a different token, or the same token on a different date. All instances for one wallet must share the same configuration folder and ledger, and run on the same operating system.

<Note>
  On Windows, a hard power loss can lose the latest reservation or stop flag. Check Polymarket Activity and reconcile the ledger before restarting live mode. Do not run Windows and WSL instances for the same wallet at the same time.
</Note>

## Settings

Edit `.env` locally and restart the watcher after changing settings. A `.env` in the current folder takes precedence over the fallback in `POTD_TRADER_HOME`.

| Variable | Default | What it controls |
| - | - | - |
| `LIVE` | `no` | Live orders require exactly `yes` in both the process settings and active `.env`, with no `HALT` file. |
| `STAKE_USD` | `5` | The amount of order principal per pick, in pUSD. `0` disables buys. |
| `DAILY_CAP_USD` | `25` | The positive cap on reserved order principal per UTC day, including unresolved earlier orders. |
| `MAX_PRICE` | `0.925` | The highest share price you permit, equivalent to 92.5 cents. The authorization can impose a lower limit. |
| `MAX_SLIPPAGE_PCT` | `3` | The maximum percentage increase of the executable book quote over the published pick price. This means 3%, not 3 cents; the API authorization can impose a lower ceiling. |
| `KICKOFF_BUFFER_MINUTES` | `5` | How many minutes before kickoff the trader stops entering. Authorization expiry can stop it earlier. |
| `LEDGER_PATH` | `ledger.json` beside `.env` | The shared local file that records orders and spending reservations. |
| `POTD_TRADER_HOME` | `~/.potd-trader` | The fallback configuration folder. |
| `WATCH_IDLE_MINUTES` | `30` | How often to check again when idle. |

An environment variable cannot enable orders when the active `.env` says `LIVE=no`. A missing control file also prevents live orders, even if secrets come from the environment.

<span id="upgrade" />

## Upgrade an existing setup

1. Run `live off` and stop every old watcher, including any in WSL.
2. Back up the complete configuration folder and ledger.
3. Install v0.3.6 in a separate checkout using the installation commands above.
4. Use the same configuration and ledger on a local filesystem.
5. Run `status` and `run --dry-run` before enabling live mode again.

When moving from WSL to native Windows, keep one active configuration copy. Update absolute `LEDGER_PATH` and `POTD_TRADER_HOME` values to their Windows paths. Existing v1 JSON ledgers need no migration.

If you are upgrading from 0.2.0, close every old process: its `live off` cannot stop a binary that is already running. Set a positive `DAILY_CAP_USD`; `0` is rejected.

For Docker setup, follow the [repository's Docker instructions](https://github.com/0xinsider/potd-trader#docker). Mount the configuration folder at `/app/data` so the container sees the same `.env`, `HALT`, and ledger.

<span id="what-leaves-your-machine" />

## Where your data goes

The private key stays in the local signing process. The trader uses the following services; package installation also contacts package hosts.

| Service | What it receives |
| - | - |
| `api.0xinsider.com` | Your 0xinsider API key, to read entitled Pro or Max picks. |
| `clob.polymarket.com` | Signed authentication messages, derived credentials, token IDs, and signed orders. |
| `gamma-api.polymarket.com` | Token IDs, to check market details and trading constraints. |
| `polymarket.com/api/geoblock` | Your IP address, to check regional eligibility. |
| `polygon.drpc.org` | Public wallet, token, and contract addresses, to check the wallet and approvals. |
| `relayer-v2.polymarket.com` | Wallet addresses, plus credentials and signed approval requests when you request setup. |

The release pins `polymarket-client==0.10.0`. The application has no withdrawal command, the builder code is optional, and `OXINSIDER_API_BASE` accepts only `https://api.0xinsider.com`. The client refuses redirects.

Anyone who can read `.env` can use its credentials. For manual setup, copy `.env.example` to `.env` inside the checkout and restrict its permissions before adding keys. Use `chmod 600 .env` on macOS/Linux; on Windows, restrict the folder to your account and administrators.

<span id="verification-and-limits" />

## Limits

Polymarket's regional restrictions apply. The trader skips a purchase when required safety data is missing. Neither a dry run nor the release's offline checks prove that a real order will succeed or that a pick will make a profit.

The tool is MIT licensed, with no warranty. If an AI agent helps you set it up, it should follow the [trader's agent instructions](https://github.com/0xinsider/potd-trader/blob/main/AGENTS.md) and leave enabling live orders to you.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.