# Telegram Bot

The Telegram bot provides a chat-based wallet and OTC experience. It integrates public marketplace state, wallet actions, and guided OTC flows into a Telegram-native interface.

The Telegram Bot stores user-facing session and referral state in the application database. The internal storage backend is intentionally not documented in the public GitBook.

## Core Features

* Create/import/disconnect wallet.
* View balances.
* Deposit and withdraw.
* Configure settings.
* Open marketplace and OTC pages.
* Create bids and asks.
* Sell into bids.
* Buy asks.
* View active and archived swaps.
* Recover pending OTC flows.
* Referral program.
* Volume leaderboard and future points context through Black Pearl Market growth channels.
* History export.

## Referral And Growth Features

Black Pearl Market referrals are designed to reward users who help grow OTC activity across the PEARL ecosystem. Users can open the referral panel with `/referral`, share their referral link where available, and follow referral-related activity from the Telegram bot.

Referral claiming is currently paused while Black Pearl Market prepares a more engaging competition and gamification model for an upcoming release. Users can still prepare by sharing their referral link and following official announcements.

Leaderboard points, referral activity, and future reward mechanics are subject to final official rules and do not guarantee financial rewards unless future official rules explicitly state otherwise.

## Runtime Principles

* The bot follows a non-custodial session model. User private keys and seed phrases are not persisted by the bot.
* Bot-Assisted asks are paused on startup and resumed only after readiness checks, which helps keep automated flows aligned with wallet balance, UTXO, gas, and indexer state.
* Readiness includes seller wallet continuity, Pearl balance, UTXO availability, and EVM gas where applicable.
* The recovery loop checks indexer health and canonical swap state before continuing automated flows.

## Public Documentation Boundary

Operator-only bot internals, storage layout, credentials, private callbacks, and deployment procedures are intentionally excluded from public documentation.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blackpearlmarket.com/overview-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.