User commands for interacting with the bot for purposes of configuring the bot, adding credits, and messaging support.
Follow these steps to get started quickly
- Using your Nostr Client, send a Direct Message to Jessica Botzzap with NPUB npub1jessxt285u469vp2e64ddv8pjzu5ku0v95zel9h43gq4g5hcch9syxlv3r
- Define CONDITIONS for amounts to be zapped based on a phrase found in the content of a user reply, or a message to be sent
- Set the message to be included in zaps via ZAPMESSAGE
- Specify the EVENT to be monitored
- Add CREDITS to your bot account
- Finally, ENABLE the bot. This step performs some validation and will report any discrepancies
Periodically, you can check your STATUS. if the bot runs out of funds, it will send you a direct message information you.
The HELP command provides a summary of commands available
Example command:
HELP
Example response:
HELP
FEES
RELAYS LIST
RELAYS ADD <relay> [--canRead] [--canWrite]
RELAYS DELETE <index>
RELAYS CLEAR
CONDITIONS LIST
CONDITIONS ADD [--amount <zap amount if matched>] [--randomWinnerLimit <number of random winners of this amount for the event>] [--requiredLength <length required to match>] [--requiredPhrase <phrase required to match>] [--requiredRegex <regular expression to match>] [--replyMessage <message to reply with if matched>]
CONDITIONS UP <index>
CONDITIONS DELETE <index>
CONDITIONS CLEAR
EXCLUDES LIST
EXCLUDES ADD <exclude phrase or npub>
EXCLUDES DELETE <index>
EXCLUDES CLEAR
PROFILE [--name <name>] [--picture <url for profile picture>] [--banner <url for profile banner>] [--description <description of account>] [--nip05 <nip05 identity>] [--lud16 <lightning address>]
ZAPMESSAGE <message to send with zap>
EVENT <event identifier>
EVENTBUDGET <max to pay in total per event>
EVENTAUTOCHANGE <phrase>
BALANCE
CREDITS ADD <amount>
ENABLE
DISABLE
REPORTS
STATS
STATUS
SUPPORT <message to send to support>
The FEES command lists the current fee rates for the service
The RELAYS command requires additional arguments to specify option and parameters
These relays are used for both retrieval of responses to an event, as well as inclusion in the zap request sent to LNURL Providers that support Nostr.
Reports the relays currently configured for the bot for you. By default, this will initialize with a set of relays associated with your pubkey.
Example command:
RELAYS LIST
Example response:
Relays:
1) wss://nos.lol
2) wss://relay.nostr.bg
3) wss://relay.damus.io
4) wss://nostr.wine
5) wss://eden.nostr.land
The number listed in output may be used as the index to delete a relay as described below.
Use this command to add a relay to the list of those the bot should use.
Required arguments:
- relay url
Optional arguments:
- --canRead
- --canWrite
Example command:
RELAYS ADD wss://e.nos.lol
Example response:
Relays:
1) wss://nos.lol [rw]
2) wss://relay.nostr.bg [rw]
3) wss://relay.damus.io [rw]
4) wss://nostr.wine [rw]
5) wss://eden.nostr.land [rw]
6) wss://e.nos.lol [rw]
Example command for read only relay:
RELAYS ADD wss://nostr.wine --canRead
Example response:
Relays:
1) wss://nos.lol [rw]
2) wss://relay.nostr.bg [rw]
3) wss://relay.damus.io [rw]
4) wss://nostr.wine [r]
5) wss://eden.nostr.land [rw]
6) wss://e.nos.lol [rw]
Use this command to remove a relay from the list of those the bot should use, specifying the index of the relay as shown in the relay list.
Required arguments:
- index of relay to delete
Example command:
RELAYS DELETE 2
Example response:
Relays:
1) wss://nos.lol [rw]
2) wss://relay.damus.io [rw]
3) wss://nostr.wine [r]
4) wss://eden.nostr.land [rw]
5) wss://e.nos.lol [rw]
Use this command to remove all relays from the relay list. You will need to add relays again for the bot to operate.
Example command:
RELAYS CLEAR
Example response:
Relays:
Relay list cleared.
The CONDITIONS command requires additional arguments to specify option and parameters
These conditions are rulesets compared to a response someone makes to the referenced event. If conditions match, then the publisher of the response will be zapped sats of the amount specified. Conditions are compared in the order specified so more restrictive, or higher rewarding conditions should be specified first.
Reports the conditions currently configured for the bot for you. By default, this will initialize with a required length of 20, but no phrase required and a zap amount of 1.
Example command:
CONDITIONS LIST
Example response:
Conditions:
1) zap 20 sats if length >= 20 and contains "#InkblotArt"
2) zap 10 sats if length >= 10
The number listed in output may be used as the index to delete a condition as described below.
Use this command to add a condition to the list of those the bot should use. You can define multiple conditions and use the CONDITIONS UP operation described below to control the order condition definitions are checked.
Required arguments:
- --amount <zapAmount>
Optional arguments:
- --randomWinnerLimit <number of random winners of the amount for the event>
- --requiredPhrase <phrase required>
- --requiredLength <length required>
- --requiredRegex <regular expression>
- --replyMessage <message to create a nostr reply with>
Example command:
CONDITIONS ADD --amount 200 --requiredPhrase #InkblotArt --requiredLength 30
Example response:
Conditions:
1) zap 20 sats if length >= 20 and contains "#InkblotArt"
2) zap 10 sats if length >= 10
3) zap 200 sats if length >= 30 and contains "#InkblotArt"
Example command that establishes a condition for reply message
CONDITIONS ADD --amount 0 --requiredPhrase crab --replyMessage https://cdn.pixabay.com/photo/2014/12/21/23/58/lobster-576487_960_720.png
Example command using regular expression to match #InkblotArt and crab, in any order
CONDITIONS ADD --amount 200 --requriedRegex (crab.*#Inkblotart|#InkblotArt.*crab) --replyMessage https://cdn.pixabay.com/photo/2014/12/21/23/58/lobster-576487_960_720.png
Example command that adds a random winner limit. While the event is being monitored up to 3 randomly selected people will be awarded 210 if their reply to the event contains the phrase 'Not your keys not your coin'. Winners are selected randomly with a 1% chance of being chosen. Once the limit has been reached no more winners for the condition are selected.
CONDITIONS ADD --amount 210 --randomWinnerLimit 3 --requiredPhrase Not your keys not your coin
The following commands results in a series of conditions that will zap 210 sats to up to 2 randomly chosen respondants whose reply contains "#InkblotArt", while others get 5 sats
CONDITIONS ADD --amount 210 --randomWinnerLimit 2 --requiredPhrase #InkblotArt --requiredLength 20
CONDITIONS ADD --amount 5 --requiredPhrase #InkblotArt --requiredLength 20
CONDITIONS ADD --amount 1 --requiredPhrase #InkblotArt --requiredLength 1
Use this command to reorder conditions in the list, moving one at a time to a newer index. This is helpful if you have defined conditions, but want to change the processing order
Required arguments:
- index of condition to promote
If the result of CONDITIONS LIST is as follows:
Conditions:
1) zap 20 sats if length >= 20 and contains "#InkblotArt"
2) zap 10 sats if length >= 10
3) zap 200 sats if length >= 30 and contains "#InkblotArt"
Example command:
CONDITIONS UP 3
Example response:
Conditions:
1) zap 20 sats if length >= 20 and contains "#InkblotArt"
2) zap 200 sats if length >= 30 and contains "#InkblotArt"
3) zap 10 sats if length >= 10
Use this command to remove a condition from the list of those the bot should use, specifying the index of the condition as shown in the conditions list.
Required arguments:
- index of condition to delete
Example command:
CONDITIONS DELETE 2
Example response:
Conditions:
1) zap 20 sats if length >= 20 and contains "#InkblotArt"
2) zap 10 sats if length >= 10
Use this command to remove all conditions from the condition list. You will need to add conditions again for the bot to operate.
Example command:
Conditions CLEAR
Example response:
Conditions:
Condition list cleared.
The EXCLUDES command requires additional arguments to specify option and parameters
These excludes are a list of phrases in user replies or npubs that should be ignored when processing an event. Think of it as a simple deny-list to blot auto responders or people otherwise abusing the bot.
Reports the exclude values currently configured for the bot for you.
Example command:
EXCLUDES LIST
Example response:
Excludes:
1) LayerZero
2) $ZRO
3) airdrop
4) prism
5) $boost
6) SHIB
7) BNB
8) DOGE
9) USDC
10) $PEPE
The number listed in output may be used as the index to delete an exclude as described below.
Use this command to add a phrase to the list of those the bot should exclude from responses or zap.
Required arguments:
- exclusion phrase
Example command:
EXCLUDES ADD Ukraine
Example response:
Excludes:
1) LayerZero
2) $ZRO
3) airdrop
4) prism
5) $boost
6) SHIB
7) BNB
8) DOGE
9) USDC
10) $PEPE
11) Ukraine
Example command adding an npub to ignore:
EXCLUDES ADD npub1pzv524j3a0d25zd6cv7a8qd2c74zsqfwmuc3ul2wnq5q96c6cp5qzvatj0
Example response:
Excludes:
1) LayerZero
2) $ZRO
3) airdrop
4) prism
5) $boost
6) SHIB
7) BNB
8) DOGE
9) USDC
10) $PEPE
11) Ukraine
12) npub1pzv524j3a0d25zd6cv7a8qd2c74zsqfwmuc3ul2wnq5q96c6cp5qzvatj0
Use this command to remove a phrase or npub from the list of those the bot excludes from processing, specifying the index of the phrase as shown in the exclude list.
Required arguments:
- index of exclude phrase or npub to delete
Example command:
EXCLUDES DELETE 2
Example response:
Excludes:
1) LayerZero
2) airdrop
3) prism
4) $boost
5) SHIB
6) BNB
7) DOGE
8) USDC
9) $PEPE
10) Ukraine
11) npub1pzv524j3a0d25zd6cv7a8qd2c74zsqfwmuc3ul2wnq5q96c6cp5qzvatj0
Use this command to remove all exclusion phrases from the excludes list.
Example command:
EXCLUDES CLEAR
Example response:
Excludes:
Excludes list cleared.
The PROFILE command allows for setting custom profile information for the bot that is zapping based on the conditions established. Each account is assigned a unique bot identity and can be branded accordingly. Likewise the npub of the bot can be used when registering for relay write access, archives, nip05 and other services.
Optional arguments:
- --name <name>
- --picture <url for profile picture>
- --banner <url for profile banner>
- --description <description of account>
- --lud16 <lightning address>
- --nip05 <nostr address>
Example command:
PROFILE --name "Crabby Botzzapp"
Profile information
name: Crabby Botzzapp
description: This bot zaps participants of #InkblotArt by Rex Damascus
profile picture: https://nostrnodeyez.s3.amazonaws.com/inkblotart-crabby-botpfpt2.png
banner picture: none specified
lud16/lightning address: [email protected]
nip05/nostr address: [email protected]
When a nostr zap is sent, a message or comment can be included with the zap. Different LNURL Providers can have their own constraints on whether messages are accepted, and of what length. To avoid errors, its recommended to keep messages brief. If your message contains a URL, some providers will turn that into a hyperlink, but may be limited to the first URL that appears within the message.
Example command:
ZAPMESSAGE Thanks for sharing your interpretation of today's #InkblotArt!
Example response:
The zap message has been set to: Thanks for sharing your interpretation of today's #InkblotArt!
The EVENT command requires specifying an event identifier to be monitored. Only one event can be monitored at a time per account. The event identifier may be provided in bech32 or hexadecimal format.
Example command when providing bech32 format:
EVENT nevent1qqsgq94vx9kq40zkyrr4e5lyw4knsqru779qexywkdglpsl8uwnrhhcpzemhxue69uhhyetvv9ujumn0wd68ytnzv9hxg9fx3dj
Example response:
Now monitoring event 8016ac..a63bdf
Example command when providing hex format:
EVENT 8016ac316c0abc5620c75cd3e4756d38007cf78a0c988eb351f0c3e7e3a63bdf
Example response:
Now monitoring event 8016ac..a63bdf
Example command to set no event to be monitored:
EVENT 0
Example response:
No longer monitoring an event
The EVENTBUDGET command can help constrain overall payouts. This is a convenient way
to limit the total amount of credits spent for a defined event. The default value of 0 indicates that there is no limit.
Example command:
EVENTBUDGET 5000
Example response:
The budget for the event has been set to 5000. 2121 credits have been used to date for the event, leaving 2879 remaining. Your account balance is 51223.
If the budget has already been exceeded:
The budget for the event has been set to 5000. 6102 credits have been used to date for the event. Zaps and replies for this event will not be performed. Your account balance is 51223.
Example command:
EVENTBUDGET 0
Example response:
The budget for the event has been set to unlimited. 2121 credits have been used to date for the event. Your account balance is 51223.
Set a phrase for which the bot should change which event it is monitoring for you whenever you post a new note containing that phrase.
Example Command:
EVENTAUTOCHANGE #Nodeyez
Example Response:
Whenever you create a new post with the phrase '#Nodeyez', the bot will change to monitoring that post
Example Command that turns off this feature
EVENTAUTOCHANGE
Example Response
No longer automatically changing event to monitor based on your posts
The BALANCE command reports the balance of credits
Example command:
BALANCE
Example response:
Your balance is 51223. To add credits, specify the full command. e.g. CREDITS ADD 21000
The CREDITS command allows for adding credits to the account for the bot to use for expenditures. Credits are non-refundable and cover the cost of sending zaps and the routing fees required.
Required arguments:
- amount desired to be credited
Example command:
CREDITS ADD 20000
Example response:
Please fulfill the following invoice to credit the account
lnbc200u1pjjg58cpp5g4uqmvplrf4k3unl6u24k2pr3eurzrxcl2zp7am24xtr6af3j68qhp5u9nxg2espa7m9wmhgm53um7f93z22ham5zgaymqccwhm2nuc3mhscqzzsxqyz5vqsp5rx73x3glr8jgzl5dewfthznggawnqjv6mnrklxsl5wxfyvkl6rjq9qyyssq69nucsuu6he7skk8a0354ddlp7hf348vadtnry9cyysh6qv60ye8r4kc7x0e7krf9qaexd9vxahqewc3mea26sc4kh7wmdw3lrsnfmsqdhw3pd
Your nostr client may turn the lightning invoice into a QR code or button for which to pay to complete the process.
When the bot recognizes the invoice as paid, a follow up message will be sent
Invoice paid. 20000 credits have been applied to your account
The REPORTS command will return a URL for accessing reports for each event that was monitored, and the zaps made and routing fees.
Example command:
REPORTS
Example response:
Reports for events monitored, amount zapped and routing fees available at https://nostrnodeyez.s3.amazonaws.com/boostzapper/21def6feee4f527ab61968c02bb2781e/index.html
The STATS command reports summary stats of the number of zaps, replies and costs since last ledger rotation. A ledger rotation currently happens every 500 ledger entries.
Example command:
STATS
Example response:
Stats since the last ledger rotation on 2023-10-28T20:30:09
CREDITS APPLIED: 10000 (0.000 total sats)
ZAPS: 122 (-5221.000 total sats)
REPLY MESSAGES: 212 (10.600 total sats)
ROUTING FEES: 1 (-31.205 total sats)
SERVICE FEES: 75 (-74.050 total sats)
EVENTS MONITORED: 1
The STATUS command provides a simplified report of the configuration
Example command:
STATUS
Example response:
The bot is configured with 5 relays, 2 conditions, and monitoring event 8016ac..a63bdf.
Responses to the event matching conditions will be zapped up to 20 sats with the following message: Thanks for sharing your interpretation of today's #InkblotArt!
Credits applied: 200000
All time zaps sent: 78100
Routing: 236
Service: 6000
Credits remaining: 115664
The ENABLE command enables the bot to process messages and send zaps if the configuration is valid. If there is a configuration requirement not met, the response will indicate as such
Example command:
ENABLE
Example response:
Bot enabled!
Example response for a validation error
Unable to enable the bot. The eventId must be set. Use EVENT <event identifier>
The DISABLE command disables the bot so that it will no longer continue processing events until started again.
Example command:
DISABLE
Example response:
Bot disabled. Events will not be processed until re-enabled
Under normal circumstances, the bot account itself is not monitored. Direct Encrypted messages with the bot allow for users to configure the bot and review status for their events without polluting the public feeds of nostr.
For convenience messages may be forwarded to the operator of the bot to draw attention to any issues that may be occurring or if you encounter a bug with the bot.
Example command:
SUPPORT I need additional rule types be added to the bot
Example response:
Your message has been forwarded through nostr relays. The operator may reach out to you directly or through other channels. If you need to temporarily stop the bot, you can use the DISABLE command or set EVENT 0