Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions apps/agent/prompts/system.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<!-- botlab-agent-system-prompt v5 (apps/agent/prompts/system.md). Changing this file changes the agent's behaviour: bump the version and note it in docs/PROGRESS.md. -->
<!-- botlab-agent-system-prompt v6 (apps/agent/prompts/system.md). Changing this file changes the agent's behaviour: bump the version and note it in docs/PROGRESS.md. -->
You are the BotLab agent: an autonomous research and strategy assistant for a self-hosted trading lab on
Polymarket (prediction markets) and Binance (crypto spot). You run unattended on a schedule; nobody is
watching this session and nobody will answer questions. Work through the tools, then end the run.
Expand All @@ -22,7 +22,8 @@ BotLab enforces the boundaries on the server, not you:

Read the mandate and limits (`botlab://config/mandate`, `botlab://config/limits`, or `get_overview`) at the start
of every run and stay inside them: categories and horizons the mandate allows, minimum 24h volume (`min_liquidity_usd` is 24h volume, not
order-book liquidity), maximum ambiguity. Read `botlab://sdk/guide.md` (the script and forecasting guide) before writing or changing a template,
order-book liquidity; when the mandate sets the lower `min_forecast_volume_usd`, markets between the two are
forecast-only: record forecasts there to build the track record, never expect a bot to trade them), maximum ambiguity. Read `botlab://sdk/guide.md` (the script and forecasting guide) before writing or changing a template,
and `botlab://sdk/types.d.ts` for the exact `ctx` API.

# Untrusted data
Expand Down
2 changes: 1 addition & 1 deletion apps/web/src/pages/Ledger.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -541,7 +541,7 @@ function SubmitForecast() {
<Card title="Submit a forecast (human)">
<form onSubmit={submit} className="space-y-3 max-w-2xl">
<p className="text-sm text-gray-400">
The probability that the token resolves YES. The server captures the market price, checks spread, 24 h volume (min_liquidity_usd) and UMA status, and files the forecast in
The probability that the token resolves YES. The server captures the market price, checks spread, 24 h volume (mandate min_forecast_volume_usd if set, else min_liquidity_usd) and UMA status, and files the forecast in
its (category, horizon) bucket. A token’s active forecast can be superseded after 6 hours.
</p>
<label className="block text-sm text-gray-400">
Expand Down
1 change: 1 addition & 0 deletions config/mandate.example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ markets:
resolves_within_days: [0, 30] # default horizon
long_horizon_days: [30, 90] # allowed only within limits.global.max_long_horizon_pct
min_liquidity_usd: 5000 # 24h volume (USD), not order-book liquidity
# min_forecast_volume_usd: 1000 # lower 24h-volume floor for recording forecasts only (orders keep the one above)
max_ambiguity_score: 1 # skip markets rated 2-3
strategies:
allow: [forecast, consistency, resolution_rule] # template keys
Expand Down
12 changes: 12 additions & 0 deletions docs/PROGRESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,7 @@ IPC handlers became `apps/server/src/routes/`).
| R206 | VPS check, amended review | **(Review: Cloudflare's country ban page — "Error 1009", "banned the country or region" — is `geo_blocked`; geo bodies are now matched before the challenge markers)** **Classification and verdict**: per request `ok` / `geo_blocked` (geoblock endpoint `blocked: true`, HTTP 451, "restricted region / location" bodies) / `bot_challenge` (`cf-mitigated`, Cloudflare HTML "Just a moment" / "Attention Required" / challenge markers, also on a 200 where JSON was expected) / `forbidden` (other 403) / `rate_limited` (429) / `network_error` (DNS, TLS, reset, timeout, proxy CONNECT refusal; fetch cause chains walked) / `unexpected` / `skipped`. Verdict (exit code): geo anywhere ⇒ `BLOCKED (geo)` (1); a challenge / 403 on a Polymarket API, or **every** Polymarket request failing at the connection level while the IP lookup works ⇒ `BLOCKED (datacenter/bot protection)` (1); nothing works at all ⇒ `DEGRADED` (no network, 2); 429, partial failures, unexpected bodies, CLOB clock skew beyond `MAX_CLOCK_SKEW_MS` + 1 s resolution, a close-only account, Binance failures ⇒ `DEGRADED` (2); else `OK` (0). IP lookup and geoblock endpoint failures are informational. A CLI usage error also exits 1/2 (existing CLI convention). **VERIFY**: `https://polymarket.com/api/geoblock` and its `{ blocked, ip, country, region }` shape are from documentation, not seen live (sandbox outbound blocked); any other shape ⇒ `unavailable`. | 429 alone is ambiguous (could be the user re-running), so it degrades rather than blocks. | Thresholds in `computeVerdict`. |
| R207 | VPS check, amended review | **(Review: a read-only open of a WAL database can still leave empty `-wal` / `-shm` files next to it; an open failure reports SQLite's own message (permissions, …) instead of "no database". Proxy detection follows Node: `https_proxy ?? HTTPS_PROXY ?? http_proxy ?? HTTP_PROXY` — an empty value disables it —, and "via proxy" is reported only when fetch will use it: `NODE_USE_ENV_PROXY` active and `no_proxy ?? NO_PROXY` not exempting the CLOB host)** **Database and proxy**: the check opens `botlab.db` **read-only** with better-sqlite3 (no migrations, no `key_check` write; the key is compared with `keyCheckMatches`) and is **allowed while the server runs** on the same data dir; the master key is loaded like the server's but never generated (`production: true`). `HTTPS_PROXY` / `HTTP_PROXY`: Node 22's fetch ignores them unless `NODE_USE_ENV_PROXY=1` (Node ≥ 22.21), so the command re-runs itself with it (and `--disable-warning=UNDICI-EHPA` via `NODE_OPTIONS`); the report says the results reflect the proxy's IP. On Node < 22.21 a note says the proxy was not used. Binance is opt-in (`--binance`). No `/api/system/connectivity` route or Settings button (kept the change CLI-only; the check is for a machine that may not run BotLab yet). | Users test a fresh VPS before installing a database; a running server must not have to stop. | Add the route later (admin only) calling `runConnectivityCheck`. |
| R208 | VPS check review | **Credential headers never follow redirects** (see R205): connectivity probes with headers (manual, 3xx ⇒ `unexpected`, no request to the target), clob-client via axios (`refuseAuthRedirects`: `maxRedirects: 0` when a POLY_* header is present; unauthenticated CLOB reads still follow redirects), Binance signed GET / POST / order query (`redirect: 'error'`). | Review 1: a redirect to another host would have carried `POLY_API_KEY` / `POLY_PASSPHRASE` / `POLY_SIGNATURE` (or `X-MBX-APIKEY`) there. The CLOB and Binance APIs do not redirect today, so nothing legitimate breaks. | Remove the request interceptor / `SIGNED_REDIRECT`. |
| R209 | shadow forecast floor | **Separate 24h-volume floor for forecasts.** Optional `mandate.yaml markets.min_forecast_volume_usd` (≤ `min_liquidity_usd`; unset = today's rule): when set, `submit_forecast` needs only that 24h volume, so shadow forecasts can build the track record in thin categories; orders keep the trading floor (max of the mandate's and `limits.yaml per_market.min_liquidity_usd`, risk engine unchanged). `search_markets` flags markets between the floors "forecast only" (still dropped by `inMandateOnly`). The Forecast Executor skips forecasts whose market's 24h volume (`ctx.polymarket.getMarket`) is below `ctx.risk.getMandateSummary().minLiquidityUsd` instead of collecting `liquidity` rejections (which would trip the rejection cooldown, R193), and cancels its bids there; unknown volume is left to the risk engine, and nothing is skipped without these calls (backtests). Config change effect: neutral. Agent system prompt v6, guide §3. | The 2026-11-01 agent session and the Mac test: with economics-only and $5k of 24h volume nearly nothing can be forecast, so no bucket can reach 30 scored forecasts. Lowering `min_liquidity_usd` itself would also loosen live orders. | Remove the key from `mandate.yaml` (back to one floor); the executor skip also applies to forecasts whose market volume fell below the trading floor after they were made. |

## Log

Expand Down Expand Up @@ -1338,3 +1339,14 @@ Independent security review of b434e6b..0e1225e. Fixed (R149, R150, R152, R154 a
`checkPolymarket.ts` (read-only open rejects writes, open errors, key mismatch, no key ⇒ none generated, unknown
wallet, proxy order / `no_proxy`); `authHeaders.ts` (header names only, no private key or secret).

### 2026-11-01 — shadow forecast floor (`min_forecast_volume_usd`)

- `mandate.yaml markets.min_forecast_volume_usd` (optional, ≤ `min_liquidity_usd`): the 24h-volume floor for
`submit_forecast` when set; orders keep the trading floor (R209). Default and example files carry it commented
out (opt-in); config change rule neutral.
- `search_markets` flags: "forecast only" between the floors, "no forecast either" below the forecast floor.
- Forecast Executor: skips (and cancels bids in) markets whose 24h volume is below the mandate summary's
`minLiquidityUsd`; unknown volume and missing calls (backtests) unchanged.
- Agent: system prompt v6 and guide §3 explain forecast-only markets; Ledger page help text.
- Tests: config (optional key, ≤ `min_liquidity_usd`), ledger gate with and without the key, search flags,
executor skip / cancel and the unchanged cases (volume at the floor, unknown, no summary).
6 changes: 6 additions & 0 deletions docs/guide/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,12 @@ markets.min_liquidity_usd` (default 5000; the larger applies) are compared with
within 90 days) cleared $5,000 of 24 h volume, so most forecasts and bids in those categories were refused. If you
want BotLab to trade more of them, consider lowering `min_liquidity_usd` (your call; the agent cannot change it).

**A lower floor for forecasts only.** To build the forecast track record in thin categories without loosening live
orders, set `markets.min_forecast_volume_usd` in `mandate.yaml` (Risk → Mandate; at most `min_liquidity_usd`,
e.g. 1000). Forecasts then need only that much 24 h volume; every order still needs `min_liquidity_usd`. Markets
between the two are forecast-only: they are scored and count toward category rights, but the Forecast Executor
does not bid on them. Leave it unset to keep one floor for both.

## Access, API and tokens

- **UI / admin**: password login → session cookie (httpOnly, SameSite=Strict, 7 days idle / 30 days
Expand Down
4 changes: 3 additions & 1 deletion docs/guide/strategies.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,9 @@ most the orders left this hour. The hourly rate counts only orders a bot itself
not the Position Manager's exits placed for it); 6 risk rejections within 10 minutes pause a bot's own
submissions until the window drains (`rejection_cooldown`). After the Position Manager stops a position out — on
any bot's position in the same mode — the token is skipped until its forecast is renewed, and a token (or its
complement) with an open exit flag on any bot's position is not bid on. Each cycle it records the best edge per day it could not fund (read by the Position Manager).
complement) with an open exit flag on any bot's position is not bid on. Markets whose 24h volume is below the trading
floor (`min_liquidity_usd`) are skipped and its bids there cancelled: forecasts may sit below it when the mandate sets
`min_forecast_volume_usd`, and the risk engine would refuse the bids anyway. Each cycle it records the best edge per day it could not fund (read by the Position Manager).

**Position Manager** (`templates/position-manager.ts`, spec §9.2) — the only bot that can see other bots'
positions (`ctx.portfolio`, granted by the server to this builtin template only; forks do not get it). It exits a
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/config/changes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,8 @@ const MANDATE_RULES: Record<string, Rule> = {
'markets.resolves_within_days': 'range-widens',
'markets.long_horizon_days': 'range-widens',
'markets.min_liquidity_usd': 'down',
// Forecasts only (shadow record); orders still need min_liquidity_usd (R209)
'markets.min_forecast_volume_usd': 'neutral',
'markets.max_ambiguity_score': 'up',
'strategies.allow': 'set-grows',
'strategies.allow_custom_templates': 'enable',
Expand Down
1 change: 1 addition & 0 deletions packages/core/src/config/defaults.ts
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ markets:
resolves_within_days: [0, 30] # default horizon
long_horizon_days: [30, 90] # allowed only within limits.global.max_long_horizon_pct
min_liquidity_usd: 5000 # 24h volume (USD), not order-book liquidity
# min_forecast_volume_usd: 1000 # lower 24h-volume floor for recording forecasts only (orders keep the one above)
max_ambiguity_score: 1 # skip markets rated 2-3
strategies:
allow: [forecast, consistency, resolution_rule] # template keys
Expand Down
10 changes: 10 additions & 0 deletions packages/core/src/config/schema.ts
Original file line number Diff line number Diff line change
Expand Up @@ -187,10 +187,20 @@ export const MandateSchema = z.strictObject({
resolves_within_days: dayRange.default([0, 30]),
long_horizon_days: dayRange.default([30, 90]),
min_liquidity_usd: usd.default(5000),
// Lower 24h-volume floor for recording forecasts only (shadow track record, R209); unset = the trading floor.
// Orders always need min_liquidity_usd (and limits.yaml per_market).
min_forecast_volume_usd: usd.optional(),
max_ambiguity_score: z.number().int().min(0).max(3).default(1),
})
.prefault({})
.superRefine((m, ctx) => {
if (m.min_forecast_volume_usd !== undefined && m.min_forecast_volume_usd > m.min_liquidity_usd) {
ctx.addIssue({
code: 'custom',
path: ['min_forecast_volume_usd'],
message: 'must be at most min_liquidity_usd (it only lowers the floor for forecasts)',
});
}
if (m.resolves_within_days[1] > LONG_HORIZON_DAYS) {
ctx.addIssue({
code: 'custom',
Expand Down
8 changes: 6 additions & 2 deletions packages/core/src/ledger/LedgerService.ts
Original file line number Diff line number Diff line change
Expand Up @@ -306,9 +306,13 @@ export class LedgerService implements ForecastSource, CategoryBucketSource {
const mandateNow = this.deps.getMandate();
if (!mandateNow) throw new LedgerValidationError('Mandate unavailable (config invalid); cannot check the market');
const limitsNow = this.deps.getLimits?.() ?? null;
const minLiquidity = Math.max(mandateNow.markets.min_liquidity_usd, limitsNow?.per_market.min_liquidity_usd ?? 0);
// The mandate may set a lower floor for forecasts only (shadow track record, R209); orders keep the trading floor
const forecastFloor = mandateNow.markets.min_forecast_volume_usd;
const minLiquidity = forecastFloor ?? Math.max(mandateNow.markets.min_liquidity_usd, limitsNow?.per_market.min_liquidity_usd ?? 0);
if (market.volume24hUsd === null || market.volume24hUsd < minLiquidity) {
throw new LedgerValidationError(`Market liquidity ${market.volume24hUsd ?? 'unknown'} (24h volume) < ${minLiquidity}`);
throw new LedgerValidationError(
`Market liquidity ${market.volume24hUsd ?? 'unknown'} (24h volume) < ${minLiquidity}${forecastFloor !== undefined ? ' (min_forecast_volume_usd)' : ''}`
);
}

const now = this.now();
Expand Down
4 changes: 3 additions & 1 deletion packages/core/src/sdk/guide.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,9 @@ caps, category rights and the monthly budget; every tool call is in the audit lo
24h volume ≥ the mandate minimum (\`min_liquidity_usd\` is **24h volume**, not order-book liquidity), a
two-sided book with spread ≤ 0.10 and end in 6 h – 90 days. Few in-mandate markets clear the default $5,000 of
24h volume (a handful on the 2026-10-31 test): an empty or short scan is expected; do not lower your standards
to fill it, and only the human can change the threshold.
to fill it, and only the human can change the threshold. If the mandate sets \`min_forecast_volume_usd\`, forecasts
need only that (lower) 24h volume, to build the track record; orders still need \`min_liquidity_usd\`, so such
markets are forecast-only (\`search_markets\` flags them "forecast only") and the executor will not bid on them.
- Ambiguity (spec §7.4): 0 objective source, clear criteria, fixed date · 1 clear but one reporting source or a
term to interpret · 2 several reasonable readings / "consensus of credible reporting" · 3 clarifications issued,
active dispute or criteria likely contested. The server raises it to ≥ 2 for 7 days after a rules change and on
Expand Down
9 changes: 8 additions & 1 deletion packages/core/src/services/MarketService.ts
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,7 @@ export class MarketService {
const mandate = this.extras.getMandate?.() ?? null;
const limits = this.extras.getLimits?.() ?? null;
const minLiq = Math.max(mandate?.markets.min_liquidity_usd ?? 0, limits?.per_market.min_liquidity_usd ?? 0);
const forecastFloor = mandate?.markets.min_forecast_volume_usd;
const now = this.now();
const out: AgentSearchHit[] = [];
for (const h of hits) {
Expand All @@ -234,7 +235,13 @@ export class MarketService {
const inHorizon = (daysToEnd >= s0 && daysToEnd <= s1) || (daysToEnd >= l0 && daysToEnd <= Math.min(l1, MAX_HORIZON_DAYS));
if (!inHorizon) flags.push(`settles in ${daysToEnd.toFixed(1)} days (outside the mandate horizons)`);
}
if ((h.volume24hUsd ?? 0) < minLiq) flags.push(`24h volume ${h.volume24hUsd ?? 'unknown'} < ${minLiq}`);
const volume = h.volume24hUsd ?? 0;
if (volume < minLiq) {
// Between the forecast floor (R209) and the trading floor a forecast can still be recorded
if (forecastFloor === undefined) flags.push(`24h volume ${h.volume24hUsd ?? 'unknown'} < ${minLiq}`);
else if (volume >= forecastFloor) flags.push(`24h volume ${h.volume24hUsd} < ${minLiq}: forecast only (orders need min_liquidity_usd)`);
else flags.push(`24h volume ${h.volume24hUsd ?? 'unknown'} < ${forecastFloor} (min_forecast_volume_usd): no forecast either`);
}
if (mandate && h.ambiguityScore !== null && h.ambiguityScore > mandate.markets.max_ambiguity_score) {
flags.push(`ambiguity ${h.ambiguityScore} > mandate max ${mandate.markets.max_ambiguity_score}`);
}
Expand Down
15 changes: 15 additions & 0 deletions templates/forecast-executor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -489,8 +489,23 @@ export async function runExecutorCycle(ctx: BotContext): Promise<CycleResult> {
}
}

// Markets under the trading floor (24h volume < min_liquidity_usd): the risk engine would refuse the bid. Forecasts
// may be recorded below it (mandate min_forecast_volume_usd, R209), so skip them instead of collecting rejections.
// Unknown volume is left to the risk engine; without these calls (backtests) nothing is skipped
const thinMarkets = new Set<string>();
if (typeof ctx.risk.getMandateSummary === 'function' && typeof ctx.polymarket.getMarket === 'function') {
const mandate = await ctx.risk.getMandateSummary();
if (mandate) {
for (const marketId of new Set(forecasts.map((f) => f.marketId))) {
const volume = (await ctx.polymarket.getMarket(marketId))?.volume24hUsd;
if (typeof volume === 'number' && volume < mandate.minLiquidityUsd) thinMarkets.add(marketId);
}
}
}

const quotes: Quote[] = [];
for (const f of forecasts) {
if (thinMarkets.has(f.marketId)) continue;
if (flaggedMarkets.has(f.marketId) || flaggedTokens.has(f.tokenId) || (f.complementTokenId && flaggedTokens.has(f.complementTokenId))) continue;
const sides: Array<{ tokenId: string; fair: number }> = [{ tokenId: f.tokenId, fair: f.probability }];
if (f.complementTokenId) sides.push({ tokenId: f.complementTokenId, fair: 1 - f.probability });
Expand Down
8 changes: 8 additions & 0 deletions tests/config/config.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,14 @@ describe('config loader', () => {
write('mandate.yaml', 'markets:\n resolves_within_days: [1, 14]\n long_horizon_days: [45, 60]\n');
expect(loadConfig(dir).mandate.markets.long_horizon_days).toEqual([45, 60]);
});

it('min_forecast_volume_usd is optional (unset: forecasts use the trading floor) and at most min_liquidity_usd', () => {
expect(MandateSchema.parse({}).markets.min_forecast_volume_usd).toBeUndefined();
write('mandate.yaml', 'markets:\n min_forecast_volume_usd: 1000\n');
expect(loadConfig(dir).mandate.markets.min_forecast_volume_usd).toBe(1000);
write('mandate.yaml', 'markets:\n min_liquidity_usd: 2000\n min_forecast_volume_usd: 3000\n');
expect(() => loadConfig(dir)).toThrow(/min_forecast_volume_usd/);
});
});

describe('cross-file validation', () => {
Expand Down
Loading
Loading