sky-bullpen

bynBA 00

https://app.bullpen.fi/

No preview

Comments (0)

No comments yet. Be the first!

System Requirements

System Requirements Document for Bullpen

1. Introduction

Bullpen is a Telegram trading bot. Its entire user-facing product surface is a Telegram chat: traders send trade commands to the bot in Telegram and check positions and results in that same chat, while a Bot Operator connects the bot to the trading account and keeps it running, watching bot status and errors.

The product intent is a crypto trading assistant that lives where its users already are — inside Telegram — rather than in a separate web terminal. The reference material at https://app.bullpen.fi/ is used only as domain context for crypto trading features (perpetuals and spot trading, order types, discovery, transfers, funding, non-custodial wallets, and a legacy Telegram bot that lets users paste token addresses, analyze, and trade within Telegram). It does not add web-terminal pages, wallet-login surfaces, or any other capability to this product. The product is a Telegram trading bot.

The audience is crypto traders who want to issue and monitor trades conversationally, and the operator responsible for the bot's connection to the trading account and its runtime health.

Page 1 of 15

2. System Overview

Bullpen is delivered as a Telegram bot backed by a shared FastAPI backend process and a MariaDB database for application-owned persistent data. There is no custom web UI: all trader and operator interaction happens on the Telegram provider surface (chat messages, commands, and bot replies). The backend holds the bot's connection to the trading account, executes trade commands received from Telegram, records positions and results, and exposes bot status and error information back into the chat.

Actors:

  • Trader — starts a Telegram chat with the bot, sends trade commands, and checks positions and results in the same chat.
  • Bot Operator — connects the bot to the trading account and keeps it running; watches bot status and errors.

Accepted behavior in scope: the bot operates in Telegram chat as its user interface; the Bot Operator connects the bot to the trading account; the Trader starts a Telegram chat with the bot; the Trader sends trade commands and checks positions and results in the same chat; the Bot Operator watches bot status and errors.

Narrow exclusions: no first-party web application, no web trading terminal, no in-product wallet creation or key export flows, and no capabilities beyond what the Telegram chat and the operator's connection/status responsibilities require.

Removed from scope

Page 2 of 15
  • Web-based trading terminal (also: app.bullpen.fi interface, web app)
  • Non-custodial wallet provisioning and private-key export (also: Turnkey wallets, wallet/X/Google/email login)
  • Fiat on-ramps and exchange transfers (also: cards, ACH, Apple Pay, Google Pay)
  • Discovery tools (also: Runners, Memescope, whale tracking)
  • Cross-chain and intra-platform transfers between Solana and Hyperliquid

2a. Product Interpretation and Delivery Boundary

Bullpen's delivery boundary is the Telegram provider surface. Traders and the Bot Operator do not receive a first-party web destination; they interact through Telegram chat with the bot, and the bot's replies are the observable product state. The shared FastAPI backend is the application-owned system of record: it maintains the bot's connection to the trading account, processes trade commands, persists positions and results, and surfaces status and errors. MariaDB stores that application-owned persistent data.

Access follows the provider: Telegram identity is the interaction identity, and the bot is reachable in chat once the Bot Operator has connected it to the trading account. The operator's connection responsibility is a prerequisite for trader journeys, not a separate web console. Nothing in this document establishes differentiated permissions, role-based visibility, or account-management features; the two personas differ by responsibility, not by a permission system described in the sources.

Current horizon: Telegram chat trading commands, position and result reporting in chat, operator connection of the trading account, and operator visibility of bot status and errors. Future ideas from the reference material (web terminal, wallets, on-ramps, discovery, transfers) are not current and are not represented in any page or acceptance criterion.

Page 3 of 15

2c. Page Content and Component Coverage

The page contract for this product is the Telegram bot chat surface. There is no custom first-party page; the single accepted destination is the provider-managed Telegram chat with the bot.

Page 4 of 15

Telegram Bot Chat

  • Information and state: the bot's conversational replies; the current connection state of the trading account as reflected in bot responses; the trader's open positions and their results as reported in chat; bot status and error messages surfaced to the operator.
  • Primary actions: Trader sends a trade command in chat; Trader requests positions and results; Bot Operator issues the connection action for the trading account and checks bot status.
  • Supporting actions: Trader starts the chat with the bot; Bot Operator reviews error messages and re-checks status after recovery.
  • Domain entities: trading account connection, trade command, position, trade result, bot status, bot error.
  • Component responsibilities: Telegram provider delivers messages and commands; the shared FastAPI backend validates and executes trade commands, persists positions and results, tracks connection state, and composes status/error replies; MariaDB stores connection state, positions, results, and status/error records.
  • States:
    • Loading: command acknowledged in chat while the backend processes it.
    • Empty: no open positions — the bot reports that there are none.
    • Success: trade command executed and confirmed in chat; positions and results returned in chat; connection confirmed to the operator.
    • Error: command rejected or execution failed — the bot reports the failure in chat; connection failure — the operator sees the error and can retry the connection.
    • Recovery: the trader reissues a corrected command; the operator re-runs the connection and re-checks status.
Page 5 of 15

3. Functional Requirements

FR-1 — Telegram chat as the product interface (explicit) As a Trader, I should interact with Bullpen entirely inside a Telegram chat, so that I can trade without leaving Telegram.

  • Trigger/input: the Trader opens the bot chat in Telegram.
  • Observable result: the bot responds in the same chat and all subsequent interaction occurs there.
  • Access state: Telegram provider surface; no first-party web page.
  • Failure/recovery: if the bot does not respond, the Trader retries in chat; the Bot Operator checks bot status.
  • Continuation: the Trader proceeds to send trade commands or request positions.

FR-2 — Start a chat with the bot (required_inference) As a Trader, I should start a Telegram chat with the bot, so that I have a channel to issue commands and receive results.

  • Trigger/input: the Trader initiates the chat with the bot in Telegram.
  • Observable result: the chat is established and the bot is addressable.
  • Access state: Telegram identity; the bot must already be connected to the trading account by the Bot Operator for trading commands to succeed.
  • Failure/recovery: if the bot is not yet connected, trading commands fail with a chat message explaining the bot is not ready; the Trader retries after the operator connects it.
  • Continuation: the Trader sends a trade command.
Page 6 of 15

FR-3 — Send trade commands in chat (explicit) As a Trader, I should send trade commands to the bot in Telegram, so that trades are executed on my behalf.

  • Trigger/input: a trade command message sent in the bot chat.
  • Observable result: the backend executes the command against the connected trading account and the bot confirms the outcome in chat.
  • Access state: Telegram chat; trading account connected by the Bot Operator.
  • Failure/recovery: invalid or unexecutable commands produce an error reply in chat; the Trader corrects and resends.
  • Continuation: the Trader checks positions and results.

FR-4 — Check positions and results in the same chat (explicit) As a Trader, I should check my positions and results in the same Telegram chat, so that I can monitor outcomes without another tool.

  • Trigger/input: a positions/results request in the bot chat.
  • Observable result: the bot replies in chat with current positions and their results, or states that there are none.
  • Access state: Telegram chat.
  • Failure/recovery: if retrieval fails, the bot reports the error in chat and the Trader retries.
  • Continuation: the Trader issues further trade commands or ends the session.
Page 7 of 15

FR-5 — Connect the bot to the trading account (required_inference) As a Bot Operator, I should connect the bot to the trading account, so that trader commands can be executed.

  • Trigger/input: the operator performs the connection action for the trading account.
  • Observable result: the connection state is recorded and confirmed; trader commands become executable.
  • Access state: operator responsibility on the provider surface and backend.
  • Failure/recovery: a failed connection is reported as an error the operator can see and retry.
  • Continuation: the operator watches bot status.

FR-6 — Keep the bot running and watch status and errors (explicit) As a Bot Operator, I should watch bot status and errors, so that the bot stays available for traders.

  • Trigger/input: the operator checks bot status and reviews error messages.
  • Observable result: current status and any errors are visible to the operator; recovery actions (such as reconnecting) can be taken.
  • Access state: operator responsibility.
  • Failure/recovery: on error, the operator diagnoses from the reported error and re-establishes the connection or restarts the bot.
  • Continuation: the operator continues monitoring.

4. User Personas

Page 8 of 15

Trader

  • Product context: A crypto trader who works inside Telegram and wants to issue and monitor trades conversationally rather than through a separate web terminal.
  • Primary goal: Execute trade commands and see positions and results without leaving the chat.
  • Distinct accepted responsibilities: Starts the chat with the bot, sends trade commands, and checks positions and results in the same chat.
  • Inputs and decisions: The trade command content (what to trade and how) and when to request positions/results; deciding whether to correct and resend after an error.
  • Interactions with other participants: Depends on the Bot Operator having connected the bot to the trading account; receives bot replies as the observable outcome of every action.
  • Observable success: Commands are confirmed in chat and positions/results are returned in the same chat.
Page 9 of 15

Bot Operator

  • Product context: The person responsible for the bot's connection to the trading account and its runtime health.
  • Primary goal: Keep the bot connected and running so traders can trade.
  • Distinct accepted responsibilities: Connects the bot to the trading account and watches bot status and errors.
  • Inputs and decisions: The trading account connection details/action; judgment on whether an error requires reconnection or restart.
  • Interactions with other participants: Enables Trader journeys by establishing the connection; sees status and errors that traders may also experience as failed commands.
  • Observable success: The connection is confirmed and status/error information is visible and actionable.

5. Core User Flows

Page 10 of 15

Flow A — Bot Operator connects the bot and monitors it

  1. The Bot Operator takes the connection action to connect the bot to the trading account.
  2. The backend records the connection state in MariaDB and confirms the connection to the operator.
  3. If the connection fails, the operator sees the error, diagnoses it, and retries the connection.
  4. The operator checks bot status and reviews any error messages.
  5. On an error, the operator re-establishes the connection or restarts the bot, then re-checks status.
  6. Continuation: the operator continues monitoring while traders use the bot.

Flow B — Trader starts the chat and issues a trade command

  1. The Trader starts a Telegram chat with the bot.
  2. The Trader sends a trade command in the chat.
  3. The backend validates and executes the command against the connected trading account and records the outcome.
  4. The bot confirms the executed trade in chat.
  5. If the command is invalid or cannot execute (including when the bot is not yet connected), the bot replies with an error in chat; the Trader corrects the command and resends, or waits for the operator to connect the bot.
  6. Continuation: the Trader proceeds to check positions and results.
Page 11 of 15

Flow C — Trader checks positions and results

  1. In the same Telegram chat, the Trader requests positions and results.
  2. The backend retrieves the trader's positions and results from MariaDB.
  3. The bot replies in chat with the positions and their results, or states that there are none.
  4. If retrieval fails, the bot reports the error in chat and the Trader retries.
  5. Continuation: the Trader issues further trade commands or ends the session.

6. Visuals Colors and Theme

The product has no first-party visual surface; its presentation is the Telegram chat. The only visual constraints are those of the Telegram provider: the bot's messages render in the user's Telegram theme, and message formatting (text, emphasis, structured position/result listings) should be legible in both light and dark Telegram themes. No custom palette, font, or layout is specified by the user, and none is invented here.

7. Signature Design Concept

The signature concept is conversational clarity: every bot reply is a compact, scannable chat message — a confirmation, a position/result listing, a status line, or an error — formatted so a trader can read the outcome at a glance inside Telegram. This recomposes only accepted content (commands, confirmations, positions, results, status, errors) and introduces no new behavior or destination.

Page 12 of 15

8. Interaction Model & Motion Direction

Interaction Model: Static (direction) Motion Tempo: still Hero Dimensionality: flat

Landing Hero Motion Brief: Not applicable — there is no first-party landing page. The entry experience is the Telegram chat itself: the Trader opens the chat and the bot's first reply is the composed first frame. There is no motion beyond Telegram's native message delivery; the reduced-motion state is identical because no custom animation is used.

9. Non-Functional Requirements

  • Provider-surface delivery (explicit): The bot operates in Telegram chat as its user interface; there is no custom web UI.
  • Durable state (required_inference): Connection state, positions, results, and status/error records persist in MariaDB so that positions and results can be reported across sessions and the operator can review status and errors.
  • Backend integration (required_inference): The shared FastAPI backend owns command execution, connection management, persistence, and reply composition; the Telegram provider delivers messages to and from it.
  • Error visibility (explicit): Bot errors are surfaced to the Bot Operator (status/error watching) and to the Trader as chat error replies, with retry paths.
  • Availability expectation (required_inference): The bot must remain running for traders to trade; the operator's monitoring responsibility exists to sustain this.
Page 13 of 15

10. Tech Stack

  • Telegram Bot — the product's user interface, delivered on the Telegram provider surface.
  • Backend — shared FastAPI process for application APIs and domain modules (command handling, connection management, position/result reporting, status/error reporting).
  • Database — MariaDB for application-owned persistent data (connection state, positions, results, status/error records).
  • Deployment — docker-compose with the backend and database services; no additional services are required for the accepted workflows.

11. Assumptions and Constraints

  • Constraint (explicit): The product is a Telegram trading bot; the bot operates in Telegram chat as its user interface.
  • Assumption: The Bot Operator has the trading account connection details needed to connect the bot; the exact connection mechanism is not specified by the source and is treated as an operator responsibility.
  • Assumption: Telegram identity is the interaction identity; no separate application account system or differentiated permissions are established by the sources.
  • Assumption: The reference material at https://app.bullpen.fi/ supplies crypto trading domain context only; its web-terminal, wallet, on-ramp, discovery, and transfer features are not current product scope.
  • Assumption: Trade command syntax and the set of supported order types are not specified beyond "trade commands"; the bot accepts trade commands in chat and reports outcomes.
Page 14 of 15

12. Glossary

  • Bullpen — the Telegram trading bot described in this document.
  • Trader — the persona who sends trade commands and checks positions and results in the Telegram chat.
  • Bot Operator — the persona who connects the bot to the trading account and watches bot status and errors.
  • Trade command — a message sent in the bot chat instructing the bot to execute a trade.
  • Position — an open trade holding reported to the Trader in chat.
  • Trade result — the outcome of an executed trade command, reported in chat.
  • Bot status — the current running/connection state of the bot, watched by the Bot Operator.
  • Bot error — a failure message surfaced to the operator and, where relevant, to the trader in chat.
  • Trading account connection — the link between the bot and the trading account that the Bot Operator establishes.
Page 15 of 15

No completed page designs yet.

Completed design pages will appear here when they are ready to preview.

connection succeeds

connection failure

error visible to operator

operator retries

connection confirmed

status retrieved

error present

recovery action taken

operator continues

1. Take connection action to connect bot to trading account

Connection confirmed to operator

2. Connection failure reported as error

3. Diagnose error and retry connection

1. Check bot status and review error messages

2. Status and errors visible to operator

3. On error, re-establish connection or restart bot

4. Re-check status and continue monitoring

No completed page designs yet.

Completed design pages will appear here when they are ready to preview.

connection succeeds

connection failure

error visible to operator

operator retries

connection confirmed

status retrieved

error present

recovery action taken

operator continues

1. Take connection action to connect bot to trading account

Connection confirmed to operator

2. Connection failure reported as error

3. Diagnose error and retry connection

1. Check bot status and review error messages

2. Status and errors visible to operator

3. On error, re-establish connection or restart bot

4. Re-check status and continue monitoring