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

# Bots

> Connect a broker account, allocate it across strategies, and manage bot execution.

##### Bots

Use this reference to submit bot allocation targets, display budgets from API responses, and manage bot lifecycle effects. AlphaInsider calculates adjusted allocation weights and broker orders.

##### Agent bot workflow

Read [authentication and requests](https://api.alphainsider.com/resources/introduction.md#authentication-and-requests) and [unscaled values](https://api.alphainsider.com/resources/trading.md#unscaled-values), then select the exact operation from the [bot operation index](https://api.alphainsider.com/resources/agent-skill.md#bots). Use `ALPHAINSIDER_BOT_ID` only when an explicit `bot_id` was not supplied; ask if a required ID remains unresolved. Check HTTP status and `success` before using a response.

##### Bot model

A bot executes in a connected broker account. Create/configure/start only within the user's authorized scope. Rebalance through bot strategy allocations; `newOrderAllocations` changes positions inside a normalized AlphaInsider strategy.

Before setup or starting, check [account limits](https://api.alphainsider.com/resources/limits.md#operation-specific-limits), broker connectivity, strategy subscriptions, and the current bot state. Start requires an off bot, at least one configured allocation, valid broker credentials, permitted active-bot/allocation counts, and broker value of at least \$2,000 for stocks or \$100 for crypto. Settings remain subject to the account tier and broker's leverage/slippage limits; use the current operation contract and account context.

Create with `newBot`, set complete targets with `updateBotAllocations`, configure optional settings/notifications, start, and confirm execution state. A successful mutation response does not establish that broker work has finished.

##### Allocation rules

`updateBotAllocations` replaces all allocations. Submit only each entry's `strategy_id` and numeric `percent`. Require unique strategies, finite fractions from `0` to `1` in `0.0001` increments, and a sum at most `1`. Bot leverage does not increase this sum limit. Each entry requires an active subscription to an active strategy matching the bot's stock/crypto type; positive weights require a positive strategy value. The account's allocation-count limit also applies.

Read the complete current allocation list before changing it. The response's `percent` values are performance-adjusted decimal strings, not immutable saved input weights; see [allocation weight drift](https://api.alphainsider.com/resources/bots.md#allocation-weight-drift). Establish the complete desired targets and validate their numeric JSON types, increments, and sum before submission. Do not pass response objects or arbitrary-precision response weights straight back to the update endpoint. Do not silently round up or change other targets to make an invalid list pass. Replacement establishes a new allocation snapshot/baseline. An empty list removes all allocations and, on an active bot, can schedule a rebalance toward no positions. Review [lifecycle and account-wide effects](https://api.alphainsider.com/resources/bots.md#lifecycle) before applying changes.

##### Allocation budgets

Inputs are real `getBotInfo.broker_details.value` and the selected allocation's fraction. For a current budget, use the returned `getBotAllocations.percent`; for a proposed budget, use the intended `updateBotAllocations` target and label it as proposed. Require finite values, a nonnegative broker value, and a fraction from `0` to `1`; invalid or unavailable broker data makes the budget unavailable.

```text theme={null}
allocation_budget = broker_portfolio_value * allocation_percent
```

A \$10,000 portfolio at `0.25` gives a \$2,500 budget. No strategy multiplier applies. This is a budget display, not an instruction to place a \$2,500 broker order or an estimate of the broker cash left over.

```python theme={null}
# example: bot-budget
from decimal import Decimal as D
broker_value, allocation_percent = D('10000'), D('0.25')
allocation_budget = broker_value * allocation_percent
# Expected allocation_budget: 2500
```

Actual exposure also depends on broker buying power, bot leverage, the strategies' positions, fee/slippage reserves, broker minimums, and netting of overlapping or opposing positions. AlphaInsider computes the broker orders. `getBotAllocations.positions` contains normalized strategy positions; use each strategy's own [multiplier context](https://api.alphainsider.com/resources/trading.md#multiplier-context) and [position valuation](https://api.alphainsider.com/resources/trading.md#position-valuation) for quantity/currency displays. Do not apply the multiplier to broker values or allocation percentages.

##### Allocation weight drift

`getBotAllocations` and `wsBotAllocations` return weights already adjusted for strategy performance and bot leverage. Use each returned `percent` for current displays and [allocation budgets](https://api.alphainsider.com/resources/bots.md#allocation-budgets). The server keeps the baselines used for this adjustment; callers do not need to recreate them or apply leverage to returned weights.

A weight can change even when no one edits the allocation. For example, an allocation submitted as `0.6` may later return `"0.6346153846"`. Treat that as the current weight, not a request to rebalance back to `0.6`. To change targets, submit the full intended allocation list to `updateBotAllocations`, following its numeric types, increments, and sum limit. See [allocation rules](https://api.alphainsider.com/resources/bots.md#allocation-rules).

##### Broker keys

Send only the selected broker's fields: Alpaca uses `alpaca_key`/`alpaca_secret`, Lighter `lighter_key`/`lighter_secret`, Hyperliquid `hyperliquid_key`/`hyperliquid_secret`, and Binance `binance_key`/`binance_secret`. Follow the current `newBot`/`broker_keys` schemas for supported account modes. Alpaca supports paper/live; Lighter is live-only.

Lighter uses an Ethereum L1 address and the private API key for the selected main/sub-account. Do not supply account or API-key indexes: the server resolves them and returns the internal account index as `account_id`. Hyperliquid accepts the optional `HL:` address prefix. Keep all credentials out of model-visible arguments, messages, logs, and commits; follow the private request guidance.

`updateBotBrokerKeys` requires the same broker account and paper/live mode as the existing bot. It cannot switch account, broker type, or mode. Create a new bot only when that change is authorized. Verify `getBotInfo.broker_status` before starting/restarting; valid credentials do not mean the bot is executing.

##### Lifecycle

Rebalancing cancels all open orders in the connected broker account and compares that account's positions with the complete bot targets. Existing unrelated holdings can be closed. Closing uses an empty target and can close broker positions across the account. Account setup and allocation updates therefore need the user's intended account-wide scope.

New bots default to status `off`, leverage `2`, slippage `0.005`, `rebalance_on_start: true`, and `close_on_stop: true`. Saved settings come from `getBots` and change through `updateBotSettings`. Explicit `startBot.rebalance_on_start` or `stopBot.close_on_stop` overrides the saved flag for that request, including an explicit `false`; it does not update the saved setting.

| Operation | Execution/history effect |
| - | - |
| `startBot` | Requires off state; sets `on` or `scheduled_rebalance` according to the effective flag. |
| `stopBot` | For an active bot, schedules closure when the effective flag is true; otherwise moves toward stopping. Read the resulting state, especially if already closing. |
| `updateBotAllocations` | Replaces targets/baselines and requests a reset; an active bot can rebalance immediately. |
| `updateBotSettings` with changed leverage | Updates allocation baselines and requests a reset; an active bot can rebalance immediately. |
| `resetBot` | Active states schedule rebalance; closing states reschedule closure. It does not start an off bot or factory-reset settings/history. |
| `resetBotPerformance` | Deletes performance history and records a new broker-value baseline; it does not close positions. |
| `deleteBot` | Deletes the bot record without a stop or liquidation operation. Do not treat deletion as a flattened account. |

Use `getBots` or `wsBotStatus:<bot_id>` to observe execution status: `off`, `scheduled_rebalance`, `rebalancing`, `on`, `scheduled_close`, `closing`, or `stopping`. `getBotInfo` reports broker connectivity/details, not bot execution status. Confirm the expected terminal state and inspect broker positions/activity before reporting completion. Reset, performance reset, deletion, and closure must stay within the user's requested action.

##### Monitoring

Use `getBotInfo` for broker values and positions, `getBotAllocations`/`wsBotAllocations` for adjusted weights, `getBotPerformance` for real portfolio history, and `getBotActivities`/`wsBotActivities` for errors and activity. `getBotInfo.broker_details` and `getBotPerformance.portfolio_value` are already real broker values.

After a timeout or uncertain mutation, follow [response and retry decisions](https://api.alphainsider.com/resources/introduction.md#responses-and-retry-decisions): inspect status, settings, allocations, broker state, and activities before another request. Do not repeat start/reset/allocation changes merely because an acknowledgement was lost. Use [connection and recovery](https://api.alphainsider.com/resources/websockets.md#connection-and-recovery) after stream loss, resubscribe to the complete channel list, and refresh REST snapshots/activity history; a reconnect does not authorize a rebalance.

##### Agent checklist

* Confirm the bot, broker account/mode, subscriptions, limits, and authorized account-wide effects.
* Submit a complete, valid allocation list and distinguish current adjusted weights from new target inputs.
* Keep real broker values separate from nested normalized strategy positions.
* Confirm execution state through `getBots` or `wsBotStatus`, and reconcile uncertain changes before retrying.


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