round-rb: A Ruby client for the Gem API

The round client is designed to interact with Gem's API to make building blockchain apps drop dead simple. All the complexity of the bitcoin protocol and crypto has been abstracted away so you can focus on building your product. Here are a few of the many great things the API and clients provide:

• Multi-signature wallets with Gem as a cosigner
• Webhook notifications automatically subscribed for you
• Integrated 2FA solution with arbitrary endpoints to build into your app
• Simplified balance inqueries
• Easy address management
• Hardware Security Modules for co-signing key
• Rules engine for transactions
• SDKs for many popular languages

• Support email: support@gem.co
• Issues: Use github issues
• Support Slack room:
• Detailed API Docs: Gem API Docs

• Ruby 2.1.5

• Introduction
• 1. Run the client
• 2. Configure your application and API token
• 3. Create your User and Wallet
• 4. Authenticate your User
• 5. Access the wallet and Default Account
• 6. Generate an Address and Add Funds
• 7. Make a Payment
• Advanced Topics
  • More about Wallets and Accounts
  • More about Transactions
  • Subscriptions
  • Integrated 2FA
  • Operational/Custodial/Business wallet models
  • Operational/Custodial/Business payments

This tutorial will have you run through setting up your application and creating your own wallet as a user of your application. By the end of the tutorial, you will have created your User, wallet, account, an address as well as fund it and then make a payment using the bitcoin testnet network.

This tutorial assumes that you have completed the developer signup and that you have successfully installed the client

In this step you will learn how to instantiate the API client for the given networks.

1. start your favorite interactive shell and import the round library

   $ irb
   > require 'round'

2. Create the client object.

client = Round.client ```

[top]

In this step your application and you will retrieve the API Token for the application and set your applications redirect url. The url is used to push the user back to your app after they complete an out of band challenge.

1. In the console copy your api_token by clicking on show

2. Go back to your shell session and set a variable for api_token

   api_token = 'q234t09ergoasgr-9_qt4098qjergjia-asdf2490'

[top]

In this step you will create your own personal Gem user and wallet authorized on your application. This is an end-user account, which will have a 2-of-3 multisig bitcoin wallet.

1. Authenticate your client

   client.authenticate_identify(api_token: api_token)

2. Create your user and wallet:

   #  Store the device token for future authentication
   device_token = client.users.create(
                     first_name: 'YOUR FIRST NAME',
                     last_name: 'YOUR LAST NAME',
                     email: 'YOUR EMAIL ADDRESS',
                     passphrase: 'aReallyStrongPassphrase',
                     device_name: 'SOME DEVICE NAME',
                     redirect_uri: 'http://something.com/user-device-approved')
                   )

3. Your application should store the device_token permanently as this will be required to authenticate from your app as this user.

4. You (acting as a user) will receive an email from Gem asking you to confirm your account and finish setup. Please follow the instructions. At the end of the User sign up flow, you'll be redirected to the redirect_uri provided in users.create (if you provided one).

[top]

In this step you will learn how to authenticate to the Gem API on a User's device to get a fully functional User object with which to perform wallet actions.

1. Call the authenticate_device method from the client object

   full_user = client.authenticate_device(
               api_token: api_token,
               device_token: device_token,
               email: email
             )

[top]

Wallets and Accounts

1. Get the wallet and then default account

   my_account = full_user.wallet.accounts['default']

[top]

In this section you'll learn how to create an address to fund with testnet coins aka funny money.

1. Create an address

   address = my_account.addresses.create
   puts address.string

puts address.path ```

1. Copy the address string and go to a faucet to fund it:
   1. TP's TestNet Faucet
   2. Mojocoin Testnet3 Faucet

Payments have to be confirmed by the network and on Testnet that can be slow. To monitor for confirmations: input the address into the following url https://live.blockcypher.com/btc-testnet/address/<YOUR ADDRESS>. The current standard number of confirmations for a transaction to be considered safe is 6.

You will be able to make a payment on a single confirmation. While you wait for that to happen, feel free to read more details about: Wallets and Accounts

[top]

In this section you’ll learn how to create a payment a multi-signature payment in an HD wallet. Once your address gets one more more confirmations we’ll be able to send a payment out of the wallet. To make a payment, you'll unlock a wallet, generate a list of payees and then call the pay method.

1. Unlock the wallet:

   my_account.wallet.unlock(<YOUR PASSWORD>)

2. Make a payment

   transaction = my_account.pay([{address: 'mxzdT4ShBudVtZbMqPMh9NVM3CS56Fp11s', amount: 25000}], 1, 'http://some-redirect-uri.com/')

puts transaction.mfa_uri # redirect your user to this URI to complete payment! ```

The pay call takes a list of payee objects. A payee is a hash of {address: ADDRESS, amount: amount} where address is the bitcoin address and amount is the number of satoshis. utxo_confirmations default to 6 and represents the number of confirmations an unspent output needs to have in order to be selected for the transaction.
The last argument is the redirect uri for Gem to send the user back to your application after the user submits their MFA challenge.

CONGRATS - now build something cool.

[top]