Beginners Guide

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

#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 of use of #bitcoin-otc for Over The Counter trading confusing. 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.

Getting connected

Browser-based IRC client

If you are unfamiliar with IRC and do not have specialized, stand-alone IRC client software, you can connect via any web browser via Freenode's webchat applet at http://webchat.freenode.net/?channels=#bitcoin-otc 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

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 http://freenode.net/policy.shtml#unlawful

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

/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

/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

/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

/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

/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

/whois <nickname>
View the connection information about a person.

/whois fbastage
fbastage is ~fbastage@unaffiliated/fbastage * f
fbastage on #bitcoin-otc
fbastage using roddenberry.freenode.net 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.

NickServ

IRC servers offer nickname services via a special "user" named NickServ. This allows you to register and protect a nickname. It is a best-practice to register and enforce your nickname to avoid squatters using your name.

It is recommended that you type any commands that require a password in the IRC status window, not in a channel window, in case you accidentally mistype the command and transmit the password as text.

/ns help

/ns helpor/nickserv helpor/msg nickserv help
You can get help from the NickServ system by typing this command.

/ns help

/ns register

/ns register <password> <email>or/nickserv register <password> <email>or/msg nickserv register <password> <email>
Register your current nickname. If you already have a registration, use the GROUP command instead to group a new name into your registration.

/nick jowels
/ns register fuUmc3*fj#$ jowels@bigface.com

/ns group

/ns groupor/nickserv groupor/msg nickserv group
Group your current nickname into your registration. '***You must have IDENTIFIED to your registered nickname prior to this command***'

/nick jowels
/ns group

/ns identify

/ns identify <password>or/ns identify <nickname> <password>or/nickserv identify <password>or/nickserv identify <nickname> <password>or/msg nickserv identify <password>or/msg nickserv identify <nickname> <password>
Identify yourself to nickserv (log in). If you are using your registered nickname, you can omit the nickname. If ENFORCE is set on, you must identify within 30 seconds or your nickname will be locked out. If this happens, use RELEASE to release the name.

/nick jowels
/ns identify fuUmc3*fj#$

/ns set enforce on

/ns set enforce onor/nickserv set enforce onor/msg nickserv set enforce on
Set ENFORCE on. This requires anyone using your nickname to IDENTIFY within 30 seconds and will keep people from using your nickname. '***You must have IDENTIFIED to your registered nickname prior to this command***'

/ns identify fuUmc3*fj#$
/ns set enforce on

/ns release

/ns release <nickname>or/ns release <nickname> <password>or/nickserv release <nickname>or/nickserv release <nickname> <password>or/msg nickserv release <nickname>or/msg nickserv release <nickname> <password>
Release your nickname if it is in use by someone else or locked out. If you are already IDENTIFIED, you can omit the password.

/ns release jowels fuUmc3*fj#$

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 http://bitcoin-otc.com/ and interactions with gribble affect data displayed on bitcoin-otc.com .

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 because OTHER supybots frequently listen for the '!' character and will reply, cluttering 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 Gribble 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

;;ticker [--bid|--ask|--last|--high|--low|--avg] [--currency XXX]
Ticker queries bitcoin pricing based on mtgox.com's history. By default it returns values in USD.
Without any arguments ;;ticker returns a collection of information

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 mtgox.com 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

;;calc <expression>
Calculate a mathematic expression. The ticker command (or other commands) can be embedded into this command by surrounding it in brackets ('[]').

;;calc 1 + 1
<gribble> 2

Note that the syntax used for exponentiation is '**', not '^'.

;;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?")

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.

You should ephasize trust, not "ratings". Ratings can be artificially inflated or deflated via creating a number of shill accounts. You should use ;;gettrust to measure the trust between you and someone or between two known parties. This better utilizes the web of trust and relies on the emergence of trusted networks within the overall web of trust.

;;gettrust

;;gettrust <nickame>or;;gettrust <nickame> <nickname2>
Get a measure of trust between you and someone else, or between two other people. If you don't have many ratings, it can be more effective to use ;;gettrust between someone you know and trust and another third party.

Note that trust is directional, so 'gettrust nick1 nick2' will produce different results from 'gettrust nick2 nick1'.

;;rate

;;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: OTC_Rating_System#Rating_guidelines

Registration, authentication, and validation

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

;;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.

;;gpg info

;;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 bitcoin-otc.com website.

Bitcoin Address authentication

;;bcregister

;;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

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

;;bcauth

;;bcauth <wot name> or ;;btcauth <wot name>
Authenticate with gribble. You will receive a challenge similar to the ;;bcregister command. Reply with ;;bcverify.

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

;;changeaddress

;;changeaddress <bitcoin address>
Change the bitcoin address associated with your WOT name. ***YOU MUST BE AUTHENTICATED FIRST TO RUN THIS COMMAND*** Reply with ;;bcverify

GPG using decryption of challenge string

Of the two GPG-based methods, this one is easier for the casual user.

Note: your key must be uploaded to keyservers in order for gribble to be able to retrieve it. An easy way to do it is to run the following command:

gpg --send-keys --keyserver pgp.mit.edu YOURKEYID

;;eregister

;;eregister <wot name> <pgp long id>
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.

;;everify

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

;;eauth

;;eauth <wot name>
Authenticate with gribble. You will receive a challenge similar to the ;;eregister command. Reply with ;;everify.

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

;;echangekey

;;echangekey <pgp long id>
Change the gpg key associated with your WOT name. ***YOU MUST BE AUTHENTICATED FIRST TO RUN THIS COMMAND*** Reply with ;;everify

GPG using clear sign and posting to an url

Note: your key must be uploaded to keyservers in order for gribble to be able to retrieve it. An easy way to do it is to run the following command:

gpg --send-keys --keyserver pgp.mit.edu YOURKEYID

;;register

;;register <wot name> <pgp long id>
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.

Using the orderbook

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

;;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.

;;book

;;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 and ;;sell

;;buy <amount> <thing> [at|@] <priceperunit> <units> [<notes>]or;;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.

You can use arithmetic as well as a few macros to automatically adjust prices relative to mtgox usd. Use {mtgoxask} or {mtgoxbid} or {mtgoxlast}.