BAQL Version 1.2.1

Abstract

BAQL (Bot Assistant Query Language) is a domain specific language used for expressing declarative requirements for Bot Assistant engines used in automated trading systems.

Its goal is to provide a flexible and ergonomic semantic to users and a machine parseable set of instructions that can be used to query for the requested data.

It’s designed to be platform agnostic, albeit some expressions might not be available in all dialects.

Syntax

The syntax of the language is currently maintained by The Trading Parrot community and it’s subject to evolution over time. It follows the rules of semantic versioning.

Queries are implicit assumed as part of the language, therefore it’s not required to have explicit imperative clauses.

Language Elements

• One sentence
• Prefix required to start the sentence
• Optional suffix at the end of the sentence to mark the end of the BAQL expression
• One or more actions are allowed in the sentence separated by space
• Each action contains one operator and a predicate
• No spaces are allowed within the action unless they are inside a list separator
• Each predicate depends on the operator
• Only one action per operator is allowed
• The maximum length of a valid BAQL query is limited to 500 characters, including the ignored ones
• Integer and Decimal numbers are allowed
• Widers numbers like 1000000 or -230000 could be written using multipliers
• A single or multiple number intervals can be defined
• Operators can accept both single and composite predicates. Composite predicates consist of a list of predicates
• Nested predicate lists aren’t allowed

Operators

Each action contains an operator and a predicate. Each operator comes with its own rules (criteria) but all of them should complain about the restrictions of BAQL grammar and syntax. The operators should be extensible and independent one each other.

Pairs Settings

Operator to command changes to the pairs settings of a bot.

PS Operator name

• Three criteria
  • Categories
  • Sort
  • Zero o more Filters

Signal

Operator to specify the bot wants to receive a specified custom signal.

SIG Operator name

• One argument
  • Signal name OR
  • List of Signal names

Orchestrator

Operator to complement the lifecycle of the bot and its deals.

ORC Operator name

• One argument
  • An orchestration definition OR
    • Orchestrator Provider
    • 1 or 2 orchestration commands
  • List of orchestration definitions

Comments

Comments are not allowed in BAQL.

Grammar

Here is the EBNF-like grammar of the BAQL. The spaces in the grammar definition are for human readability. The grammar described here isn’t meant to be 100% accurate. Here are some missing details:

• Numbers are expressed as regular expression to simplify their definition here
• Usage of quantifiers like ()* and ()+ and ()? to simplify the expression of occurrences

Main

sentence: prefix actions ((action_separator)* suffix)?

actions: action ((action_separator)+ action)*

prefix: 'BAQL:'

suffix: '!@'

action_separator: ' '

action: operator 
      | operator operator_separator predicate

operator: 'PS'
        | 'SIG'
        | 'ORC'

operator_separator: ':'

list_start: '[' 

list_end: ']'

list_separator: ' '

interval_start: '(' 

interval_end: ')'

interval_separator: '&'

decimal_number: [-+0-9\.]+(number_multiplier)

number_multiplier: ''
                 | 'K'
                 | 'M'
                 | 'B'
                 | 'T'
                 | 'Q'

Number multipliers:

Multiplier	Description	Example
K	Thousand	1K = 1000
M	Million	1M = 1000K
B	Billion	1B = 1000M
T	Trillion	1T = 1000B
Q	Quadrillion	1Q = 1000T

Best Practices using decimal numbers

• Use 1M instead of 1000000
• Use 1.25M instead of 1250000
• Use 0.001 instead of .001
• Choose 1.5K or 1500 both are great

Examples

❌ ALL_50_BUS

INVALID: Missing starting BAQL tag

❌ BAQL:ALL_50BUS

INVALID: No available actions

❌ BAQL:XXX:ALL_50BUS

INVALID: No available actions

PairsSettings Operator

predicate: categories criteria_separator sort criteria_separator filters

categories: 'ALL'
          | category_list

category_list: category (category_separator category)*

category: 'DEFI'
        | 'ERC'
        | 'NFT'
        | 'DOT'
        | 'BSC'
        | 'ZIL'
        | 'MEME'
        | 'SC'

category_separator: '&'

criteria_separator: '_'

sort: sort_number criteria_separator sort_keyword reverse_keyword

sort_number: [0-9]+
               
sort_keyword: 'LCGS'
            | 'LCAR'
            | 'DUSD'
            | 'DBTC'
            | 'HUSD'
            | 'SV'
            | 'BES'
            | 'BUS'
            | 'MC'
            | 'MV'
            | 'MCR'
            | 'CGR'
            | 'WUSD'

reverse_keyword: '.r'
               | ''
          
filters: filter (interval_separator filter)*

filter: interval_start (greater_equal_filter) filter_keyword (lower_equal_filter) interval_end

greater_equal_filter: range_number lower_equal

lower_equal_filter: lower_equal range_number

lower_equal: '≤'
           | '<='

range_number: decimal_number

filter_keyword: sort_keyword

Sort & Filter keywords:

Sort Name	Description	Default Sort Order
LCGS	LunarCrush Galaxy Scoretm 1	descending
LCAR	LunarCrush AltRanktm 1	ascending
DUSD	24h % change (USD) 2	descending
DBTC	24h % change (BTC) 2	descending
HUSD	1h % Change (USD) 2	descending
SV	Social Volume 1	descending
BUS	Bullish Sentiment (values between 1 and 5) 1	descending
BES	Bearish Sentiment (values between 1 and 5) 1	descending
MC	Market cap 2	descending
MV	Market volume 2	descending
MCR	Market cap rank 2	ascending
CGR	CoinGecko rank 2	ascending
WUSD	7 days % change (USD) 2	descending

Supported categories:

Category 1	Description
DEFI	DeFi
ERC	ERC-20
NFT	NFT
DOT	DOT ecosystem
BSC	BSC ecosystem
ZIL	ZIL ecosystem
SC	Stable coins
MEME	Meme coins

PairsSettings examples

Check the available Sort and Filters criteria.

✅ BAQL:PS:ALL_50_BUS

• All categories
• Top 50 tokens sorted by bullish sentiment

✅ BAQL:PS:MEME_25_DUSD

• Meme category
• Top 25 coins with highest daily %change in USD

✅ BAQL:PS:ALL_200_MC.r

• All categories
• Lowest 200 market cap tokens

✅ BAQL:PS:DEFI&NFT_25_DBTC

• Categories: DeFi & NFT
• Top 25 coins with daily % change in BTC

✅ BAQL:PS:ALL_10_LCAR

• All categories
• Top 10 AltRank^tm coins

✅ BAQL:PS:ALL_7_MCR

• All categories
• Top 7 tokens sorted by market cap rank

✅ BAQL:PS:ALL_10_CGR

• All categories
• Top 10 tokens sorted by CoinGecko rank

Check how to use number multipliers.

✅ BAQL:PS:ALL_50_LCGS_(250M≤MV≤1.2B)

• All categories
• Top 50 GalaxyScore^tm coins
• Filters:
  • Market volume is between 250 millions and 1.2 billion

✅ BAQL:PS:ALL_50_LCGS_(250M≤MV≤1.2B)&(0.1≤DBTC≤10)

✅ BAQL:PS:ALL_50_LCGS_(250000000≤MV≤1200000000)&(0.1≤DBTC≤10)

• All categories
• Top 50 GalaxyScore^tm coins
• Filters:
  • Market volume is between 250 millions and 1.2 billion
  • 24h % change in BTC between 0.1% and 10%

✅ BAQL:PS:ALL_10_LCAR_(750M≤MC)

✅ BAQL:PS:ALL_10_LCAR_(750M<=MC)

✅ BAQL:PS:ALL_10_LCAR_(750000000<=MC)

• All categories
• Top 10 AltRank^tm coins
• Filters:
  • Market cap greater than or equal to 750 millions

✅ BAQL:PS:ALL_50_BUS_(101≤LCAR)

• All categories
• Top 50 tokens sorted by bullish sentiment
• Filters:
  • AltRank^tm greater than 100

✅ BAQL:PS:ALL_7_BUS_(LCAR≤327)

• All categories
• Top 7 tokens sorted by bullish sentiment
• Filters:
  • AltRank^tm less than or equal to 327

✅ BAQL:PS:ALL_10_BUS_(50≤MCR≤100)

• All categories
• Top 10 tokens sorted by bullish sentiment
• Filters:
  • Market cap rank is between 50 and 100

❌ BAQL:PS:ALL_10_ZZ

INVALID: PS: Invalid sorting order keyword

❌ BAQL:PS:ALL_LCAR

INVALID: PS: Action malformed

❌ BAQL:PS:ALL_10000000_LCAR

INVALID: PS: Invalid n. of tokens

❌ BAQL:PS:ALL_50_LCGS_(250M≤ZZZZ≤1.2B)

INVALID: PS: Invalid filter keyword

❌ BAQL:PS:ALL_50_LCGS_(250M≤MV≤1.2B)_(0.1≤DBTC≤10)

INVALID: PS: Action malformed

❌ BAQL:PS:ALL_50_LCGS_(DBTC≥10)

INVALID: Invalid interval sign

❌ BAQL:PS:ALL_50_LCGS_(0.1<DBTC)

INVALID: Invalid interval sign

❌ BAQL:PS:ALL_50_LCGS_(10≤DBTC≤0.1)

INVALID: Interval inequality malformed

Signal Operator

predicate: signal_name
         | signal_list

signal_name: [a-zA-Z0-9]+

signal_list: list_start signal_name ((list_separator)+ signal_name)* list_end

Signal examples

Check the available TTP signals.

✅ BAQL:SIG:PETRO

• PETRO signal

✅ BAQL:SIG:[MCC]

• Market Cipher Conservative (long) signal

✅ BAQL:SIG:[PETRO LAMBO]

• Petro and Lambo signals

❌ BAQL:SIG:[MCC_MCB]

• INVALID: SIG: Invalid signal name format

❌ BAQL:SIG:[MCC LAMBO MCC]

• INVALID: SIG: Multiple occurrences of the same signal

❌ BAQL:SIG:[MCC

• INVALID: Predicate list malformed

❌ BAQL:SIG:[[MCC] [LAMBO]]

• INVALID: Nested predicate lists are not supported

❌ BAQL:SIG:__[MCC LAMBO]

• INVALID: Composite predicate malformed

Orchestrator Operator

predicate: orchestrator
         | orchestrator_list

orchestrator_list: list_start orchestrator ((list_separator)+ orchestrator)* list_end

orchestrator: orchestrator_provider operator_separator orchestration_command_list

orchestrator_provider: [a-zA-Z0-9]+

orchestration_command_list: orchestration_command (command_separator orchestration_command)?

orchestration_command: orchestration_action orchestration_separator orchestration_reaction

orchestration_separator: '_'

command_separator: '&'

orchestration_action: [a-zA-Z0-9]+

orchestration_reaction: [a-zA-Z0-9]+

Orchestrator examples

Check the available TTP orchestrator providers. See the possible commands using the list of actions and the list of reactions.

✅ BAQL:ORC:[ORIG:SELL_STPCL]

• Original Orchestrator
  • At SELL signal stops the bot and closes all its deals at market price

✅ BAQL:ORC:ORIG:SELL_STPCL

• Original Orchestrator
  • At SELL signal stops the bot and closes all its deals at market price

✅ BAQL:ORC:BTCS:IN_STT

• Bitcoin Season Index Orchestrator
  • At IN signal starts the bot

✅ BAQL:ORC:[ORIG:SELL_STP&BUY_STT]

✅ BAQL:ORC:ORIG:SELL_STP&BUY_STT

• Original Orchestrator
  • At SELL signal stops the bot and leaves deals opened untouched
  • At BUY signal starts the bot

✅ BAQL:ORC:[ORIG:SELL_STP&BUY_STT ST:SELL_STPCL&BUY_STT]

• Original Orchestrator
  • At SELL signal stops the bot and leaves opened deals untouched
  • At BUY signal starts the bot
• SuperTrend Orchestrator
  • At SELL signal stops the bot and closes all its deals at market price
  • At BUY signal starts the bot

✅ BAQL:ORC:[BTCS:OUT_STP&IN_STT ST:SELL_STPCL&BUY_STT]

• Bitcoin Season Index Orchestrator
  • At OUT signal stops the bot and leaves opened deals untouched
  • At IN signal starts the bot
• SuperTrend Orchestrator
  • At SELL signal stops the bot and closes all its deals at market price
  • At BUY signal starts the bot

❌ BAQL:ORC:]ORIG:BUY_STT]

• INVALID: Predicate list malformed

❌ BAQL:ORC:[ORIG:SELL_STP&&SELL_STPCL]

• INVALID: ORC: Action malformed

❌ BAQL:ORC:[ORIG:SELL_STP&SELL_STP]

• INVALID: ORC: Multiple occurrences of the same command action

❌ BAQL:ORC:[ORIG:SELL_STP ORIG:SELL_STPCL]

• INVALID: ORC: Multiple occurrences of the same orchestrator provider

❌ BAQL:ORC:ORIG:SELL_STP&BUY_STT ST:SELL_STPCL&BUY_STT

• INVALID: Unsupported action

Combined examples (more than one action together)

✅ BAQL:PS:ALL_3_LCAR SIG:SERPIL

✅ BAQL:PS:ALL_3_LCAR SIG:SERPIL!@

✅ BAQL:PS:ALL_3_LCAR SIG:SERPIL !@

✅ BAQL:PS:ALL_3_LCAR SIG:SERPIL !@ - further text

• PS:
  • All categories
  • Top 3 tokens sorted by AltRank^tm
• SIG:
  • Serpil

✅ BAQL:PS:ALL_10_LCGS SIG:LAMBO ORC:[ORIG:SELL_STP&BUY_STT ST:SELL_STPCL&BUY_STT]

• PS:
  • All categories
  • Top 10 tokens sorted by GalaxyScore^tm
• SIG:
  • Lambo
• Original Orchestrator
  • At SELL signal stops the bot and leaves opened deals untouched
  • At BUY signal starts the bot
• SuperTrend Orchestrator
  • At SELL signal stops the bot and closes all its deals at market price
  • At BUY signal starts the bot

✅ BAQL:PS:MEME&DEFI_50_LCGS_(2.17≤BUS) ORC:ORIG:BUY_STT

• PS:
  • Meme & DeFi categories
  • Top 50 tokens sorted by GalaxyScore^tm
  • Filters:
    • Bullish sentiment greater than or equal to 2.17
• Original Orchestrator
  • At BUY signal starts the bot

❌ BAQL:PS:ALL_3_LCAR_SIG:SERPIL

• INVALID: PS: Action malformed

Appendixes

Error codes

Code	Meaning
1001	String too long: Max 500 chars
1002	Missing starting BAQL tag
1003	Additional start tags
2001	No available actions
2002	Unsupported action
2003	Multiple occurences of the same action
2004	Nested predicate lists are not supported
2005	Predicate list malformed
2006	Composite predicate malformed
2007	Interval list malformed
2008	Invalid interval sign
2009	Interval inequality malformed
2010	Interval number malformed
2011	Multiple occurrences of the same interval criteria
3001	PS: Action malformed
3002	PS: Unsupported categories
3003	PS: Invalid n. of tokens [1,99999]
3004	PS: Invalid sorting criteria
3005	PS: Invalid sorting order keyword
3006	PS: Unsupported filter
4001	SIG: Invalid signal name format
4002	SIG: Multiple occurrences of the same signal
5001	ORC: Action malformed
5002	ORC: Multiple occurrences of the same orchestrator provider
5003	ORC: Multiple occurrences of the same command action

Available TTP signals

Signal Name	Description
SERPIL	Serpil signal
MCC	Market Cipher Conservative signal
MCR	Market Cipher Risky signal
MCB	Market Cipher Bear (short) signal
BIANCA	Bianca signal
LAMBO	Lambo signal
POISON	Parrot Poison signal
PETRO	Petro signal
FFALL	FFALL signal
PBOUNCE	PBOUNCE signal
METERL	METER long signal
METERS	METER short signal
SAVAGEL	Risk Savage long signal
SAVAGES	Risk Savage short signal

Available TTP’s Orchestrator Providers

Provider	Description	Supported Action
ORIG	Original TTP Orchestrator	BUY & SELL
ST	SuperTrend 1H BTC	BUY & SELL
STHA2H	SuperTrend HA 2H BTC	BUY & SELL
STDXY	SuperTrend 4H DXY	BUY & SELL
STT3	SuperTrend 1H TOTAL3	BUY & SELL
BULLOSC	Bull OSC 2H BTC	BUY & SELL
BEAROSC	Bear OSC 2H BTC	BUY & SELL
MC15M	MarketCipher 15M div BTC	BUY & SELL
MC1H	MarketCipher 1H div BTC	BUY & SELL
MC4H	MarketCipher 4H div BTC	BUY & SELL
MC1D	MarketCipher 1D div BTC	BUY & SELL
HIVE1H	Hive 1H bull:60C7MinDiv, bear:7C2MinDiv	BUY & SELL
HIVE4H	Hive 4H bull:60C7MinDiv, bear:7C2MinDiv	BUY & SELL
HIVE1D	Hive 1D bull:60C7MinDiv, bear:7C2MinDiv	BUY & SELL
RSIRALS	RSI ratio LS 1H	BUY & SELL
BTCS	Bitcoin Season:Altcoin Index between 0 and 24 a	IN & OUT
ALTS	Altcoin Season: Altcoin Index between 75 and 100 a	IN & OUT
EFEAR	Fear & Greed Index: between 0 and 24 b	IN & OUT
FEAR	Fear & Greed Index: between 25 and 49 b	IN & OUT
GREED	Fear & Greed Index: between 50 and 74 b	IN & OUT
EGREED	Fear & Greed Index: between 75 and 100 b	IN & OUT
WE	SELL on Sat 0Hrs, BUY on Mon 0hrs UTC	BUY & SELL
TEST	Fast shooting ORC for testing purposes	BUY & SELL

Available Orchestration Actions

The following are all the actions supported by the bot assistant. See the table above to see which actions are supported by a given orchestrator provider.

Action	Description
SELL	Signal when the market is rather overbought
BUY	Signal when the market is rather oversold
IN	Signal when the reference value enters a range
OUT	Signal when the reference value exits a range

Available Orchestration Reactions

Reaction	Description
STP	Stop the bot
STPCL	Stop the bot and close bot deals at market price
CL	Close bot deals at market price
STPCA	Stop the bot and cancel all bot deals
CA	Cancel all bot deals
STT	Start the bot
STTDL	Start the bot and start new deal (single-pair bot)

Previous versions

• 1.2.0 Reference
• 1.1.1 Reference
• 1.0.0 Reference

Notes

• ^{_{1. LCGS, LCAR, SV, BUS, BES metrics and categories are provided by LunarCrush Inc. ⮐}}

• ^{_{2. DUSD, DBTC, HUSD, WUSD, CGR, MC, MCR, MV metrics are provided by CoinGecko ⮐}}

• ^{_{GalaxyScore™️ and AltRank™️ are registered trademarks of LunarCrush Inc.}}

• ^{_{a. BTCS and ALTS orchestrators are provided by Altcoin Index ⮐}}

• ^{_{b. EFEAR, FEAR, GREED and EGREED orchestrators are provided by Crypto Fear and Greed Index ⮐}}