Skip to main content
The ouroborai Telegram bot is built with grammY and provides access to core agent functionality through chat commands.

​
Setup

Start the bot with: 
cd apps/telegram
TELEGRAM_BOT_TOKEN=your_bot_token \
API_URL=https://your-api.railway.app \
bun run dev

​
Commands

Description: Initialize the bot and display a welcome message with available commands.Parameters: NoneExample:
/start
Response: Welcome message with command overview and inline buttons for common actions.
Description: Check API server health status.Parameters: NoneExample:
/health
Response: Server status, uptime, and chain connection info.
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
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
Description: View current wallet balances and DeFi positions.Parameters: NoneExample:
/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
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.

​
Inline Callbacks

The bot uses Telegram inline keyboard buttons for action confirmation:
CallbackAction
confirm_tradeExecute the quoted swap
cancel_tradeCancel the pending swap
confirm_perpSubmit the perpetual order
cancel_perpCancel the perpetual order
confirm_bidSubmit the TimeBoost bid
cancel_bidCancel 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: 
# 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.