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

# AI Traders

> How to create and manage AI-powered trading accounts on Hyperoru.

An **AI Trader** is the core unit of Hyperoru. Each trader is an independent trading account with its own exchange wallet, its own language-model configuration, and its own strategy. You can run many in parallel, each pursuing a different thesis.

## What a trader holds

| Part                  | Role                                                                  |
| --------------------- | --------------------------------------------------------------------- |
| **Exchange wallet**   | The Hyperliquid API Wallet or Binance key/secret used to sign orders. |
| **LLM configuration** | Provider, model, API key, and base URL for prompt-based strategies.   |
| **Strategy binding**  | The prompt or program the trader consults when a signal fires.        |
| **Risk settings**     | Maximum leverage, notional, and concurrent positions.                 |
| **Trade history**     | Every decision, prompt, reasoning, order, and fill.                   |

<Note>
  Traders are fully isolated. A bug or misconfiguration in one trader never affects another.
</Note>

## Creating a trader

You can create a trader from the app's **AI Traders** screen or via the API.

<Steps>
  <Step title="Create the trader">
    ```bash theme={null}
    curl -X POST https://api.production.hyperoru.com/api/account/ \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "BTC Momentum",
        "description": "Trend-following strategy for BTC perpetuals",
        "llm_provider": "openai",
        "llm_model": "gpt-4o"
      }'
    ```

    The response includes the new `account_id`. You will use it in every subsequent call.
  </Step>

  <Step title="Configure the language model">
    Update LLM settings via `PUT /api/account/{account_id}`:

    ```bash theme={null}
    curl -X PUT https://api.production.hyperoru.com/api/account/$ACCOUNT_ID \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "llm_provider": "openai",
        "llm_model": "gpt-4o",
        "llm_api_key": "sk-your-api-key",
        "llm_base_url": "https://api.openai.com/v1"
      }'
    ```

    <Tip>
      Hyperoru speaks the OpenAI chat-completions protocol. Anthropic, Google, DeepSeek, and any OpenAI-compatible gateway all work by changing `llm_base_url` and `llm_model`.
    </Tip>
  </Step>

  <Step title="Connect an exchange wallet">
    See [Exchange setup](/trading/exchange-setup) for per-exchange instructions. Hyperliquid uses an API Wallet; Binance uses an API key and secret (without withdrawal permission).
  </Step>

  <Step title="Bind a strategy">
    Attach a prompt or program so the trader knows what to do when a signal fires:

    ```bash theme={null}
    curl -X PUT https://api.production.hyperoru.com/api/account/$ACCOUNT_ID/strategy \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "strategy_id": "strat_abc", "strategy_kind": "prompt" }'
    ```

    See [Prompt strategies](/trading/prompt-strategies) and [Program strategies](/trading/program-strategies).
  </Step>
</Steps>

## LLM providers

Any provider that exposes the OpenAI chat-completions API works. Typical configurations:

| Provider                       | `llm_base_url`                                     | Example models                                          |
| ------------------------------ | -------------------------------------------------- | ------------------------------------------------------- |
| OpenAI                         | `https://api.openai.com/v1`                        | `gpt-4o`, `gpt-4o-mini`                                 |
| Anthropic                      | `https://api.anthropic.com/v1`                     | `claude-sonnet-4-20250514`, `claude-3-5-haiku-20241022` |
| Google Gemini                  | `https://generativelanguage.googleapis.com/v1beta` | `gemini-2.0-flash`                                      |
| DeepSeek                       | `https://api.deepseek.com/v1`                      | `deepseek-chat`, `deepseek-reasoner`                    |
| LLM Gateway (aggregator)       | Your gateway URL                                   | Any model the gateway exposes                           |
| Any OpenAI-compatible provider | Their OpenAI-compatible base URL                   | Any model they expose                                   |

<Note>
  Hyperoru stores your LLM key encrypted at rest and never exposes it back to the browser. See [Trust and safety](/guides/security-and-trust).
</Note>

## Trader lifecycle

<AccordionGroup>
  <Accordion title="Start trading" defaultOpen>
    Toggle the trader on in the app, or set it active via the API. Once active, the trader listens for signal fires and runs its strategy.
  </Accordion>

  <Accordion title="Pause trading">
    The fastest way to halt new orders without losing configuration. Existing positions remain open at the exchange.

    ```bash theme={null}
    curl -X POST https://api.production.hyperoru.com/api/account/$ACCOUNT_ID/disable-trading \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Accordion>

  <Accordion title="Trigger a decision manually">
    Useful for testing a strategy without waiting for a signal:

    ```bash theme={null}
    curl -X POST https://api.production.hyperoru.com/api/account/$ACCOUNT_ID/trigger-ai-trade \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "symbol": "BTC" }'
    ```
  </Accordion>

  <Accordion title="Delete a trader">
    Soft-delete. The trader stops executing but trade history is preserved for analytics:

    ```bash theme={null}
    curl -X DELETE https://api.production.hyperoru.com/api/account/$ACCOUNT_ID \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Accordion>
</AccordionGroup>

## Dashboard status

Traders surface on the dashboard with one of these states:

| Status     | Meaning                                                                 |
| ---------- | ----------------------------------------------------------------------- |
| **Active** | Listening for signals and executing decisions.                          |
| **Paused** | Configured but not executing.                                           |
| **Error**  | The last execution failed. Inspect the decision log for the root cause. |

## Related

<Columns cols={2}>
  <Card title="Prompt strategies" icon="message" href="/trading/prompt-strategies">
    Describe how to trade in plain English.
  </Card>

  <Card title="Program strategies" icon="code" href="/trading/program-strategies">
    Write Python rules you control precisely.
  </Card>

  <Card title="Exchange setup" icon="vault" href="/trading/exchange-setup">
    Connect Hyperliquid or Binance safely.
  </Card>

  <Card title="Signal system" icon="signal" href="/trading/signal-system">
    Decide when strategies run.
  </Card>
</Columns>