API and data reference

Every Binary AI Engine admin endpoint with its method, path and permission key, plus the thirteen database tables the addon owns and the settlement hooks it exposes to core binary trading.

3 min readUpdated 3 August 2026api, endpoints, permissions, schema

Every endpoint below is under /api/admin/ai/binary-engine, requires authentication, and is gated on the permission listed. Errors are returned with HTTP 200 and the real code in the body — see the platform convention, not this addon's doing.

There are no user-facing endpoints. The addon operates entirely behind core binary trading; a user's browser never talks to it. What a trader sees comes from /api/exchange/binary/*, which belongs to Bicrypto core.

Dashboard

Engine counts, today's aggregated live stats, per-engine summaries, the last 24h of high-severity events, whether the emergency stop fired, and a breakdown of settlement verdicts

The settlementDecisions object counts the last 24 hours of live settlements by reason. A rising FAIR:EXPIRY_MINUTE_CLOSED share means settlements are running after their expiry candle sealed.

recentAlerts is capped at 20 and is a sample, not a population. Never render its length as a total and never search it for whether something happened — lastEmergencyStop exists precisely because that pattern is wrong.

Engines

List every engine with its market maker and market

Flat engine list for selection dropdowns

AI Market Makers that do not yet have an engine attached

Create an engine for a market maker; always created PAUSED

One engine with its full configuration

Update configuration; validates first, then snapshots, then writes

Delete an engine and cascade to all of its data

Change status to ACTIVE, PAUSED or STOPPED

Archive and clear the current win-rate period

Current period and historical statistics; days and isDemo query parameters

Tracked positions; filter by status and whale flag

The engine action log; filter by action type

Bulk lifecycle

Pause every ACTIVE engine; reversible with resume-all

Resume every PAUSED engine

Archive and reset the win-rate period on every engine

Stop every ACTIVE engine immediately; a reason is required

The status response carries engineAttached — whether this process is genuinely running the engine rather than merely recording that it should. Treat status: "ACTIVE" with engineAttached: false as a broken install.

Creating an engine returns 400 for an out-of-contract payload, 404 when the market maker does not exist, and 400 when that market maker already has an engine. Activating returns 400 with a readable message when the market maker is not running.

User tiers

List tiers, optionally scoped to one engine

Create a tier for an engine

One tier

Update a tier

Delete a tier

Validation: winRateBonus 0–0.2, tierOrder 0–1000, maxVolume strictly greater than minVolume, and a non-empty name on create.

Cooldowns

List active and historical cooldowns with their engine

One cooldown

Update reduction, expiry or active flag

Delete a cooldown row, history included

Deactivate every active cooldown; history retained; optionally scoped to one engine

Validation: winRateReduction 0–1, expiresAt a parseable date.

Snapshots

List snapshots with their engine

Create a snapshot for an engine given in the body

Create a snapshot for an engine given in the path

Create one snapshot per engine

One snapshot with its configuration and performance capture

Delete a snapshot

Restore a snapshot; auto-snapshots current state first

Analytics

Machine learning

Recommended win rate for an engine; targetMetric of PROFIT, RETENTION or BALANCED

Train the win-rate model on historical data, in a worker thread

Cohorts

List cohort definitions for an engine

Create a cohort definition

Eight predefined cohort templates

Full metrics for one cohort

Compare metrics across several cohorts

Delete a cohort definition

A/B tests

List an engine's A/B tests

Create and start a test; only one may run per engine

Arm metrics, significance, winner and recommendation

Stop a running test

Apply the winning arm's configuration to the engine

Time of day

Hour-of-day and day-of-week metrics, in UTC

Per-hour win-rate recommendations with reasoning

Price correlation

Current monitoring status and statistics for an engine

Update monitoring configuration; writes the engine columns, not just the JSON blob

Run a single comparison now

Historical correlation samples for a symbol

Deviation alerts for an engine

Acknowledge an alert

Resolve an alert

The config endpoint accepts both vocabularies: enabled or enableExternalCorrelation; deviationThresholdPercent (a percentage) or maxDeviationPercent (a fraction); providers (a list, first entry becomes the primary) or externalPriceSource (a single name). It returns 404 for an unknown engine rather than a cheerful success, and 400 for an unknown provider or for enabling monitoring with no provider at all.

Settings

Global settings are not served by this addon. The Settings page reads and writes binaryAiEngine* keys through the core platform settings endpoint:

Read and write the binaryAiEngine* platform settings, changed keys only

Every key is documented in Global settings.

The settlement hooks

Core binary trading reaches the addon through three functions, resolved lazily so an install without the addon simply has no engine.

Hook	Called from	Effect when absent
`getBinaryAiSettlementPrice(order, realClose)`	The settlement path, three call sites	Returns the real close
`reconcileBinaryAiSettlement(order)`	After the settlement transaction commits	No-op
`getBinaryAiMaxOrderExposure(symbol)`	Order placement, live orders only	No cap

The exposure lookup is asynchronous on purpose — the in-memory engine map is populated on the main thread while order placement happens anywhere. Its caller must await it: an un-awaited promise reads as "no cap" and silently disables the limit everywhere.

Database tables

Thirteen tables, all prefixed binary_ai_engine. Deleting an engine cascades to every one of them.

Table	Holds
`binary_ai_engine`	One row per engine: configuration and live period counters
`binary_ai_engine_position`	One row per tracked order, with the steering decision and outcome
`binary_ai_engine_action`	The append-only action log
`binary_ai_engine_daily_stats`	Archived period statistics
`binary_ai_engine_user_tier`	Per-engine tier ladder
`binary_ai_engine_user_cooldown`	Active and historical cooldowns
`binary_ai_engine_snapshot`	Configuration snapshots
`binary_ai_engine_simulation`	Simulation runs
`binary_ai_engine_ab_test`	Experiment definitions and state
`binary_ai_engine_ab_test_assignment`	User-to-arm assignments
`binary_ai_engine_cohort`	Cohort definitions
`binary_ai_engine_correlation_alert`	Deviation alerts
`binary_ai_engine_correlation_history`	Correlation samples

binary_ai_engine.marketMakerId carries a unique index — one engine per market maker — and status is indexed for the restart-recovery query.

The driver returns every DECIMAL as a string. Target win rates, thresholds, profits and adjustment percentages are all DECIMAL. If you query these tables directly, coerce before you add — string concatenation is the failure mode, and it is silent.

Enum values

Column	Values
`binaryAiEngine.status`	`ACTIVE`, `PAUSED`, `STOPPED`
`practiceMode`	`DISABLED`, `SAME_AS_LIVE`, `CUSTOM`
`optimizationStrategy`	`CONSERVATIVE`, `MODERATE`, `AGGRESSIVE`
`whaleStrategy`	`REDUCE_EXPOSURE`, `ALERT_ONLY`, `FORCE_LOSS`
`tierCalculationMethod`	`VOLUME`, `DEPOSIT`, `MANUAL`
`externalPriceSource`	`BINANCE`, `COINGECKO`, `CRYPTOCOMPARE`
`allowedOrderTypes`	`RISE_FALL`, `HIGHER_LOWER`, `TOUCH_NO_TOUCH`, `CALL_PUT`, `TURBO`
Position `side`	`RISE`, `FALL`
Position `outcome`	`PENDING`, `WIN`, `LOSS`, `DRAW`
Position `status`	`ACTIVE`, `SETTLED`, `CANCELLED`
Cooldown `reason`	`BIG_WIN`, `STREAK`, `MANUAL`
A/B test `status`	`DRAFT`, `RUNNING`, `COMPLETED`, `CANCELLED`, `STOPPED`, `PAUSED`
A/B test `primaryMetric`	`WIN_RATE`, `PROFIT`, `RETENTION`, `VOLUME`
Alert `severity`	`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`

Note that only RISE_FALL is ever steered, regardless of what allowedOrderTypes contains. Every other type settles fairly.

The cron job

Property	Value
Name	`processBinaryAiEngine`
Category	`binary_ai_engine`
Period	10 seconds
Gated on	The `binary_ai_engine` extension row being enabled

It supervises lifecycle, restart recovery, the kill switch, period rollover, A/B test expiry, correlation monitor reconciliation and ML auto-apply. The per-second steering loop is separate and lives inside the engine singleton.