BAQL Version 1.2.0

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'

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 Score^tm	descending
LCAR	LunarCrush AltRank^tm	ascending
DUSD	24h % change (USD)	descending
DBTC	24h % change (BTC)	descending
HUSD	1h % Change (USD)	descending
SV	Social Volume	descending
BUS	Bullish Sentiment (values between 1 and 5)	descending
BES	Bearish Sentiment (values between 1 and 5)	descending
MC	Market cap	descending
MV	Market volume	descending

Supported categories:

Category	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

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_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:[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:]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

Available TTP’s Orchestrator Providers

Provider	Description
ORIG	Original TTP Orchestrator
ST	SuperTrend 1H BTC
STHA2H	SuperTrend HA 2H BTC
STDXY	SuperTrend 4H DXY
STT3	SuperTrend 1H TOTAL3
BULLOSC	Bull OSC 2H BTC
BEAROSC	Bear OSC 2H BTC
MC15M	MarketCipher 15M div BTC
MC1H	MarketCipher 1H div BTC
MC4H	MarketCipher 4H div BTC
MC1D	MarketCipher 1D div BTC
HIVE1H	Hive 1H bull:60C7MinDiv, bear:7C2MinDiv
HIVE4H	Hive 4H bull:60C7MinDiv, bear:7C2MinDiv
HIVE1D	Hive 1D bull:60C7MinDiv, bear:7C2MinDiv
RSIRALS	RSI ratio LS 1H
WE	SELL on Sat 0Hrs, BUY on Mon 0hrs UTC
TEST	Fast shooting ORC for testing purposes

Available Orchestration Actions

Action	Description
SELL	Signal when the market is rather overbought
BUY	Signal when the market is rather oversold

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

Notes

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