Beginners Guide

From bitcoin-otc wiki
Revision as of 09:36, 26 January 2013 by Fbastage (Talk | contribs) (Initial creation)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This document is a simple beginner's guide to using Gribble and #bitcoin-otc on


Background on IRC and Freenode

#bitcoin-otc is an Intenet Relay Chat (IRC) chatroom that exists on the Freenode network of IRC. This collection of different systems and protocols might at first make certain aspects use of #bitcoin-otc for Over The Counter (OTC; informal, not going through a centralized regulatory body or market authority). This tutorial seeks to define various terms, commands, and usage patterns to get you comfortable with using the OTC to trade bitcoins and other related goods or services.

optional information:

First step: getting connected

Browser-based IRC client

If you are unfamiliar with IRC and do not have a specialized, stand-alone IRC client software, you can connect via any web browser via Freenode's webchat applet at which will bring you directly into the #bitcoin-otc chatroom.

Stand-alone IRC client

If you have a standalone IRC client, change the settings to use any of the Freenode network servers and initiate a connection. Once connected, join #bitcoin-otc by typing the IRC command /join #bitcoin-otc or by any other method specific to your client for joining a channel.

Tor-based connections

Freenode does support TOR-based connections, but only through SASL authentication. See for details.

IRC is not Bitcoin specific

It is worth noting that IRC and Freenode exist in a more general context than just for chatting about trading bitcoins. #bitcoin-otc is simply one of many channels that exist on Freenode and that it is only by following Freenode's terms of service that we can continue to use their network for our trade. The most significant restriction in the terms of service is to not engage in activities that are illegal. Please see

Useful IRC commands

These commands are part of the IRC protocol and supported by the IRC server.

Note that most of the information you provide in your configuration will be publicly viewable. If you are concerned about your privacy, do not use your real name or identifying information; there is no requirement to provide your real information. The IP or host you are connecting from will also be shown unless you request a "cloak" from Freenode admins in conjunction with having registered your nickname through nickname services (NickServ).

/nick <new name>

To change your IRC nickname, type /nick <new name>. Nicknames limited to only of characters a-z, A-Z, 0-9, underscore, and dash, must begin with a letter and limited to 16 characters in length. Note that nicknames can be registered with IRC's nickname services (NickServ) and that if you chose a nickname already registered, you will be asked to IDENTIFY within 30 seconds or your nickname will be forcibly changed.

/nick Charlie333
* Your nick is now Charlie333

/join <#channel-name>

You may join any number of channels simultaneously. Typing /join <#channel-name> will connect you to the new channel while leaving you connected to your existing channels. Note that channels can be configured to require an invite or password. Also, channels can be created by anyone - joining a chanel that does not exist will create that channel. Channels can also be registered with channel services (ChanServ) so it may be possible to reserve a channel through these services.

/join #bitcoin-otc

/part <#channel-name>

You may leave a channel by typing /part <#channel-name>. Most IRC clients that use windows also allow you to leave a channel by killing the window for that channel.

/part #bitcoin-otc

/query <nickname> [<message>] or /msg <nickname> <message>

To initiate a private chat with a single person, type /query <nickname>. The query command opens a private window for the private chat, while msg sends the message but doesn't open a new window.

/query gribble ;;ticker

/me <action text>

If you wish to write your text as an action, type /me <action text>. I.e. /me goes to bed will cause your text to display similar to "nickname goes to bed".

/me laughs at this
* fbastage laughs at this

/whois <nickname>

View the connection information about a person.

/whois fbastage
fbastage is ~fbastage@unaffiliated/fbastage * f
fbastage on #bitcoin-otc 
fbastage using Brisbane, AU
fbastage has been idle 26mins 36secs, signed on Sat Jan 26 07:54:45
fbastage is logged in as fbastage
fbastage End of /WHOIS list.

Who is Gribble? OTC's bot

Gribble is a bot (software agent) that uses #bitcoin-otc (and several other related channels) to facilitate OTC trade or provide information about bitcoin. These are not part of the IRC protocol or server but provided via this bot through communications on the IRC server via private messages or text within the #bitcoin-otc channel.

Gribble is run and maintained by nanotube. Nanotube also runs and interactions with gribble affect data displayed on .

Gribble is an open-source python-based supybot with plugins to support bitcoin-related queries. You can get the code for supybot at or get the code for gribble (which includes supybot) at .

Bitcoin-specific functions that gribble provides include managing authentication (via PGP keys or Bitcoin address signing), maintaining a Web Of Trust (WOT) score and feedback messages between users, keeping an orderbook of proposed trades from users, querying bitcoin market prices, and querying bitcoin and blockchain statistics.

Gribble is configured to listen for commands beginning with two semi-colons (';;') or an exclamation point ('!') when issued in the channel. When communicating with gribble in private message you may omit these characters if you wish. Because supybot (and gribble) are open-source, it is possible for others to run supybots that exist in the same channel; because of this, it is recommended to use the ;; characters before commands as it is frequent for OTHER supybots to be listening to ! character commands and can lead to many bots responding to your intended command and clutter the channel.

If you have not authenticated with gribble, gribble will reply to your commands via private message; if you have authenticated gribble will reply in channel. It is a common point of confusion for newer users to issue a command and not see a reply and not notice gribble replied in a separate private window.

Gribble commands for OTC

Here are some basic OTC commands and aliases you will find useful immediately. For a more comprehensive list of gribble commands, please see Commands.

Note that elements in brackets ('[]') are optional arguments that modify this command. The '|' character represents "OR" - one of these options can be used at a time.

Bitcoin pricing or calculations

;;ticker [--bid|--ask|--last|--high|--low|--avg] [--currency XXX]

Ticker queries bitcoin pricing based on's history. By default it returns values in USD. Without any arguments ;;ticker returns a collection of information

<gribble> BTCUSD ticker | Best bid: 15.68000, Best ask: 15.68001, Bid-ask spread: 0.00001, Last trade: 15.68001, 24 hour volume: 26503.89738865, 24 hour low: 15.48512, 24 hour high: 15.89000, 24 hour vwap: 15.69555

If you wish to just get a single value, use one of the options to specify which piece of information, such as the current bid price, ask price, last price, 24 hour high, 24 hour low, or 24 hour average.

;;ticker --ask
<gribble> 15.68001

If you wish to query the price in a different currency, use the currency option. Valid currencies are any currency listed on and currently include USD, EUR, JPY, CAD, GBP, CHF, RUB, AUD, SEK, DKK, HKD, PNL, SGD, THB, NZD, and NOK.

;;ticker --bid --currency GBP
<gribble> 9.82000

;;calc <expression>

Calculate a mathematic expression. Note that the syntax used for exponentiation is '**', not '^'. The ticker command can be embedded into this command by surrounding it in brackets ('[]').

;;calc 1 + 1
<gribble> 2
;;calc 3 ** 2
<gribble> 9
("How many bitcoins will $100 buy with 5% mark-up over the last mtgox price?")
;;calc 100 / [ticker --last] / 1.05
<gribble> 6.07773034211 
("How many yen can I get for 10 bitcoins at last price in yen if I sell at 1% discount?")
;;calc 10 * [ticker --last --currency JPY] * 0.99
<gribble> 14230.9629

Web of Trust ratings

It is worth noting that Web Of Trust (WOT) names do not have to be the same as someone's IRC nickname. WOT registration is also completely separate from NickServ (Nickname Services) nickname registration.

Note the brackets ('[]') in this section are not meant to indicate optional arguments, but are used by gribble to embed one command within another.

=;;getrating <nickame>

or  ;;getrating [ident <nickname>] Get a summary of a person's rating in the WOT and link to a webpage for the full feedback text for those ratings. If a person is using a different nickname on IRC than they use in the WOT, this command will either fail or could respond with someone else's ratings, so it is recommended to use ;;getrating [ident <nickname>]

;;getrating fbastage
<gribble> WARNING: Currently not authenticated. User fbastage, rated since Thu Jul  5 16:24:50 2012. Cumulative rating 32, from 33 total ratings. Received ratings: 31 positive, 2 negative. Sent ratings: 31 positive, 68 negative. Details:

;;rate <#> <nickname>

or  ;;rate <#> [ident <nickname>] Rate a user with a numeric rating (1 to 10 or -1 to -10; there is no 0 rating; see ;;unrate). This command will fail if you are not registered and authenticated or if the nickname you are rating is not registered. There are suggested guidelines to the rating you give:

;;rate fbastage 1 helluva guy
<@gribble> Rating entry successful. Your rating of 1 for user fbastage has been recorded.

;;rated <nickname>

Show which rating you had given <nickname>.

;;rated fbastage
<gribble> You rated user deego on Sat Sep 29 14:54:39 2012, giving him a rating of 1, and supplied these additional notes: helluva guy

;;unrate <nickname>

or  ;;unrate [ident <nickname>] Remove a rating you had given to <nickname>.

;;unrate fbastage

Registration, authentication, and validation

Note that you can find more information on GPG/PGP authentication on and more information on Bitcoin Address Authentication on

You only need to use one of the registration and authentication methods (there are 2 PGP methods and one Bitcoin Address method) but you should consider having both a PGP and a Bitcoin registration in case you lose one or the other.

;;ident [<nickname>]

Ask gribble if <nickname> (or your own username, if omitted) is authenticated with a WOT name. This is the same command that was embedded within brackets in the rating commands above.

;;ident FonziScheme
<gribble> Nick 'FonziScheme', with hostmask 'FonziScheme!~fbastage@unaffiliated/fbastage', is not identified.

;;gpg info <nickname> or  ;;gpg info [ident <nickname>]

Get the WOT registration information for a nickname. This will display their PGP fingerprint, bitcoin address, and a link to this information on the website.

;;gpg info fbastage
<gribble> User 'fbastage', with keyid 908C368A9C77770C, fingerprint FDEF465AEA108B4A95482795908C368A9C77770C, and bitcoin address 1Eycgq4c91MiYi1diyPFEva6Wi8sjLEu4o, registered on Tue Jul  3 16:00:32 2012. . Currently not authenticated.

;;eregister <wot name> <pgp long id> [<key server>]

Initiate registration of a WOT name using a PGP key. To complete this registration, you will need to DECRYPT a challenge string that gribble gives you via an url (COPY THE ENTIRE CONTENTS OF THIS PAGE; I suggest using ctrl-a to select all) and use this value with the ;;everify command. This command is preferred over the similar ;;register command because the register command requires you to post the results of your challenge on a website and tell gribble to find it via url.

For examples, visit GPG_authentication

;;everify <otp>

Verify your key by giving gribble the decrypted One Time Password (OTP) from a previous command (;;eregister or ;;eauth).

;;register <wot name> <pgp long id> [<key server>]

Initiate registration of a WOT name using a PGP key. To complete this registration, you will need to CLEAR SIGN a challenge string that gribble gives (COPY THE ENTIRE CHALLENGE STRING) post the results of your challenge on a website and tell gribble to find it via url using the ;;verify command.

;;verify <url>

Verify your key by giving gribble the url containing your clear signed text from a previous command (;;register or ;;auth).

;;bcregister <wot name> <btc address> or  ;;btcregister <wot name> <btc address>

Initiate registration of a WOT name using a Bitcoin address. To complete this registration, you will need to SIGN a One Time Password (OTP) that gribble gives you (COPY THE ENTIRE TEXT including the leading "freenode:#bitcoin-otc:" portion) and use this value with the ;;bcverify command. Bitcoin address signing is supported in the base client wallet ("Satoshi") and some other wallet software and some online wallets. The function to sign is usually found in the "Receive Coins" page. Be sure to use the same address to sign that you register with.

;;bcverify <signedmessage> or  ;;btcverify <signedmessage>

Verify your address by giving gribble the signed One Time Password (OTP) from a previous command (;;bcregister or ;;bcauth).

You need to re-authenticate with gribble each time you leave the channel or if gribble gets reset or leaves the channel.

;;eauth <wot name>

Authenticate with gribble. You will receive a challenge similar to the ;;eregister command. Reply with ;;everify.

;;auth <wot name>

Authenticate with gribble. You will receive a challenge similar to the ;;register command. Reply with ;;verify.

;;bcauth <wot name> or  ;;btcauth <wot name>

Authenticate with gribble. You will receive a challenge similar to the ;;bcregister command. Reply with ;;bcverify.

Using the orderbook

You may find it easier to view the orderbook online at but I believe to enter or delete orders you must use gribble commands.

Note: there is no automatic processing of orders in the orderbook. They are simply listings. If you wish to accept someone's offer, contact them and deal with them manually. You should delete any orders that you have already honored. Orders also expire on their own, though you can refresh them. You can not edit an order, but you can simply remove it and make a new one.

;;view [<orderid>|<nick>]

View an order by order id or view the orders created by <nick>. If you don't include an options gribble will show your orders.

 ;;view 1311
 <gribble> #1311 Sat Jan 26 06:10:58 2013 fbastage SELL 1 Silver Eagle (1 troy ounce 99.9% pure) @ 2.1087 btc (plus 0.286 btc shipping)

;;book <search term>

View orders in the orderbook that wish to trade that <search term>. Note that things in the order book can be listed by all sorts of different names (i.e. usd, goxusd, mtgoxusd) so you may need to try a few variants to find what you are looking for.

;;buy <amount> <thing> [at|@] <priceperunit> <units> [<notes>]

;;sell <amount> <thing> [at|@] <priceperunit> <units> [<notes>]

Create a new order to buy or sell something at a certain price. If the <thing> or <units> is more than one word you will need to enclose them in quotes.

 ;;sell 3 "bitcoin t-shirts" at 2 BTC I made them all by myselfs
 <gribble> Order id 139 created.

;;remove <orderid>

Remove an order by id number.

 ;;remove 139

;;refresh [<orderid>]

Refresh an order by id or all of your orders if no id is specified so that it does not expire.

 ;;refresh 139

Further reading

There is are many more commands supported by gribble and the IRC environment. For more info you might want to look at ____________________.