Deals & Trading Tools - Teleton Agent Documentation

How It Works

The deals system enables P2P trading of Telegram gifts (Star Gifts / collectibles) between the agent and users. Trades are proposed via inline bot buttons, verified on-chain, and auto-executed.

Grammy inline bot : sends deal cards with Accept/Decline buttons directly in chat (requires bot_token in config)
DM-only scope : deal_propose, deal_verify_payment, and deal_cancel can only be used in direct messages
Strategy enforcement : every deal is checked against configurable rules (buy_max_floor_percent, sell_min_floor_percent) before creation
On-chain verification : TON payments verified via blockchain with deal ID as memo; gift transfers detected via telegram_get_my_gifts
Replay protection : atomic status transitions prevent double-spend from concurrent pollers
Auto-execution : after payment verification, the agent automatically sends its part (TON or gift)

Deal States

State Machine

proposed     # Deal created, waiting for user to Accept/Decline
accepted     # User clicked Accept, waiting for payment
verified     # Payment confirmed on-chain
completed    # Agent sent its part, deal done
declined     # User clicked Decline
expired      # 2-minute timeout elapsed
cancelled    # Manually cancelled before verification
failed       # Execution error after verification

Available Tools

Tool	Scope	Description
`deal_propose`	DM only	Create a trade proposal with inline Accept/Decline buttons. Checks strategy compliance before creation. Supports gift-for-TON, TON-for-gift, and gift-for-gift swaps.
`deal_verify_payment`	DM only	Verify user's payment for an accepted deal. For TON: checks blockchain for TX with deal ID memo. For gifts: polls for newly received gift matching expected slug. Auto-triggers execution on success.
`deal_status`	Any	Check full status and details of a deal by ID. Shows parties, assets, timestamps, payment tracking, profit calculation, and strategy check results.
`deal_list`	Any	List recent deals with optional filters by status, user ID, and limit. Includes P&L totals and status counts. Non-admins can only see their own deals.
`deal_cancel`	DM only	Cancel a deal in proposed or accepted status. Cannot cancel verified/completed deals. Notifies user in chat if deal was already accepted.

Deal Flow

Example: Agent Buys a Gift

# 1. Agent proposes to buy user's gift for TON
deal_propose:
  chatId: "123456789"
  userId: 987654321
  userGivesType: gift
  userGivesGiftSlug: "DeluxeHeart-551203"
  userGivesValueTon: 50.0
  agentGivesType: ton
  agentGivesTonAmount: 40.0
  agentGivesValueTon: 40.0
  # Strategy check: 40/50 = 80% of floor -> compliant

# 2. User clicks Accept on inline bot card
# (handled by Grammy bot callback)

# 3. User sends gift to agent's account

# 4. Agent verifies gift receipt
deal_verify_payment:
  dealId: "d_7f3k9"
  # Gift detected -> status = 'verified'
  # Auto-executes: agent sends 40 TON to user's wallet

# 5. Check result
deal_status:
  dealId: "d_7f3k9"
  # -> status: completed, profit: 10 TON

Strategy Enforcement

Every deal is validated against STRATEGY.md rules at the code level. Deals that violate strategy are rejected before creation.

Scenario	Rule	Default
Agent buys gift (pays TON)	Pay at most `buy_max_floor_percent` of floor price	100% (never above floor)
Agent sells gift (receives TON)	Charge at least `sell_min_floor_percent` of floor price	105% (floor + 5%)
Gift-for-gift swap	Agent must receive equal or greater value	-

Configure in config.yaml under deals:

config.yaml

deals:
  enabled: true
  buy_max_floor_percent: 80      # Pay max 80% of floor
  sell_min_floor_percent: 115    # Charge min 115% of floor
  expiry_seconds: 120            # Deal expires in 2 minutes
  poll_interval_ms: 5000         # Payment check every 5s
  max_verification_retries: 12   # 60s max verification wait

Security