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

# Telegram Commands

> Bot command reference

The ouroborai Telegram bot is built with [grammY](https://grammy.dev) and
provides access to core agent functionality through chat commands.

## Setup

Start the bot with:

```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
cd apps/telegram
TELEGRAM_BOT_TOKEN=your_bot_token \
API_URL=https://your-api.railway.app \
bun run dev
```

## Commands

<AccordionGroup>
  <Accordion title="/start">
    **Description**: Initialize the bot and display a welcome message with
    available commands.

    **Parameters**: None

    **Example**:

    ```
    /start
    ```

    **Response**: Welcome message with command overview and inline buttons
    for common actions.
  </Accordion>

  <Accordion title="/health">
    **Description**: Check API server health status.

    **Parameters**: None

    **Example**:

    ```
    /health
    ```

    **Response**: Server status, uptime, and chain connection info.
  </Accordion>

  <Accordion title="/trade">
    **Description**: Execute a spot token swap on Arbitrum.

    **Parameters**:

    * `amount` -- Amount to swap (human-readable)
    * `tokenIn` -- Input token symbol
    * `for` -- Literal keyword
    * `tokenOut` -- Output token symbol

    **Example**:

    ```
    /trade 100 USDC for ARB
    /trade 0.5 ETH for USDC
    ```

    **Flow**:

    1. Bot parses the trade parameters
    2. Fetches a quote from the API
    3. Displays quote with confirm/cancel inline buttons
    4. On confirm, submits the swap and returns the transaction hash
  </Accordion>

  <Accordion title="/perp">
    **Description**: Open or close a leveraged perpetual position on GMX V2.

    **Parameters**:

    * `action` -- `open` or `close`
    * `leverage` -- Leverage multiplier (for open)
    * `side` -- `long` or `short`
    * `market` -- Market pair (ETH, BTC, ARB, LINK)
    * `collateral` -- USDC collateral amount (for open)

    **Examples**:

    ```
    /perp open 10x long ETH 500
    /perp close long ETH
    ```

    **Flow**:

    1. Bot validates parameters
    2. Displays position summary with confirm/cancel buttons
    3. On confirm, submits the order to GMX V2 keepers
  </Accordion>

  <Accordion title="/portfolio">
    **Description**: View current wallet balances and DeFi positions.

    **Parameters**: None

    **Example**:

    ```
    /portfolio
    ```

    **Response**: Formatted summary including:

    * ETH and USDC balances
    * Aave V3 health factor, collateral, and debt
    * Open GMX V2 positions with PnL
    * TimeBoost express lane status
  </Accordion>

  <Accordion title="/timeboost">
    **Description**: View TimeBoost express lane status and optionally
    submit a bid.

    **Parameters** (optional):

    * `bid` -- Keyword to submit a bid
    * `amount` -- Bid amount in ETH

    **Examples**:

    ```
    /timeboost
    /timeboost bid 0.002
    ```

    **Response (status)**: Current round number, controller address, time
    remaining in round, and whether you control the express lane.

    **Response (bid)**: Bid confirmation with round number and amount.
  </Accordion>
</AccordionGroup>

## Inline Callbacks

The bot uses Telegram inline keyboard buttons for action confirmation:

| Callback        | Action                     |
| --------------- | -------------------------- |
| `confirm_trade` | Execute the quoted swap    |
| `cancel_trade`  | Cancel the pending swap    |
| `confirm_perp`  | Submit the perpetual order |
| `cancel_perp`   | Cancel the perpetual order |
| `confirm_bid`   | Submit the TimeBoost bid   |
| `cancel_bid`    | Cancel the bid             |

All destructive actions (trades, positions, bids) require explicit
confirmation through inline buttons before execution.

## Natural Language

In addition to structured commands, you can send natural language prompts
directly to the bot. These are forwarded to the agent API as
`POST /agent/prompt`:

```
Swap 50 USDC for ARB on Uniswap
What's the current price of ETH?
Supply 1000 USDC to Aave
```

The bot polls the job status and replies with the agent's response when
complete.

## CLI Commands

The ouroborai CLI provides terminal-based access to the same agent
functionality:

```bash theme={"theme":{"light":"dracula","dark":"dracula"}}
# Pipe a prompt directly
echo "What is my ETH balance?" | ouroborai

# Interactive mode
ouroborai --interactive

# Single command
ouroborai prompt "Swap 100 USDC for ARB"
ouroborai portfolio
ouroborai health
```

The CLI reads `API_URL` from the environment or defaults to
`http://localhost:3000`.