Hello all dCity players! Many of you are already aware of and actively using CityHelper to manage your cities, but many others are not. After 5 months, I'm finally writing an official introduction post and tutorial.

What is CityHelper?

CityHelper is a Discord bot with loads of functions for helping you manage your city. The intent is that you can explore every aspect of the game without ever leaving the community on Discord, where this game started.

Many functions are actually much more convenient from Discord, such as live rankings and bulk transfers, sales, and purchases. More on those later.
Disclaimer, I am not @gerber. If you need help with CityHelper, mention or DM Mike C#0408 on discord.

How Do I Use It?

Head on over to the official dCity Discord and jump into the #cityhelper channel. You will also need Hive Keychain installed and set up in your default browser.

A few functions are available right away, but for full functionality you'll have to link your Discord and Hive accounts with the !register command.

Registration

This process lets the bot know which Hive account to associate with your Discord account. Simply type !register hive-username using your actual Hive username, e.g. !register gerber.
This command generates a Keychain link for a transfer of 0.001 Hive to @cityhelper to verify that you do in fact have the keys to the account you're attempting to register. After a few seconds, the bot will mention you and the process is complete.

You can break this link with the !unregister command.

Getting Help

Before we go any further, you should know how to use the bot to get more information about a command.
First, use the !help command to get a list of all possible command with a short description of each.

To get more information about a specific command, e.g. !city, simply type !help city.

The first part might look a bit confusing, but you can ignore it for now. It's just outlining the structure of the command parameters.
The most important thing to look at is the examples. Here we can see that typing !city with no parameters will display your own city (if you're registered), and typing !city gerber will show @gerber's city.
The cooldown is an anti-spam measure and can also mostly be ignored. Here it's just saying that each user must wait at least 2 seconds before using this command again.

You're All Set!

At this point you're ready to use the bot. One more tip is to use the !dm command to have the bot start a private conversation with you. This keeps the main channel clean and lets you keep all your secrets to yourself.
I'll make a post with detailed information about each command later and link it here when it's ready.

Bulk Transfers, Sales, and Purchases

One of the conveniences of CityHelper is that you can do very fast bulk operations with just a bit of typing.

Card Names

A quick note about card names. Due to the nature of Discord bot commands, parameters cannot contain spaces. So typing !sell 5 basic home 300 sim will result in an error. In this case, "home" is seen as the 3rd parameter, which is supposed to be the price.

To get around this, I have set up nicknames for most cards, e.g. basic, luxury, military, etc.
Alternatively, you can replace the spaces with -, e.g. basic-home.
Wrapping the card name in quotes also works, e.g. "basic home".

Currently I don't have nicknames for tech cards, but I'll try to work on that soon. For now you can use - or quotes.
Another thing to note is that nothing is case sensitive.

Transfers

Use the !send command to transfer cards from your registered account to an alt account. BE CAREFUL! You could accidentally send your whole city to the wrong account if you make a typo here. The bot will check that the Hive username of the receiver is valid, but that doesn't completely prevent mistakes. Be sure to check the transaction on the webpage before clicking "Confirm" on Keychain.

example: "!send gerber" (default=all cards)
example: "!send gerber homeless" (send all homeless)
example: "!send gerber homeless 400" (send 400 homeless)

From the help text we can see that the parameters are a bit weird on this one. This is because parameters with default values must come after required parameters. (I might rewrite this to make it more logical, but this is it for now.)
You can use the !return command to return cards from an alt account to your main. There is no risk here, since you need the keys for the alt account.

Sales

Selling cards in bulk is very simple with CityHelper. First, there are a few helpful commands to determine a good price.
!average will show the average sale price of a card in SIM.
!averages will show the averages of all cards.
!history will show previous sales.
!market will show current sales.
Once you know your price, simply type the command and click the link, e.g. !sell 5 basic 300 sim. The webpage will show you what transaction you're about to confirm just in case you want to double check it.
There are a couple more commands used to manage sales:
!cancel will cancel your current sales.
!change will edit your current sales.

Purchases

It is also very easy to buy from the market with CityHelper.
Use the previously mentioned !average(s), !history, and finally !market to decide on a price, then use the !buy command.

For example, if you want to buy 50 basic homes and you decide that 1.5 SWAP.HIVE is a good price, you can type !buy 50 basic 1.5 swap.hive. Your order will include the 31 cards for 1.49 SWAP.HIVE each and 19 for 1.5 each.
The code will automatically limit your purchase based on the count you specify, the availability on the market, and your Hive Engine balance.
e.g. if you type !buy 1000 basic 1.49 swap.hive, only the 31 available on the market will be added to the order. If you only had 3.0 SWAP.HIVE in your wallet, the order would only include 2 cards.
Using !market and !buy together like this is a quick way to buy lots of cards. It hurts to watch people buying one by one in the dCity market stream.

Bids

Bids are a brand new feature of CityHelper (as of 7/19/2020). I'll write up a more detailed post when they're fully ready, but you can still use them as they are now.
Use the !deposit command to send tokens to @cityhelperbid. Only SIM and SWAP.HIVE are currently supported.
Use !balances to see how much SIM and SWAP.HIVE you currently have available for the bid bot to use.
Use !withdraw to get your tokens back from the bot.

Use the !bid command to place a bid on a card, e.g. !bid 5 basic 250 sim.
If any basic homes become available for 250 SIM or cheaper, the bot will buy the cards and send them to you.
Bids are filled by price (highest first) and creation time (earliest first).
You can only have 1 bid per card per symbol (SIM & SWAP.HIVE). Using the !bid command when you already have an existing bid will just update your old bid.
Use !bids to see all existing bids on a card, e.g. !bids basic.
Use !mybids to see all of your existing bids.

Have Fun!

I hope you enjoy using CityHelper. There are a lot more commands that weren't covered here, so go check them out!
As mentioned before, DM or mention Mike C#0408 on Discord if you have any questions or feedback related to the bot.